יצירת שרת proxy של API מתבנית YAML

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

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

בדף הזה מוסבר איך להגדיר שרת proxy של API כתבנית תכונה של Apigee ב-YAML ולפרוס אותו באמצעות Google Cloud CLI. קודם בונים פרוקסי פשוט, ואז בונים דוגמה מלאה יותר שמוצגת בחזית של מודל Gemini.

מידע נוסף זמין במאמר בנושא הגדרת שרת proxy באמצעות YAML. לסכימה המלאה, אפשר לעיין במאמר בנושא הפניית הגדרות YAML של שרת proxy ל-API.

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

  • מפעילים את Vertex AI API בפרויקט בענן ב-Google Cloud כדי שה-proxy יוכל לתקשר עם מודלים של Gemini. 
    gcloud services enable aiplatform.googleapis.com
  • מתקינים ומפעילים את Google Cloud CLI.
  • כדי לגשת לפקודות שמשמשות במדריך הזה, צריך להתקין את רכיב הבטא של gcloud: 
    gcloud components install beta
  • יש לכם ארגון Apigee ולפחות סביבה אחת. חשוב לשים לב לשמות הארגון והסביבה. בדוגמאות נעשה שימוש ב-ORG וב-ENV כמשתני מיקום. בנוסף, שער ה-AI בחלק 2 דורש סביבה מסוג Intermediate או Comprehensive (לא סביבה מסוג Base). מידע נוסף זמין במאמר סוגי סביבות ב-Apigee.
  • מוודאים שיש לכם את ההרשאות הנדרשות:
    • כדי לייבא (ליצור) proxy ל-API: התפקיד אדמין API (roles/apigee.apiAdmin) או תפקיד מקביל שמעניק את ההרשאה apigee.proxies.create.
    • כדי לפרוס פרוקסי של API: אדמין סביבות (roles/apigee.environmentAdmin) בסביבת היעד, וקורא API (roles/apigee.apiReaderV2) ברמת הפרויקט.
    • כדי ליצור את מוצר ה-API, המפתח והאפליקציה שמפיקים את מפתח ה-API בחלק 2, שלב 6: אדמין API (roles/apigee.apiAdmin) ואדמין מפתחים (roles/apigee.developerAdmin). לרשימה המלאה של התפקידים, אפשר לעיין בתפקידים ב-Apigee.

חלק 1: יצירת proxy ל-API

בקטע הזה יוצרים שרת proxy שמעביר בקשות לשירות היעד המדומה של Apigee ומחיל מגבלת קצב.

שלב 1: יצירת התבנית

תבנית היא הקובץ שפורסים. הוא מגדיר את נתיב הבסיס, המסלולים ויעד ה-backend של ה-proxy, ומפרט את התכונות שצריך לכלול.

יוצרים ספרייה בשביל ה-proxy, ואז יוצרים קובץ בשם hello-proxy.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: hello-proxy
type: template
description: A simple proxy to the Apigee mock target, protected by a rate limit.
features:
- spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

התבנית הזו מגדירה:

  • נקודת קצה עם נתיב הבסיס /hello. לקוחות קוראים ל-proxy בנתיב הזה.
  • מסלול ששולח בקשות ליעד בשם default.
  • יעד שמפנה לכתובת ה-URL של ה-Backend.
  • תכונה, spike-arrest.yaml, שתיצור בהמשך.

שלב 2: יוצרים את התכונה

תכונה היא יחידת הגדרה שאפשר להשתמש בה שוב ושוב ומכילה מדיניות. תבנית לא יכולה להכיל מדיניות ישירות, ולכן מדיניות הגבלת הקצב נמצאת בתכונה.

באותה תיקייה שבה נמצאת התבנית, יוצרים קובץ בשם spike-arrest.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: spike-arrest
displayName: Spike Arrest
type: feature
description: Protects the backend by smoothing traffic spikes.
categories:
- traffic
parameters:
- name: RATE
  displayName: RATE
  description: Maximum request rate, for example 30ps (per second) or 100pm (per minute).
  default: 30ps
  examples:
  - 30ps
  - 100pm
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: SA-SpikeArrest
policies:
- name: SA-SpikeArrest
  type: SpikeArrest
  content:
    SpikeArrest:
      metadata:
        name: SA-SpikeArrest
        enabled: "true"
        continueOnError: "false"
      DisplayName: SA-SpikeArrest
      Rate: "{RATE}"

פרטים לגבי התכונה:

  • מגדיר מדיניות SpikeArrest שמגבילה את קצב הבקשות.
  • משתמשים ב-defaultEndpoint.flows כדי להוסיף את המדיניות לבקשה PreFlow, כך שהיא תופעל בכל בקשה.
  • ההצהרה על פרמטר, ‏ RATE, שברירת המחדל שלו (30ps) מוחלפת ב-{RATE} כשקובץ ה-proxy עובר קומפילציה.

שלב 3: מייבאים את ה-proxy

מייבאים את התבנית כדי ליצור תיקון של פרוקסי API. מריצים את הפקודה הבאה מהספרייה שמכילה את הקבצים:

gcloud beta apigee apis import hello-proxy \
    --from-template=hello-proxy.yaml \
    --organization=ORG

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

שלב 4: פריסת ה-proxy

פורסים את הגרסה לסביבה:

gcloud apigee apis deploy \
    --api=hello-proxy \
    --environment=ENV \
    --organization=ORG

כברירת מחדל, הפקודה הזו פורסת את הגרסה האחרונה. כדי לפרוס גרסה ספציפית, מעבירים את המספר שלה כארגומנט הראשון, לדוגמה gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. אם כבר נפרס פרוקסי אחר באותו נתיב בסיס, מוסיפים את --override כדי להחליף אותו ללא השבתה.

שלב 5: מתקשרים לשרת ה-proxy

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

כדי למצוא את שם המארח של קבוצת סביבות שמכילה את הסביבה שלכם:

  1. במסוף Google Cloud , עוברים אל Apigee > Management > Environments (ניהול > סביבות).
  2. לוחצים על הכרטיסייה קבוצות סביבות.
  3. מאתרים את קבוצת הסביבות שמכילה את הסביבה שלכם ומעתיקים ערך מהעמודה Hostnames (שמות מארחים).

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

curl https://HOSTNAME/hello

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

חלק 2: בניית שער AI ל-Gemini

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

בניגוד לשרת ה-proxy הפשוט שמופיע בחלק 1, שרת ה-proxy הזה קורא לשירות Google Cloud ‏ (Vertex AI). התכונה gemini-target משתמשת ב-auth: GoogleAccessToken, ולכן Apigee מצרף אסימון Google OAuth לכל בקשה ל-Vertex AI. האסימון הזה מונפק עבור חשבון שירות שיוצרים ואז מספקים כשפורסים את ה-proxy. לכן, החלק הזה מוסיף שלב ליצירת חשבון השירות הזה (שלב 3).

שלב 1: יצירת התבנית

יוצרים קובץ בשם ai-gateway.yaml:

gateway: apigee
schemaVersion: 1.0.0
name: ai-gateway
type: template
description: AI gateway that fronts a Gemini model with throttling and API key enforcement.
features:
- spike-arrest.yaml
- verify-api-key.yaml
- gemini-target.yaml
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

שלב 2: יצירת התכונות

באותה ספרייה, יוצרים את שלושת קובצי התכונות.

משתמשים בתכונה spike-arrest.yaml מחלק 1.

כדי ליצור verify-api-key.yaml ולדרוש מפתח API בכותרת x-api-key:

gateway: apigee
schemaVersion: 1.0.0
name: verify-api-key
displayName: Verify API Key
type: feature
description: Requires a valid API key in the x-api-key request header.
categories:
- security
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: VA-VerifyAPIKey
policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

יוצרים gemini-target.yaml כדי להפנות למודל Gemini, מאומת באמצעות אסימון גישה של Google:

gateway: apigee
schemaVersion: 1.0.0
name: gemini-target
displayName: Gemini Target
type: feature
description: Routes requests to a Gemini model on Vertex AI, authenticated with a Google access token.
categories:
- llm
targets:
- name: gemini
  url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

מחליפים את PROJECT_ID במזהה של הפרויקט ב-Google Cloud, ואת REGION באזור Vertex AI שבו אתם משתמשים (למשל us-central1). התכונה הזו משתמשת ב-auth: GoogleAccessToken כדי ש-Apigee יצרף אסימון גישה ל-Google לכל בקשה ל-Vertex AI.

המודלים לא זמינים בכל המיקומים, וכתובת ה-URL תלויה במיקום שבו אתם משתמשים. כתובת ה-URL שלמעלה היא בפורמט אזורי, והיא מתאימה למודל שמופעל מאזור ספציפי, כמו gemini-2.5-flash ב-us-central1. מודלים אחרים מופעלים רק מנקודת הקצה הגלובלית, שמשתמשת במארח אחר וב-locations/global:

  url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent

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

שלב 3: יצירת חשבון שירות לשרת ה-proxy

מכיוון שהתכונה gemini-target משתמשת ב-auth: GoogleAccessToken, ה-proxy שנפרס קורא ל-Vertex AI בתור חשבון שירות. יוצרים את חשבון השירות, נותנים לו גישה ל-Vertex AI ומאפשרים לסוכן השירות של Apigee להשתמש בו. מציינים את חשבון השירות הזה כשפורסים את ה-proxy בשלב 5. לפרטים נוספים, ראו שימוש באימות של Google.

  1. יוצרים חשבון שירות שמנוהל על ידי משתמש באותו Google Cloud פרויקט שבו נמצא הארגון שלכם ב-Apigee. (חשבון השירות שמוגדר כברירת מחדל ב-Compute Engine לא מתקבל). במאמר יצירה וניהול של חשבונות שירות מוסברות דרכים נוספות ליצירת חשבון שירות. 
    gcloud iam service-accounts create SA_NAME \
    --project=PROJECT_ID \
    --display-name="Apigee AI gateway"

    כך נוצר חשבון השירות SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

  2. מעניקים לחשבון השירות גישה לעורף הקצה שאליו הוא קורא. למטרה של Vertex AI, צריך להעניק את התפקיד Vertex AI User (roles/aiplatform.user): 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

    אם מדיניות ה-IAM של הפרויקט כבר מכילה קישורים מותנים בין תפקידים, מוסיפים את --condition=None לפקודה הזו.

  3. מאפשרים לסוכן השירות של Apigee ליצור אסימונים בשביל חשבון השירות על ידי הקצאת התפקיד יצירת אסימונים בחשבון שירות (roles/iam.serviceAccountTokenCreator) בחשבון השירות: 
    gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --project=PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    כדי למצוא את PROJECT_NUMBER, מריצים את הפקודה gcloud projects describe PROJECT_ID --format='value(projectNumber)'.

שלב 4: ייבוא ה-proxy

מייבאים את התבנית כדי ליצור גרסה של proxy ל-API:

gcloud beta apigee apis import ai-gateway \
    --from-template=ai-gateway.yaml \
    --organization=ORG

רושמים את מספר הגרסה בפלט של הפקודה. תצטרכו אותו בשלב 5. כדי להדפיס רק את מספר הגרסה, מוסיפים את האפשרות --format="value(revision)" לפקודת הייבוא.

שלב 5: פריסת ה-proxy עם חשבון השירות

יש שני הבדלים בין פריסת שער AI לבין פרוקסי פשוט שמוסבר בחלק 1:

  • צריך לספק את חשבון השירות שיצרתם בשלב 3. אם תבצעו פריסה בלי להגדיר אזור, הפריסה תיכשל ותוצג השגיאה MISSING_SERVICE_ACCOUNT.
  • חובה לפרוס בסביבה בינונית או מקיפה. הפרוקסי הזה משתמש במדיניות שניתנת להרחבה, שסביבת Base לא תומכת בה. פריסה לסביבה כזו תיכשל עם השגיאה Extensible proxy can not be deployed to a base environment. למידע על סוגי סביבות ב-Apigee

ממשק המשתמש של Apigee: פורסים את ה-proxy, וכשמוצגת בקשה לחשבון שירות, מזינים את SA_NAME@PROJECT_ID.iam.gserviceaccount.com. הוראות מפורטות זמינות במאמר בנושא פריסת שרת proxy של API.

‫Deployment API: קוראים ל-deployments API ומעבירים את חשבון השירות כפרמטר השאילתה serviceAccount. מחליפים את REVISION במספר הגרסה משלב 4:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com"

הבקשה לפריסה מוחזרת באופן מיידי, והפריסה היא אסינכרונית. שליחת בקשה לבדיקת סטטוס הפריסה של הגרסה, שמוחזרת PROGRESSING עד שהיא הופכת ל-READY:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"

כשקובץ ה-proxy עובר קומפילציה, התכונות spike-arrest ו-verify-api-key מוסיפות את כללי המדיניות שלהן ל-PreFlow של הבקשה (קודם הגבלת קצב, ואז בדיקת מפתח ה-API), והתכונה gemini-target מוסיפה את ה-backend של Vertex AI. אחרי שהפריסה מסתיימת, ה-proxy מבצע אימות ב-Vertex AI בתור חשבון השירות שלכם.

שלב 6: קבלת מפתח API

התכונה verify-api-key דוחה כל בקשה שלא כוללת מפתח API תקין, לכן צריך מפתח כדי להפעיל את ה-proxy. מפתח API הוא אמצעי אימות של אפליקציית מפתח שמשויך למוצר API שמכיל את ה-proxy הזה. צריך לבצע את המשימות הבאות, שמתוארות במאמר סקירה כללית על פרסום:

  1. יוצרים מוצר API שכולל את שרת ה-proxy‏ ai-gateway ואת הסביבה שבה פרסתם אותו.
  2. רישום מפתח אפליקציות.
  3. רושמים אפליקציית מפתח שמשויכת למוצר ה-API הזה.

רישום האפליקציה יוצר את המפתח. במאמר איך רואים מפתח API ו-API Secret מוסבר איך לאחזר אותו.

שלב 7: מתקשרים לשרת ה-Proxy

מוצאים את שם המארח של קבוצת הסביבות כמו שמתואר בחלק 1, שלב 5, ואז קוראים לשרת ה-proxy בנתיב הבסיס /v1/gemini. מעבירים את מפתח ה-API בכותרת x-api-key ושולחים גוף בקשה של Gemini generateContent:

curl -X POST https://HOSTNAME/v1/gemini \
    -H "x-api-key: API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'

מחליפים את HOSTNAME בשם המארח של קבוצת הסביבות ואת API_KEY במפתח משלב 6. תגובה מוצלחת היא פלט JSON של המודל. אם לא מציינים את המפתח, המדיניות VerifyAPIKey מחזירה שגיאת הרשאה, שמאשרת שהתכונה verify-api-key פועלת. במאמר שליחת בקשה עם מפתח API תקין מוסברות דרכים אחרות להעברת מפתח.

השלבים הבאים