יצירה והרצה של תוספים

במסמך הזה מוסברת הפונקציונליות העיקרית של שירות התוספים של Vertex AI:

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

יצירה וייבוא של תוספים

במסמך הזה אנחנו מניחים שכבר יש לכם שירות API פעיל שיכול לתמוך בתוסף. כדי ליצור תוסף, צריך להגדיר את הממשק שלו עם API חיצוני בקובץ הגדרות API. צריך להעלות את קובץ המפרט הזה לקטגוריה של Cloud Storage או להמיר אותו למחרוזת. לאחר מכן צריך להגדיר מניפסט של התוסף, לכלול את קובץ המפרט ולשלוח בקשת רישום לשירות התוספים.

יצירת קובץ מפרט API

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

קובץ מפרט API מתאר את הממשק של שירות API. עליכם לספק קובץ מפרט API בפורמט YAML שתואם ל-OpenAPI 3.0. בקובץ המפרט צריך להגדיר את הפרטים הבאים:

  • אובייקט שרת. באובייקט הזה צריך להגדיר כתובת URL של שרת API. שירות התוסף Vertex AI לא תומך בכמה שרתים.

    servers:
  - url: API_SERVICE_URL

  • אובייקט paths. האובייקט הזה צריך לתאר את הפעולות השונות ששירות ה-API מספק ואת פרמטרי הקלט שמתאימים לכל פעולה. לכל פעולה צריך להיות מזהה ייחודי ותגובה.

    paths:
  ...
    get:
      operationId: API_SERVICE_OPERATION_ID
      ...
      parameters:
        - name: API_SERVICE_INPUT_VAR
          ...
      responses:
      ...

  • אובייקט components. האובייקט הזה הוא אופציונלי. אפשר להשתמש באובייקט components כדי להגדיר אובייקטים שאפשר לעשות בהם שימוש חוזר. לדוגמה, אפשר להשתמש באובייקט components כדי לספק הגדרה של סכימות האובייקטים שמוגדרות באובייקט paths. אפשר גם להשתמש באובייקט components כדי לתאר את פרמטרי הפלט של שירות ה-API.

    components:
  schemas:
    Result:
      ...
      properties:
        API_SERVICE_OUTPUT_VAR:
        ...

מידע נוסף על OpenAPI זמין במאמר מפרט OpenAPI.

הדוגמה הבאה היא קובץ מפרט API לשירות API שאומר "שלום" בשפה המבוקשת:

  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: Hello Extension
    description: Learn to build Vertex AI extensions
  servers:
    - url: [API_SERVICE_URL]
  paths:
    /hello:
      get:
        operationId: say_hello
        description: Say hello in prompted language.
        parameters:
          - name: apiServicePrompt
            in: query
            description: Language
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Successful operation.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Result"
  components:
    schemas:
      Result:
        description: Hello in the requested language.
        properties:
          apiServiceOutput:
            type: string

העלאת קובץ המפרט

אפשר להעלות את קובץ המפרט לקטגוריה ב-Cloud Storage או להמיר אותו למחרוזת.

אם מעלים את קובץ המפרט לקטגוריה של Cloud Storage, צריך להקצות לחשבון השירות Vertex AI Extension Service Agent (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com) את התפקיד צפייה באובייקט אחסון. במאמר הצגת רשימה של הקטגוריות מוסבר איך להציג את רשימת הקטגוריות בפרויקט. מידע נוסף על העתקת אובייקט לקטגוריה של Cloud Storage מופיע במאמר העתקה, שינוי שם והעברה של אובייקטים.

הגדרת בקשה לייבוא תוסף

אחרי שיוצרים קובץ הגדרות API, אפשר להגדיר בקשת ייבוא של תוסף בקובץ JSON. בקשת ייבוא של תוסף חייבת להכיל הפניה לקובץ מפרט ה-API (apiSpec) ולהגדרת האימות (authConfig). כדי לחבר את התוסף למודל שפה גדול (LLM) ולראות איך התוסף פועל, צריך לכלול את הפרמטר האופציונלי toolUseExamples. אם רוצים להפעיל רק את התוסף, לא כוללים את הפרמטר toolUseExamples.

בקשה לייבוא תוסף נראית כך:

{
  "displayName":  "DISPLAY_NAME_HUMAN",
  "description": "DESCRIPTION_HUMAN",
  "manifest": {
    "name": "EXTENSION_NAME_LLM",
    "description": "DESCRIPTION_LLM",
    "apiSpec": { ... },
    "authConfig": { ... },
  }
  "toolUseExamples": [ ... ],
}
  • DISPLAY_NAME_HUMAN: השם של התוסף שמוצג למשתמשים.
  • ‫DESCRIPTION_HUMAN: התיאור של התוסף שמוצג למשתמשים.
  • ‫EXTENSION_NAME_LLM: השם של התוסף שמשמש את ה-LLM לניתוח.
  • ‫DESCRIPTION_LLM: תיאור התוסף שמשמש את ה-LLM לניתוח. מומלץ לספק תיאור משמעותי ואינפורמטיבי.

הפניה לקובץ מפרט ה-API

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

  • משתמשים ב-openApiGcsUri כדי להעביר את ה-URI של קובץ ה-YAML ב-Cloud Storage.

    "apiSpec": {
  "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
},
    • ‫BUCKET_NAME: השם של קטגוריית Cloud Storage שבה מאוחסן קובץ המפרט.
    • ‫SPECIFICATION_FILE_NAME: השם של קובץ מפרט ה-API.

  • משתמשים ב-openApiYaml כדי להעביר את קובץ ה-YAML כמחרוזת.

הגדרת אימות

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

בקשה לייבוא תוסף חייבת לכלול הגדרת אימות. אפשר לבחור בין שיטות האימות הבאות:

  • NO_AUTH: ללא אימות
  • ‫API_KEY_AUTH: אימות באמצעות מפתח API
  • ‫HTTP_BASIC_AUTH: אימות בסיסי של HTTP
  • ‫OAUTH: אימות OAuth
  • ‫OIDC_AUTH: אימות OIDC

מידע נוסף על הגדרות אימות זמין במאמר הגדרת אימות.

דוגמאות שממחישות איך התוסף פועל

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

הקוד הבא מציג את הפורמט של toolUseExamples בדוגמה אחת, עם פרמטר קלט אחד ופרמטר פלט אחד. בדוגמה הזו, פרמטרי הבקשה והתשובה הם מסוג string.

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "API_SERVICE_OPERATION_ID",
      },
      "displayName": "EXAMPLE_DISPLAY_NAME",
      "query": "EXAMPLE_QUERY",
      "requestParams": {
        "fields": [
          {
            "key": "API_SERVICE_INPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_INPUT",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "API_SERVICE_OUTPUT_VAR",
            "value": {
              "string_value": "EXAMPLE_OUTPUT",
            },
          }
        ],
      },
      "responseSummary": "EXAMPLE_SUMMARY"
    }
],
  • ‫query: דוגמה לשאילתה שיכולה להפיק תועלת מהתוסף הזה. משתמשים ב-EXAMPLE_QUERY כדי לספק את הטקסט של השאילתה.
  • ‫extensionOperation: פעולת תוסף שמתאימה למענה על query. משתמשים ב-API_SERVICE_OPERATION_ID כדי לספק את המזהה של פעולת תוסף שמוגדרת בקובץ מפרט ה-API.
  • ‫displayName: שם מוצג לדוגמה. משתמשים בתג EXAMPLE_DISPLAY_NAME כדי לספק תיאור קצר.
  • ‫requestParams: פרמטרים של הבקשה שנדרשים עבור extensionOperation וערכים לדוגמה, בפורמט של צמד מפתח/ערך. משתמשים ב-API_SERVICE_INPUT_VAR כדי לספק פרמטר קלט שמוגדר בקובץ מפרט ה-API ומתאים ל-API_SERVICE_OPERATION_ID. משתמשים בערך EXAMPLE_INPUT כדי לספק דוגמה לערך קלט שתואם לערך EXAMPLE_QUERY.
  • ‫responseParams: פרמטרים של התגובה של extensionOperation וערכים לדוגמה בפורמט של צמד מפתח/ערך. משתמשים ב-API_SERVICE_OUTPUT_VAR כדי לספק פרמטר פלט שמוגדר בקובץ מפרט ה-API ומתאים לשירות ה-API. משתמשים בפונקציה EXAMPLE_OUTPUT כדי לספק דוגמה לערך פלט שתואם לערך EXAMPLE_INPUT.
  • ‫responseSummary: דוגמה לסיכום שהאפליקציה עשויה לספק בתגובה ל-query. משתמשים בתג EXAMPLE_SUMMARY כדי לספק את טקסט הסיכום.

הדוגמה הבאה מציגה את toolUseExamples עבור שירות API שאומר 'שלום' בשפה המבוקשת:

"toolUseExamples": [
  {
      "extensionOperation": {
        "operationId": "say_hello",
      },
      "displayName": "Say hello in the requested language",
      "query": "Say hello in French",
      "requestParams": {
        "fields": [
          {
            "key": "apiServicePrompt",
            "value": {
              "string_value": "French",
            }
          }
        ]
      },
      "responseParams": {
        "fields": [
          {
            "key": "apiServiceOutput",
            "value": {
              "string_value": "bonjour",
            },
          }
        ],
      },
      "responseSummary": "Bonjour"
    }
],

ציון הגדרת אימות

כשמגדירים בקשה לייבוא תוסף, צריך לציין הגדרת אימות.

אם התוסף לא דורש אימות, מגדירים את המשתנה authType לערך NO_AUTH:

"authConfig": {
  "authType": "NO_AUTH"
}

אם התוסף דורש אימות, צריך להגדיר את סוג האימות במשתנה authType ולספק הגדרת אימות. אפשר לבחור בין שיטות האימות הבאות:

אימות באמצעות מפתח API

כדי לתמוך באימות באמצעות מפתח API, ‏ Vertex AI משתלב עם SecretManager לאחסון סודות ולגישה אליהם. פלטפורמת התוספים של Vertex AI לא מאחסנת את הנתונים הסודיים ישירות. אתם אחראים לניהול מחזור החיים של משאב SecretManager.

מציינים את authConfig באופן הבא:

"authConfig": {
  "authType": "API_KEY_AUTH",
  "apiKeyConfig": {
    "name": "API_KEY_CONFIG_NAME",
    "apiKeySecret": "API_KEY_SECRET",
    "httpElementLocation": "HTTP_ELEMENT_LOCATION",
  },
}
  • ‫API_KEY_CONFIG_NAME: השם של מפתח ה-API. לדוגמה, בבקשת ה-API‏ https://example.com/act?api_key=<API KEY>,‏ API_KEY_CONFIG_NAME תואם ל-api_key.
  • ‫API_KEY_SECRET: משאב של גרסת סוד SecretManager שמאחסן את המפתח. הפורמט של הפרמטר הזה הוא: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

  • ‫HTTP_ELEMENT_LOCATION: המיקום של מפתח ה-API בבקשת ה-HTTP. הערכים שאפשר לבחור הם:

    • HTTP_IN_QUERY
    • HTTP_IN_HEADER
    • HTTP_IN_PATH
    • HTTP_IN_BODY
    • HTTP_IN_COOKIE

    מידע נוסף זמין במאמר תיאור פרמטרים.

אימות HTTP בסיסי

כדי לתמוך באימות בסיסי של HTTP, ‏ Vertex AI משתלב עם SecretManager לאחסון סודות וגישה אליהם. פלטפורמת התוספים של Vertex AI לא מאחסנת את הנתונים הסודיים ישירות. אתם צריכים לנהל בעצמכם את מחזור החיים של משאב SecretManager.

מציינים את authConfig באופן הבא:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • ‫CREDENTIAL_SECRET: משאב של גרסת סוד SecretManager שמאחסן את פרטי הכניסה בקידוד base64. הפורמט של הפרמטר הזה הוא: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

אימות OAuth

‫Vertex AI תומך בשתי שיטות אימות OAuth: אסימון גישה וחשבון שירות.

טוקן גישה

מציינים את authConfig באופן הבא:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {}
}

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

חשבון שירות

מציינים את authConfig באופן הבא:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: מערכת Vertex AI משתמשת בחשבון השירות הזה כדי ליצור אסימוני גישה.

כדי לאפשר ל-Vertex AI Extension Service Agent לקבל אסימוני גישה מ-SERVICE_ACCOUNT_NAME, צריך לבצע את השלבים הבאים.

  1. עוברים לדף IAM.

    כניסה לדף IAM

  2. לוחצים על הכרטיסייה חשבונות שירות.

  3. לוחצים על חשבון השירות. הערך של SERVICE_ACCOUNT_NAME ב-authConfig צריך להיות זהה לשם של חשבון השירות.

  4. לוחצים על הכרטיסייה Principals with access (גורמים עם גישה).

  5. לוחצים על הענקת גישה.

  6. בקטע Add principals, בשדה New principals, מזינים service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. החשבון הראשי הזה תואם לחשבון השירות Vertex AI Extension Service Agent.

  7. בקטע הקצאת תפקידים, מוצאים את התפקיד Service Account Token Creator ובוחרים בו. התפקיד הזה כולל את ההרשאה iam.serviceAccounts.getAccessToken.

  8. לוחצים על הלחצן שמירה.

אימות OIDC

‫Vertex AI תומך בשתי שיטות לאימות OIDC: אסימון מזהה וחשבון שירות.

אסימון מזהה

מציינים את authConfig באופן הבא:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {}
}

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

חשבון שירות

מציינים את authConfig באופן הבא:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • ‫SERVICE_ACCOUNT_NAME: Vertex AI משתמש בחשבון השירות הזה כדי ליצור אסימונים של OpenID Connect‏ (OIDC). ‫Vertex AI מגדיר את הקהל של הטוקן ל-API_SERVICE_URL, כפי שמוגדר בקובץ מפרט ה-API.

כדי לאפשר ל-Vertex AI Extension Service Agent לקבל אסימוני גישה מ-SERVICE_ACCOUNT_NAME, צריך לבצע את השלבים הבאים.

  1. עוברים לדף IAM.

    כניסה לדף IAM

  2. לוחצים על הכרטיסייה חשבונות שירות.

  3. לוחצים על חשבון השירות. הערך של SERVICE_ACCOUNT_NAME ב-authConfig צריך להיות זהה לשם של חשבון השירות.

  4. לוחצים על הכרטיסייה Permissions.

  5. לוחצים על הענקת גישה.

  6. בקטע Add principals, בשדה New principals, מזינים service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com. החשבון הראשי הזה תואם לחשבון השירות Vertex AI Extension Service Agent.

  7. בקטע הקצאת תפקידים, מוצאים את התפקיד Service Account Token Creator ובוחרים בו. התפקיד הזה כולל את ההרשאה iam.serviceAccounts.getOpenIdToken.

  8. לוחצים על הלחצן שמירה.

ייבוא התוסף באמצעות Vertex AI

אחרי שמגדירים בקשת ייבוא של תוסף, אפשר לייבא את התוסף באמצעות Vertex AI.

  1. מגדירים את משתני ה-shell הבאים:

    ENDPOINT="LOCATION-aiplatform.googleapis.com"
URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
    • ‫PROJECT_ID: הפרויקט שלכם.
    • ‫LOCATION: אזור לבחירתכם. אם אתם לא בטוחים, בוחרים באפשרות us-central1.

  2. מריצים את הפקודה הבאה curl כדי לשלוח את בקשת הייבוא:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @IMPORT_REQUEST.json "${URL}/extensions:import"

    התשובה תהיה בפורמט הבא:

    {
  "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata",
    "genericMetadata": {
      "createTime": "[CREATE_TIME]",
      "updateTime": "[UPDATE_TIME]"
    }
  }
}

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

    EXTENSION_ID=EXTENSION_ID
IMPORT_OPERATION_ID=IMPORT_OPERATION_ID

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

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/operations/${IMPORT_OPERATION_ID}"

ניהול תוספים

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

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"

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

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"

אפשר לעדכן את displayName, description או toolUseExamples של התוסף. אם מציינים toolUseExamples כשמעדכנים תוסף, העדכון מחליף את הדוגמאות. לדוגמה, אם יש לכם דוגמאות a ו-b, ואז אתם מעדכנים את התוסף עם הדוגמה c, התוסף המעודכן יכיל רק את הדוגמה c.כדי לעדכן את תיאור התוסף, מריצים את הפקודה curl הבאה:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
  "description": "A nice tool.",
}'

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

curl \
 -X DELETE \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}

הרצת תוסף

יש שתי דרכים להפעיל תוסף:

  • ‫execute: במצב הזה, הדגש הוא רק על הפעלת ה-API. התוסף מפעיל את פעולת ה-API שצוינה ומחזיר את התוצאות הגולמיות בלי עיבוד נוסף.

  • ‫query: המצב הזה מיועד לאינטראקציות חכמות. התהליך כולל כמה שלבים:

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

בקטע הזה מוסבר איך execute תוסף.

אם התוסף שלכם משתמש באימות OAuth ובאסימון גישה, כדאי לעיין במאמר בנושא הרצת תוסף עם אימות OAuth ואסימון גישה.

אם התוסף משתמש באימות OIDC ובאסימון מזהה, כדאי לעיין במאמר בנושא הפעלת תוסף עם אימות OIDC ואסימון מזהה.

אם לא, אפשר להפעיל אותו לפי השלבים הבאים:

  1. יוצרים קובץ בשם execute-extension.json עם התוכן הבא:

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {
    "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE"
  }
}
    • ‫API_SERVICE_OPERATION_ID: המזהה של פעולת שירות ה-API שרוצים להריץ. פעולות שירות של API מוגדרות בקובץ מפרט ה-API.
    • ‫API_SERVICE_INPUT_VAR: משתנה קלט שתואם ל-API_SERVICE_OPERATION_ID ומוגדר בקובץ מפרט ה-API.
    • ‫API_SERVICE_INPUT_VALUE: ערך קלט לתוסף.

  2. מריצים את הפקודה הבאה curl:

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

    התשובה תהיה בפורמט הבא:

    {
  "output": {
    "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}"
  }
}
    • ‫API_SERVICE_OUTPUT_VAR: פרמטר פלט שמוגדר בקובץ מפרט ה-API ומתאים לשירות ה-API.
    • ‫API_SERVICE_OUTPUT_VALUE: ערך מחרוזת שהוא סריאליזציה של אובייקט התגובה. אם קובץ מפרט ה-API מגדיר סכימת תגובה בפורמט JSON, צריך לנתח את מחרוזת הפלט הזו ל-JSON בעצמכם.

הפעלת תוסף עם אימות OAuth ואסימון גישה

אם התוסף משתמש באימות OAuth ובאסימון גישה, אפשר להריץ אותו באמצעות השלבים הבאים:

  1. יוצרים קובץ בשם execute-extension.json עם התוכן הבא:

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OAUTH",
    "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"}
  }
}
    • ‫API_SERVICE_OPERATION_ID: המזהה של פעולת שירות ה-API שרוצים להריץ. פעולות שירות של API מוגדרות בקובץ מפרט ה-API.

  2. מריצים את הפקודה הבאה curl:

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

הפעלת תוסף עם אימות OIDC ואסימון מזהה

אם התוסף משתמש באימות OIDC ובאסימון מזהה, אפשר להריץ אותו באמצעות השלבים הבאים:

  1. יוצרים קובץ בשם execute-extension.json עם התוכן הבא:

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {...},
  "runtime_auth_config": {
    "authType": "OIDC_AUTH",
    "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"}
  }
}
    • ‫API_SERVICE_OPERATION_ID: המזהה של פעולת שירות ה-API שרוצים להריץ. פעולות שירות של API מוגדרות בקובץ מפרט ה-API.

  2. מריצים את הפקודה הבאה curl:

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \
"${URL}/extensions/${EXTENSION_ID}:execute"

המאמרים הבאים