תחילת העבודה עם Apigee Extension Processor

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

בדף הזה מוסבר איך להגדיר את Apigee Extension Processor כדי לאכוף מדיניות API על תעבורת API באמצעות מאזן עומסים שמופעל בו Service Extensions.

במאמר הזה מוסבר על תרחישי השימוש המומלצים ב-Apigee Extension Processor לניהול API ועל היתרונות של השימוש בו.

מעבד התוספים של Apigee הוא תוסף לתעבורת נתונים (סוג של Service Extensions) שמאפשר לכם להשתמש ב-Cloud Load Balancing כדי לשלוח קריאות מנתיב עיבוד הנתונים של מאזן העומסים של האפליקציה למעבד התוספים של Apigee. אחרי שמגדירים את מאזן העומסים ואת תוסף התנועה, מאזן העומסים מעבד את תנועת ה-API. כללי המדיניות במעבד התוספים של Apigee חלים על תנועת נתונים ב-API באמצעות קריאות להרחבת תנועת נתונים.

בקטעים הבאים מוסבר איך להגדיר את רכיבי המפתח של Apigee Extension Processor:

• הגדרת מאזן עומסים לשירות קצה עורפי.
• הגדרת מעבד התוספים של Apigee
• הגדרת תוסף התנועה
• שימוש במדיניות עם מעבד התוספים.

לפני שמתחילים

לפני שמתחילים להגדיר את Apigee Extension Processor, צריך לבצע את המשימות הבאות:

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Apigee, Compute Engine, and Network Services APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. מתקינים את Google Cloud CLI.

   אחרי שמתקינים את Google Cloud CLI, מריצים את הפקודה gcloud components update כדי לקבל את הרכיבים האחרונים של gcloud.

2. אם עדיין לא עשיתם זאת, צריך להקצות מופע של Apigee באמצעות גרסה 1-15-0-apigee-2 ואילך.

   אפשר לראות את גרסאות המופעים בדף Instance details בממשק המשתמש של Apigee במסוף Google Cloud . נכנסים לדף Instances במסוף Google Cloud כדי לבחור מופע ולהציג את הפרטים שלו:

   כניסה לדף Instances

   אפשר להשתמש ב-Extension Processor עם ארגון Apigee במינוי או בPay-as-you-go. אם אתם לא בטוחים אם אתם משתמשים בארגון Apigee עם מינוי או עם תשלום לפי שימוש, פנו לאדמין של ארגון Apigee שלכם. פרטים נוספים על הקצאת מופעים בתשלום של Apigee זמינים במאמר לפני שמתחילים.

3. מוודאים ש VPC ורשת משנה מופעלים במופע Apigee שמתכננים להשתמש בו. עוברים לדף VPC Networks במסוף Google Cloud :

   כניסה אל VPC Networks

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות להתקנת Apigee Extension Processor, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

• יצירה וניהול של חשבונות שירות: אדמין של חשבון שירות (roles/iam.serviceAccountAdmin) בארגון
• ליצור ולנהל הרחבות שירות: אדמין של הרחבות שירות (roles/networkservices.serviceExtensionsAdmin) בארגון
• יצירה וניהול של קבוצות נקודות קצה ברשת (NEGs): אדמין מכונות של Compute (roles/compute.instanceAdmin) בארגון
• ליצור ולנהל משאבי רשת: אדמין של רשת מחשוב (roles/compute.networkAdmin) בארגון
• כדי ליצור ולנהל שירותים לקצה העורפי: אדמין של מאזן עומסים ב-Compute (roles/compute.loadBalancerAdmin) בארגון
• ליצור ולנהל משאבי Apigee: אדמין ארגוני ב-Apigee (roles/apigee.admin) בארגון
• ליצור ולנהל תוספים של תנועה: אדמין של תוסף שירות Apigee APIM (roles/apigee.apimServiceExtensionAdmin) בארגון
• כדי להציג תוספים של תנועה: צפייה בתוספים של שירות Apigee APIM (roles/apigee.apimServiceExtensionViewer) בארגון
• ניהול פעולות ממושכות: Apigee APIM Service Extension Service Agent (roles/apigee.apimServiceExtensionServiceAgent) בסוכן השירות בפרויקט Google Cloud

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

הגדרה של משתני סביבה

בפרויקט Google Cloud שמכיל את מופע Apigee, משתמשים בפקודה הבאה כדי להגדיר משתני סביבה:

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET

כאשר:

• ‫PROJECT_ID הוא מזהה הפרויקט עם מופע Apigee.
• ‫REGION הוא האזור של מופע Apigee. Google Cloud
• ‫INSTANCE הוא השם של מופע Apigee.
• ‫VPC_NETWORK_NAME הוא השם של רשת ה-VPC בפרויקט Google Cloud שבה רוצים להשתמש עבור מעבד התוספים של Apigee.
• ‫SUBNET הוא שם רשת המשנה בפרויקט Google Cloud שרוצים להשתמש בה עבור מעבד התוספים של Apigee.

כדי לוודא שמשתני הסביבה מוגדרים בצורה נכונה, מריצים את הפקודה הבאה ובודקים את הפלט:

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET

הגדרת טוקן אימות

כדי להגדיר אסימון אימות, מריצים את הפקודה הבאה:

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

הגדרת מאזן עומסים לשירות קצה עורפי

בקטעים הבאים מוסבר איך להגדיר מאזן עומסים גלובלי חיצוני של אפליקציות לשירות קצה עורפי, באמצעות httpbin.org כדוגמה:

1. יצירת מאזן עומסים גלובלי חיצוני של אפליקציות
2. יצירת קבוצת נקודות קצה ברשת (NEG)
3. יצירת שירות לקצה העורפי.
4. יצירת מפת URL.
5. יצירת שרת proxy ליעד
6. יצירת כלל גלובלי להעברה

יצירת מאזן עומסים גלובלי חיצוני של אפליקציות (ALB)

כדי ליצור את מאזן העומסים:

1. מגדירים את gcloud כך שישתמש בפרויקט הנוכחי:

   gcloud config set project PROJECT_ID

   כאשר PROJECT_ID הוא מזהה הפרויקט עם מופע Apigee.

2. יוצרים כתובת IP סטטית גלובלית:

   gcloud compute addresses create IP_ADDRESS --ip-version=IPV4 --global

   כאשר IP_ADDRESS הוא שם כתובת ה-IP שרוצים ליצור. השם חייב להתאים לביטוי הרגולרי (?:a-z?).

3. מקבלים את כתובת ה-IP ושומרים אותה כמשתנה סביבה:

   IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)

   ‫IP_ADDRESS הוא שם כתובת ה-IP שיצרתם בשלב הקודם.

4. יוצרים אישור TLS עבור nip.io, שירות צד שלישי שמספק רשומות DNS עם תווים כלליים לכתובות IP:

   gcloud compute ssl-certificates create SSL_CERT_NAME \
     --domains="nip.io"

   כאשר SSL_CERT_NAME הוא שם האישור שרוצים ליצור.

יצירת קבוצת נקודות קצה ברשת (NEG)

כדי ליצור את קבוצת נקודות הקצה ברשת (NEG) עבור מאזן העומסים:

1. כדי ליצור NEG:

   gcloud compute network-endpoint-groups create NEG_NAME \
     --network-endpoint-type=INTERNET_FQDN_PORT \
     --default-port=443 \
     --global

   כאשר NEG_NAME הוא השם של קבוצת ה-NEG שרוצים ליצור.

2. מוסיפים את נקודת הקצה של httpbin.org ל-NEG:

   gcloud compute network-endpoint-groups update NEG_NAME \
     --add-endpoint=fqdn=httpbin.org,port=443 \
     --global

   כאשר NEG_NAME הוא השם של קבוצת ה-NEG שיצרתם בשלב הקודם.

יצירת שירות לקצה העורפי

כדי ליצור את השירות לקצה העורפי שנחשף על ידי מאזן העומסים:

1. יוצרים את שירות הקצה העורפי:

   gcloud compute backend-services create BACKEND_SERVICE_NAME \
     --load-balancing-scheme=EXTERNAL_MANAGED \
     --protocol=HTTPS \
     --global

   מחליפים את BACKEND_SERVICE_NAME בשם של שירות ה-Backend שרוצים ליצור.

2. מוסיפים את ה-NEG לחלק האחורי:

   gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
     --network-endpoint-group=NEG_NAME \
     --global-network-endpoint-group \
     --global

   כאשר:

   • ‫BACKEND_SERVICE_NAME הוא השם של שירות ה-Backend שיצרתם בשלב הקודם.
   • ‫NEG_NAME הוא השם של קבוצת ה-NEG שיצרתם בשלב הקודם.

יצירת מפת URL

כדי ליצור מפת URL בין מאזן העומסים לבין שירות הקצה העורפי, משתמשים בפקודה הבאה:

gcloud compute url-maps create URL_MAP_NAME \
  --default-service BACKEND_SERVICE_NAME \
  --global

כאשר:

• ‫URL_MAP_NAME הוא השם של מפת ה-URL שרוצים ליצור.
• ‫BACKEND_SERVICE_NAME הוא השם של שירות הלקצה העורפי שיצרתם בשלב הקודם.

יצירת שרת proxy ליעד

כדי ליצור שרת proxy ליעד בשביל מאזן העומסים כדי לעבד תעבורה של תוסף שירות, משתמשים בפקודה הבאה:

gcloud compute target-https-proxies create TARGET_PROXY_NAME \
  --global \
  --ssl-certificates SSL_CERT_NAME \
  --global-ssl-certificates \
  --url-map URL_MAP_NAME \
  --global-url-map

כאשר:

• ‫TARGET_PROXY_NAME הוא שם ה-proxy של היעד שרוצים ליצור.
• ‫URL_MAP_NAME הוא השם של מפת ה-URL שיצרתם בשלב הקודם.
• ‫SSL_CERT_NAME הוא השם של אישור ה-SSL שיצרתם בשביל nip.io בשלב הקודם.

יצירת כלל העברה גלובלי

כדי ליצור כלל העברה גלובלי למאזן העומסים, משתמשים בפקודה הבאה:

gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --network-tier=PREMIUM \
  --address=IP_ADDRESS \
  --target-https-proxy=TARGET_PROXY_NAME \
  --ports=443 \
  --global

כאשר:

• ‫FORWARDING_RULE_NAME הוא שם כלל ההעברה שרוצים ליצור.
• ‫IP_ADDRESS הוא שם כתובת ה-IP של נקודת הקצה של ה-NEG שיצרתם בשלב הקודם.
• ‫TARGET_PROXY_NAME הוא השם של שרת ה-Proxy של היעד שמטפל בתנועה של התוסף.

הגדרת מעבד התוספים של Apigee

בקטעים הבאים מוסבר איך מגדירים את Apigee Extension Processor:

1. יצירת סביבת Apigee
2. יצירת שרת proxy של מעבד התוסף.

יצירת סביבת Apigee

הערה: לפני שיוצרים סביבה חדשה וקבוצת סביבות חדשה, או משתמשים במשאבים קיימים בשלב הזה, כדאי לעיין במגבלות על סביבות, קבוצות סביבות ו-API Proxy בהגדרות של Extension Processor. מידע נוסף מופיע בקטע מגבלות.

1. יוצרים סביבת Apigee באמצעות הפקודה הבאה:

   curl -i -X POST -H  "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments" -H "Content-Type:application/json" -d \
       '{
           "name": "ENV_NAME",
           "displayName": "ENV_NAME",
           "state": "ACTIVE",
           "deploymentType": "PROXY",
           "apiProxyType": "PROGRAMMABLE",
           "type": "COMPREHENSIVE",
           "properties":
           {"property": [
               {
               "name": "apigee-service-extension-enabled",
               "value": "true"
               }
             ]
           }
       }'

   ‫ENV_NAME הוא השם של הסביבה שאתם יוצרים. השם צריך לכלול בין 2 ל-32 תווים, שיכולים להיות אותיות קטנות, מספרים או מקפים. השם חייב להתחיל באות ולא יכול להסתיים במקף. השם צריך להיות שונה מכל שם אחר של סביבה בארגון.

   בודקים שהסביבה נוצרה:

   curl -i -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"

   הרשימה של הסביבות צריכה לכלול את הסביבה שיצרתם.

2. מצרפים את הסביבה החדשה שנוצרה למופע Apigee:

   curl -i -X POST -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances/$INSTANCE/attachments" -H "Content-Type:application/json" -d \
       '{
           "environment": "ENV_NAME"
           }'

   ‫ENV_NAME הוא שם הסביבה שיצרתם בשלב הקודם.

   הפעולה הזו עשויה להימשך עד 10 דקות.

3. יוצרים את קבוצת הסביבות של Apigee:

   curl -H "Authorization: Bearer $TOKEN" -X POST \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups" -H "Content-Type:application/json" -d \
       '{
           "name": "ENV_GROUP_NAME",
           "hostnames": ["ENV_GROUP_HOSTNAME"]
           }'

   כאשר:

   • ‫ENV_GROUP_NAME הוא שם קבוצת הסביבות שאתם יוצרים.
   • ‫ENV_GROUP_HOSTNAME הוא שם המארח של קבוצת הסביבות שאתם יוצרים. שם המארח חייב להיות שם דומיין שמוגדר במלואו (FQDN).
     הערה: שם המארח לא צריך להיות ניתן לפענוח.
4. מצרפים את הסביבה החדשה לקבוצת הסביבות החדשה:

   curl -H "Authorization: Bearer $TOKEN" -X POST\
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups/ENV_GROUP_NAME/attachments" -H "content-type:application/json" -d \
           '{
               "name": "ENV_GROUP_NAME",
               "environment": "ENV_NAME"
           }' 

   כאשר:

   • ‫ENV_GROUP_NAME הוא שם קבוצת הסביבות שאתם יוצרים.
   • ‫ENV_NAME הוא שם הסביבה שיצרתם בשלב קודם.

יצירת שרת proxy של מעבד התוסף

שרת ה-proxy של Extension Processor הוא proxy ל-API של Apigee שמשמש להחלת מדיניות ניהול API על תעבורת הנתונים במאזן העומסים. אפשר ליצור שרת proxy ללא יעד או שרת proxy עם הפעלה של אירועים שנשלחים מהשרת (SSE). מידע נוסף על שימוש ב-SSE עם Apigee זמין במאמר בנושא אירועים שנשלחים מהשרת.

כדי ליצור proxy ל-API של Apigee לשימוש עם מאזן העומסים של Extension Processor:

אין שרת proxy יעד

1. פועלים לפי השלבים במאמר יצירת proxy ל-API כדי ליצור שרת proxy מסוג No target עם המפרט הבא:
   • תבנית proxy: בוחרים באפשרות No target (ללא יעד).
   • שם ה-proxy: מזינים שם ל-proxy. השם הזה ישמש כמזהה של מעבד התוספים.
   • נתיב בסיסי: מגדירים נתיב בסיסי כלשהו. לא נעשה שימוש בנתיב.

   מפרט ה-XML של ה-proxy אמור להיראות כך:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <APIProxy revision="1" name="extproc-sample">
       <DisplayName/>
       <Description/>
       <CreatedAt>1739581781912</CreatedAt>
       <LastModifiedAt>1739582447868</LastModifiedAt>
       <BasePaths>/</BasePaths>
       <Policies></Policies>
       <ProxyEndpoints>
           <ProxyEndpoint>default</ProxyEndpoint>
       </ProxyEndpoints>
   </APIProxy>

2. פועלים לפי השלבים במאמר פריסת proxy ל-API כדי לפרוס את ה-proxy בסביבה שיצרתם קודם.

שרת proxy עם SSE

1. פועלים לפי השלבים במאמר יצירת proxy ל-API כדי ליצור פרוקסי של אירוע שנשלח מהשרת עם המפרט הבא:
   • תבנית proxy: בוחרים באפשרות No target (ללא יעד).
   • שם ה-proxy: מזינים שם ל-proxy.
   • נתיב בסיסי: מגדירים נתיב בסיסי כלשהו. לא נעשה שימוש בנתיב.

   מפרט ה-XML של ה-proxy אמור להיראות כך:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <APIProxy revision="1" name="extproc-sample">
       <DisplayName/>
       <Description/>
       <CreatedAt>1739581781912</CreatedAt>
       <LastModifiedAt>1739582447868</LastModifiedAt>
       <BasePaths>/</BasePaths>
       <ProxyEndpoints>
           <ProxyEndpoint>default</ProxyEndpoint>
       </ProxyEndpoints>
   </APIProxy>

2. מגדירים את EventFlow בשרת ה-proxy:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <APIProxy revision="1" name="extproc-sample">
       <DisplayName/>
       <Description/>
       <CreatedAt>1739581781912</CreatedAt>
       <LastModifiedAt>1739582447868</LastModifiedAt>
       <BasePaths>/</BasePaths>
       <ProxyEndpoints>
           <ProxyEndpoint>default</ProxyEndpoint>
           <EventFlow name="EventFlow" content-type="text/event-stream">
             <Response/>
           </EventFlow>
           <HTTPProxyConnection>
             <Properties/>
             <URL>https://httpbin.org/sse</URL>
           </HTTPProxyConnection>
       </ProxyEndpoints>
   </APIProxy>

3. פועלים לפי השלבים במאמר פריסת proxy ל-API כדי לפרוס את ה-proxy בסביבה שיצרתם קודם.

הגדרת תוסף התנועה

בקטע הזה מוסבר איך להגדיר את תוסף שירות התנועה למעבד התוספים, באמצעות השלבים הבאים:

1. יצירת תוסף התנועה באמצעות Extension Processor provisioning API
2. שליחת בקשה למאזן העומסים.

יצירת תוסף התנועה באמצעות Extension Processor provisioning API

בשלב הזה, יוצרים תוסף של שירות תנועה למעבד התוספים באמצעות Extension Processor provisioning API.

כדי ליצור את תוסף התנועה, מפעילים את Extension Processor provisioning API באמצעות הפקודה הבאה:

curl -X POST -H  "Authorization: Bearer $TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions?apimServiceExtensionId=TRAFFIC_EXT_NAME \
    -H "Content-Type:application/json" -d \
    '{
      "extensionProcessor": "TARGET_PROXY_NAME"
      "lbForwardingRule": "LB_FORWARDING_RULE",
      "network" : "NETWORK",
      "networkConfigs": [
        {
          "region": "$REGION",
          "subnet": "project/my-project/regions/$REGION/subnetworks/$SUBNET"
        }
      ],
      "extensions": [
        {
          "name": "TARGET_PROXY_NAME",
          "matchCondition": "CEL_EXPRESSION",
          "failOpen": FAIL_OPEN,
          "hostname": "ENV_GROUP_HOSTNAME",
          "supportedEvents": [
            "REQUEST_HEADERS",
            "RESPONSE_HEADERS"
          ]
        }
      ]
    }'

כאשר:

• ‫TRAFFIC_EXT_NAME הוא שם התוסף לניתוח תנועה שאתם יוצרים.
• ‫LB_FORWARDING_RULE הוא השם של כלל ההעברה שיצרתם בשלב קודם.
• ‫NETWORK הוא שם הרשת שיצרתם בשלב קודם.
• ‫TARGET_PROXY_NAME הוא שם שרת ה-Proxy שמטפל בתנועה של התוסף.
• ‫CEL_EXPRESSION הוא הביטוי ב-Common Expression Language ‏ (CEL) שבו רוצים להשתמש להרחבת התנועה. למידע נוסף על התחביר של CEL, אפשר לעיין בהפניה לשפת ההתאמה של CEL.
• ‫FAIL_OPEN הוא ערך בוליאני שקובע אם תוסף התנועה נכשל במצב פתוח או סגור. הערכים התקינים הם true או false.
• ‫ENV_GROUP_HOSTNAME הוא שם המארח של קבוצת הסביבות שיצרתם בשלב קודם.

הערה: אחרי שיוצרים את תוסף התנועה, אי אפשר לשנות את השדות name, lbForwardingRule ו-network.

הפעולה הזו עשויה להימשך כמה דקות.

קבלת פרטים על תוסף תנועה

כדי לוודא שיצרתם את התוסף של שירות התנועה בהצלחה, משתמשים בפקודה הבאה:

curl -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME"

מחליפים את TRAFFIC_EXT_NAME בשם של תוסף התנועה שיצרתם.

התגובה תיראה כך:

{
  "name": "my-traffic-extension",
  "extensionProcessor": "my-extension-processor",
  "lbForwardingRule": "https://www.googleapis.com/compute/v1/projects/my-project/global/forwardingRules/my-forwarding-rule",
  "network": "projects/my-project/global/networks/my-network",
  "networkConfigs": [
    {
      "region": "us-west1",
      "subnet": "projects/my-project/regions/us-west1/subnetworks/my-subnet"
    }
  ],
  "extensions": [
    {
      "name": "organizations/my-org/apis/my-api-proxy",
      "matchCondition": "request.url.contains('1234567890')",
      "failOpen": true,
      "hostname": "my-hostname.apigee.net",
      "supportedEvents": [
        "REQUEST_HEADERS",
        "RESPONSE_HEADERS"
      ]
    }
  ]
}

עדכון תוסף של תנועה

אפשר לעדכן את תוסף התנועה באמצעות הפרמטר updateMask. כשמשתמשים בפרמטר updateMask, מציינים את המאפיינים של המשאב שרוצים לעדכן באמצעות רשימה מופרדת בפסיקים. המאפיינים הנתמכים של updateMask הם:

• ‫networkConfigs: עדכונים בשדות region ו-subnet.
  הערה: אפשר לעדכן את השדה הזה רק עבור מאזני עומסים של אפליקציות גלובליות. במקרה של מאזני עומסים של אפליקציות אזוריים, אי אפשר לעדכן את networkConfigs. כדי לשנות את הגדרות הרשת, צריך למחוק את התוסף וליצור אותו מחדש.
• ‫extensions: מעדכן את השדות name,‏ matchCondition,‏ failOpen,‏ hostname ו-supportedEvents.
• ‫extensionProcessor: מעדכן את השדה extensionProcessor.

כדי לעדכן תוסף תנועה, משתמשים בפקודה curl עם ה-method ‏PATCH. אפשר לעדכן כמה מאפיינים על ידי הכללתם בפרמטר השאילתה updateMask כמחרוזת מופרדת בפסיקים (לדוגמה, ?updateMask=extensions,extensionProcessor).

הנה כמה דוגמאות:

עדכון של networkConfigs (איזון עומסים גלובלי)

כדי לעדכן את המאפיינים של networkConfigs, משתמשים בפקודה הבאה:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=networkConfigs \
  -H "Content-Type:application/json" -d \
  '{
    "networkConfigs": [
      {
        "region": "REGION",
        "subnet": "projects/$PROJECT/regions/REGION/subnetworks/SUBNET"
      }
    ]
  }'

כאשר:

• ‫TRAFFIC_EXT_NAME הוא השם של התוסף Extension Processor traffic שרוצים לעדכן.
• ‫REGION הוא האזור של האזור המעודכן.
• ‫SUBNET היא רשת המשנה החדשה של הרשת.

לעדכון extensions

כדי לעדכן את המאפיינים של extensions, משתמשים בפקודה הבאה:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ]
  }'

כאשר:

• ‫TRAFFIC_EXT_NAME הוא השם של התוסף Extension Processor traffic שרוצים לעדכן.
• ‫TARGET_PROXY_NAME הוא שם שרת ה-Proxy שמטפל בתנועה של התוסף.
• ‫NEW_CEL_EXPRESSION הוא ביטוי ה-CEL המעודכן.
• ‫NEW_FAIL_OPEN הוא הערך הבוליאני המעודכן של fail open.
• ‫NEW_ENV_GROUP_HOSTNAME הוא שם המארח של קבוצת הסביבות.

לעדכון extensionProcessor

כדי לעדכן את המאפיינים של extensionProcessor, משתמשים בפקודה הבאה:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

כאשר:

• ‫TRAFFIC_EXT_NAME הוא השם של התוסף Extension Processor traffic שרוצים לעדכן.
• ‫NEW_TARGET_PROXY_NAME הוא השם החדש של שרת ה-proxy שמטפל בתנועה של התוסף.

עדכון של כמה מאפיינים (מאזן עומסים גלובלי)

כדי לעדכן את המאפיינים extensions ו-extensionProcessor בו-זמנית, משתמשים בפקודה הבאה:

curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions,extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN,
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ],
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

כאשר:

• ‫TRAFFIC_EXT_NAME הוא השם של התוסף Extension Processor traffic שרוצים לעדכן.
• ‫TARGET_PROXY_NAME הוא שם שרת ה-Proxy שמטפל בתנועה של התוסף.
• ‫NEW_CEL_EXPRESSION הוא ביטוי ה-CEL המעודכן.
• ‫NEW_FAIL_OPEN הוא הערך הבוליאני המעודכן של fail open.
• ‫NEW_ENV_GROUP_HOSTNAME הוא שם המארח של קבוצת הסביבות.
• ‫NEW_TARGET_PROXY_NAME הוא השם החדש של שרת ה-proxy שמטפל בתנועה של התוסף.

שליחת בקשה למאזן העומסים

כדי לבדוק את ההגדרה של מאזן העומסים ושל מעבד התוספים, שולחים בקשה למאזן העומסים:

curl "https://LB_DOMAIN_NAME/get"

כאשר LB_DOMAIN_NAME הוא שם הדומיין שבו השתמשתם למאזן העומסים ולאישור ה-SSL. אם השתמשתם ב-nip.io, שם הדומיין ייראה בערך כך: IP_ADDRESS.nip.io.

התגובה תיראה כך:

{"status": 200,
  {
    "args": {},
    "headers": {
      ...
    },
    "origin": "173.93.50.108",
    "url": "https://httpbin.org/get"
  }
}

שימוש במדיניות עם מעבד התוספים

בקטע הזה מוסבר איך להשתמש במדיניות עם מעבד התוספים.

בדוגמה הזו, מגדירים מדיניות VerifyAPIKey ו-AssignMessage עבור Extension Processor. המדיניות הזו מאמתת מפתחות API שכלולים בבקשות ל-Apigee ומזריקה טוקן Googleלכותרות של בקשות לקריאות לשירות לקצה העורפי. התרחיש הזה שימושי לספקי API שמשתמשים ב-Apigee Extension Processor כדי להעניק הרשאה ולבצע אימות של בקשות לשירותי Apigee שלהם, ולהזריק בצורה חלקה את טוקני האימות שלGoogle שנדרשים לשירות לקצה העורפי כמו Vertex AI.

הוספה של מדיניות VerifyAPIKey לאימות מפתח API

בקטעים הבאים מוסבר איך להשתמש במדיניות VerifyAPIKey כדי לאמת מפתחות API לקריאות לשירות הקצה העורפי באמצעות Extension Processor:‏

1. מצרפים את מדיניות VerifyAPIKey ל-Extension Processor.
2. יוצרים מוצר API.
3. יוצרים אפליקציה למפתחים ופרטי כניסה לאפליקציה.
4. שולחים בקשה למאזן העומסים באמצעות מפתח ה-API.

צירוף המדיניות VerifyAPIKey לשרת ה-proxy

כדי לצרף מדיניות VerifyAPIKey לשרת ה-proxy של Extension Processor:

1. במסוף Google Cloud , נכנסים לדף Apigee > Proxy Development > API Proxies.

   מעבר אל API Proxies

2. בוחרים את ה-proxy של מעבד התוספים שיצרתם בקטע יצירת מעבד תוספים.
3. לוחצים על הכרטיסייה פיתוח.
4. בחלונית הניווט, לוחצים על בקטע Policies (מדיניות).
5. בתיבת הדו-שיח Create policy, בוחרים באפשרות VerifyAPIKey מתוך רשימת המדיניות.
6. בחלונית VerifyAPIKey, ממלאים את שדות החובה בקטעים Name [שם] ו-Display name [שם לתצוגה] באמצעות הערכים הבאים:
   • שם: מזינים שם למדיניות. לדוגמה, VA-verify-api-key.
   • השם המוצג: מזינים את שם המדיניות לשימוש בממשק המשתמש. לדוגמה, VA-verify-api-key.
7. לוחצים על יצירה.

   מפרט ה-XML של המדיניות VerifyAPIKey שכלולה בשרת ה-proxy של Extension Processor צריך להיראות בערך כך:

     <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <VerifyAPIKey continueOnError="false" enabled="true" name="VA-verify-api-key">
       <DisplayName>VA-verify-api-key</DisplayName>
       <Properties/>
       <APIKey ref="request.queryparam.x-api-key"/>
     </VerifyAPIKey>

8. פורסים את הגרסה החדשה של ה-proxy.

יצירת מוצר API

כדי ליצור מוצר API ולהגדיר את קבוצת פעולות ה-API בשירות:

1. פועלים לפי השלבים במאמר יצירת מוצר API כדי ליצור מוצר API לשירות. אתם יכולים להגדיר את פרטי המוצר של מוצר ה-API איך שאתם רוצים.
2. פועלים לפי השלבים שבקטע פעולות כדי להוסיף קבוצה של פעולות API למוצר ה-API, בהתאם למפרטים הבאים:
   • מקור:

     במסוף Google Cloud , נכנסים לדף Apigee > Distribution > API Products.

     מעבר אל API Products

     בוחרים את מוצר ה-API שיצרתם בשלב קודם.
   • פעולה: לוחצים על עריכה ומגדירים את הנתיבים והשיטות הבאים:
     • נתיב: /get עם שיטה: GET
     • נתיב: /TARGET_PROXY_NAME עם שיטה: GET

       ‫TARGET_PROXY_NAME הוא שם שרת ה-Proxy שמטפל בתנועה של התוסף.

יצירת אפליקציה ופרטי כניסה לאפליקציה למפתחים

כדי ליצור אפליקציה למפתחים ואמצעי אימות לאפליקציה עבור מוצר ה-API החדש:

1. נכנסים לדף Apigee API management במסוף Google Cloud :

   Apigee API management

2. יצירת מפתח:
   1. בוחרים באפשרות הפצה > מפתחים.
   2. בדף מפתחים, לוחצים על + יצירה.
   3. בדף Add developer (הוספת מפתח), ממלאים את שדות החובה בכל ערך שרוצים.
   4. לוחצים על הוספה.
3. יצירת אפליקציה:
   1. בוחרים באפשרות הפצה> אפליקציות.
   2. בדף אפליקציות, לוחצים על + יצירה.
   3. בדף Create App (יצירת אפליקציה), ממלאים את שדות החובה בקטע App Details (פרטי האפליקציה) באמצעות הערכים הבאים:
      • שם האפליקציה: מזינים שם לאפליקציה. לדוגמה, ext-proc-app
      • מפתח: בוחרים את המפתח שיצרתם בשלב הקודם או מפתח אחר מהרשימה.
   4. בקטע App Credentials (פרטי כניסה לאפליקציה), לוחצים על + Add Credential (+הוספת פרטי כניסה).
   5. בקטע פרטי הכניסה, בוחרים באפשרות לעולם לא מתיבת הרשימה תפוגה.
   6. בקטע מוצרים, לוחצים על + הוספת מוצרים כדי להציג את החלונית הוספת מוצרים.
   7. בוחרים את מוצר ה-API שיצרתם בשלב הקודם.
   8. לוחצים על OK.
   9. לוחצים על הוספה כדי לסגור את החלונית הוספת מוצרים.
   10. לוחצים על יצירה.
4. בדף פרטי האפליקציה, בקטע פרטי הכניסה, לוחצים על כדי להציג את הערך של המפתח.

   מעתיקים את הערך Key. תשתמשו במפתח הזה כדי לבצע קריאות ל-API של השירות בשלב מאוחר יותר.

5. בדף פרטי האפליקציה, בקטע פרטי הכניסה, לוחצים על כדי להציג את הערך של סוד האפליקציה.

שליחת בקשה למאזן העומסים באמצעות מפתח ה-API

כדי לבדוק את האימות של מפתח ה-API, שולחים בקשה למאזן העומסים באמצעות מפתח ה-API:

curl "https://LB_DOMAIN_NAME/get"

כאשר LB_DOMAIN_NAME הוא שם הדומיין שבו השתמשתם למאזן העומסים ולאישור ה-SSL.

התגובה נכשלת ללא מפתח API.

שולחים בקשה נוספת למאזן העומסים, באמצעות מפתח ה-API בבקשה:

curl "https://LB_DOMAIN_NAME/get?key=API_KEY"

כאשר:

• ‫LB_DOMAIN_NAME הוא שם הדומיין שבו השתמשתם למאזן העומסים ולאישור ה-SSL.
• ‫API_KEY הוא מפתח ה-API מפרטי הכניסה של אפליקציית המפתחים שנחשפו בשלב קודם.

התגובה מציינת שההרשאה לנקודת הקצה הצליחה. המשמעות היא שמעבד התוסף אימת את מפתח ה-API, ועכשיו ה-Proxy של Apigee יכול לעבד את הבקשה.

הוספת מדיניות AssignMessage לאימות Google

אם רוצים להשתמש ב-Extension Processor כדי לספק ניהול API לשירות שמאומת על ידי Google, אפשר להחדיר אסימון גישה של Google או אסימון מזהה של Google לבקשות שנשלחות לשירות לקצה העורפי באמצעות מדיניות AssignMessage.

בקטעים הבאים מוסבר איך להשתמש במדיניות AssignMessage כדי להוסיף אסימון אימות לבקשות שנשלחות לשירות לקצה העורפי באמצעות Extension Processor: Google

1. מצרפים את מדיניות AssignMessage לשרת ה-proxy.
2. שולחים בקשה למאזן העומסים כדי לבדוק את הוספת האסימון.

צירוף מדיניות AssignMessage לשרת ה-proxy

כדי להוסיף את מדיניות AssignMessage לשרת ה-proxy:

1. במסוף Google Cloud , נכנסים לדף Proxy Development > API Proxies.

   מעבר אל API Proxies

2. בוחרים את ה-proxy של מעבד התוספים שיצרתם בקטע יצירת מעבד תוספים.
3. לוחצים על הכרטיסייה פיתוח.
4. בחלונית הניווט, לוחצים על בקטע Policies (מדיניות).
5. בתיבת הדו-שיח Create policy, בוחרים באפשרות AssignMessage מתוך רשימת המדיניות.
6. בחלונית Assign Message (הקצאת הודעה), ממלאים את שדות החובה בקטעים Name (שם) ו-Display name (שם לתצוגה) באמצעות הערכים הבאים:
   • שם: מזינים שם למדיניות. לדוגמה, AM-auth.
   • שם לתצוגה: מזינים שם מדיניות שיוצג בממשק המשתמש. לדוגמה, AM-auth.
7. לוחצים על יצירה.
8. מתחת לרכיב <Set>, מוסיפים את רכיבי הצאצא הבאים:

   <Set>
       <Authentication>
       <HeaderName>Authorization</HeaderName>
       <GoogleAccessToken>
           <Scopes>
           <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
           </Scopes>
       </GoogleAccessToken>
       </Authentication>
   </Set>

9. לוחצים על Save.
10. פורסים את הגרסה החדשה באמצעות Google חשבון שירות.

חשבון השירות יוצר טוקנים של גישה ומזריק אותם לכותרת הבקשה עבור קריאות ל-API של שירותי הבק-אנד. Google Google

שליחת בקשה למאזן העומסים כדי לבדוק את הוספת האסימון

כדי לוודא שהוספת הטוקן פועלת, שולחים בקשה למאזן העומסים:

curl "https://LB_DOMAIN_NAME/get"

כאשר LB_DOMAIN_NAME הוא שם הדומיין שבו השתמשתם למאזן העומסים ולאישור ה-SSL.

התגובה תיראה כך:

{
  ...
  "headers": {
    "Accept": "*/*",
    "Authorization": "Bearer ya29.c.c0ASRK0Gbw03y9cfvxL11DxaRYBQUU18SmUP4Vu63OckHI5cX7wJ4DmGMG2vbDDS69HXJHqMj-lak4tcqOsJGmE65crn2gNuJLanXidwM8",
    "First": "1.0",
    "Host": "apigee-ext-proc-test.apigee.net",
    "Second": "1.0",
    "Sum": "2",
    "User-Agent": "curl/8.7.1",
    "X-Api-Key": "McYcHGR3PTSGLXExvKADwQ1JJeCjgPDUvAakCl0rJKCFaX0Y",
    "X-Cloud-Trace-Context": "0fd3dadc2a3c328fa968d5f5f1434c29/18300783092696918345"
  },
  ...
}

התגובה מראה שהאסימון לאימות Google הוחדר בהצלחה לכותרת הבקשה.

אחרי שהמדיניות AssignMessage מוחלת בהצלחה, הבקשה של הלקוח (שכוללת את מפתח ה-API) אל Apigee בתרחיש לדוגמה משתנה כך שתכלול אסימון אימות של Google בכותרת הבקשה, כפי שנדרש על ידי שירות הקצה העורפי שאומת באמצעות Google.