Erweiterungen erstellen und ausführen

In diesem Dokument werden die wichtigsten Funktionen des Vertex AI-Erweiterungsdienstes beschrieben:

Informationen zum Importieren und Ausführen einer von Google bereitgestellten Erweiterung finden Sie hier:

Erweiterungen erstellen und importieren

In diesem Dokument wird davon ausgegangen, dass Sie bereits einen ausgeführten API-Dienst haben, der eine Erweiterung unterstützen kann. Zum Erstellen einer Erweiterung müssen Sie die Schnittstelle mit einer externen API in einer API-Spezifikationsdatei definieren. Sie müssen diese Spezifikationsdatei in einen Cloud Storage-Bucket hochladen oder in einen String konvertieren. Anschließend müssen Sie ein Erweiterungsmanifest definieren, die Spezifikationsdatei einschließen und eine Registrierungsanfrage an den Erweiterungsdienst senden.

API-Spezifikationsdatei erstellen

Eine Erweiterung kann von jedem über Dateien erstellt werden, die die API-Endpunkte der Erweiterungen definieren und beschreiben. Die API-Endpunkte können öffentlich oder privat sein und in jeder Cloud oder lokal gehostet werden.

In einer API-Spezifikationsdatei wird die Schnittstelle eines API-Dienstes beschrieben. Sie müssen eine API-Spezifikationsdatei im YAML-Format bereitstellen, die mit OpenAPI 3.0 kompatibel ist. In dieser Spezifikationsdatei muss Folgendes definiert sein:

  • Ein Serverobjekt. Dieses Objekt muss eine API-Server-URL definieren. Der Vertex AI-Erweiterungsdienst unterstützt nicht mehrere Server.

    servers:
  - url: API_SERVICE_URL

  • Ein Pfadobjekt. Dieses Objekt muss die verschiedenen vom API-Dienst bereitgestellten Vorgänge und die Eingabeparameter für die einzelnen Vorgänge beschreiben. Jeder Vorgang muss eine eindeutige Kennzeichnung und eine Antwort haben.

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

  • Ein Komponentenobjekt. Dieses Objekt ist optional. Mit dem Komponentenobjekt können Sie wiederverwendbare Objekte definieren. Beispielsweise können Sie mit dem Komponentenobjekt eine Definition der Objektschemas bereitstellen, die im Pfadobjekt definiert sind. Sie können das Komponentenobjekt auch verwenden, um die Ausgabeparameter des API-Dienstes zu beschreiben.

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

Weitere Informationen zu OpenAPI finden Sie in der OpenAPI-Spezifikation.

Das folgende Beispiel zeigt eine API-Spezifikationsdatei für einen API-Dienst, der "hello" in der angeforderten Sprache angibt:

  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

Spezifikationsdatei hochladen

Sie können entweder die Spezifikationsdatei in einen Cloud Storage-Bucket hochladen oder in einen String konvertieren.

Wenn Sie die Spezifikationsdatei in einen Cloud Storage-Bucket hochladen, weisen Sie dem Dienstkonto Vertex AI Extension Service Agent (service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com) die Rolle Storage-Objekt-Betrachter zu. Informationen zum Auflisten der Buckets in Ihrem Projekt finden Sie unter Buckets auflisten. Weitere Informationen zum Kopieren eines Objekts in einen Cloud Storage-Bucket finden Sie unter Objekte kopieren, umbenennen und verschieben.

Anfrage zum Importieren von Erweiterungen definieren

Nachdem Sie eine API-Spezifikationsdatei erstellt haben, können Sie eine Importanfrage für Erweiterungen in einer JSON-Datei definieren. Eine Importanfrage für eine Erweiterung muss einen Verweis auf Ihre API-Spezifikationsdatei (apiSpec) und die Authentifizierungskonfiguration (authConfig) enthalten. Wenn Sie die Erweiterung mit einem Large Language Model (LLM) verbinden möchten, um zu sehen, wie sie funktioniert, fügen Sie den optionalen Parameter toolUseExamples ein. Wenn Sie nur die Erweiterung ausführen möchten, geben Sie den Parameter toolUseExamples nicht an.

Eine Anfrage zum Importieren einer Erweiterung hat folgendes Format:

{
  "displayName":  "DISPLAY_NAME_HUMAN",
  "description": "DESCRIPTION_HUMAN",
  "manifest": {
    "name": "EXTENSION_NAME_LLM",
    "description": "DESCRIPTION_LLM",
    "apiSpec": { ... },
    "authConfig": { ... },
  }
  "toolUseExamples": [ ... ],
}
  • DISPLAY_NAME_HUMAN: Der Name der Erweiterung, der Nutzern angezeigt wird.
  • DESCRIPTION_HUMAN: Die Beschreibung der Erweiterung, die Nutzern angezeigt wird.
  • EXTENSION_NAME_LLM: Der Name der Erweiterung, die vom LLM aus Gründen verwendet wird.
  • DESCRIPTION_LLM: Die Beschreibung des Erweiterungsdrifts wird vom LLM aus Logik verwendet. Geben Sie eine aussagekräftige und informative Beschreibung.

Verweis auf Ihre API-Spezifikationsdatei

Die Importanfrage für die Erweiterung muss einen Verweis auf Ihre API-Spezifikationsdatei enthalten. Sie können die Spezifikationsdatei auf zwei Arten bereitstellen:

  • Verwenden Sie openApiGcsUri, um den Cloud Storage-URI der .yaml-Datei zu übergeben.

    "apiSpec": {
  "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml"
},
    • BUCKET_NAME: Der Name des Cloud Storage-Buckets, in dem die Spezifikationsdatei gespeichert ist.
    • SPECIFICATION_FILE_NAME: Der Name der API-Spezifikationsdatei.

  • Verwenden Sie openApiYaml, um die .yaml-Datei als String zu übergeben.

Authentifizierungskonfiguration

Erweiterungen können öffentlich für jeden Nutzer verfügbar oder privat nur für autorisierte Nutzer innerhalb einer oder mehrerer Organisationen verfügbar sein.

Eine Anfrage zum Importieren einer Erweiterung muss eine Authentifizierungskonfiguration enthalten. Sie können zwischen den folgenden Authentifizierungsmethoden wählen:

  • NO_AUTH:Keine Authentifizierung
  • API_KEY_AUTHAuthentifizierung von API-Schlüsseln
  • HTTP_BASIC_AUTHHTTP-Basisauthentifizierung
  • OAUTHAuthentifizierung mit OAuth
  • OIDC_AUTH: OIDC-Authentifizierung

Weitere Informationen zu Authentifizierungskonfigurationen finden Sie unter Authentifizierungskonfiguration angeben.

Beispiele zur Funktionsweise der Erweiterung

Die besten Ergebnisse erzielen Sie, wenn Sie beim Importieren von Erweiterungen Beispiele zur Funktionsweise der Erweiterung enthalten. Verwenden Sie den Parameter toolUseExamples, um diese Beispiele bereitzustellen.

Der folgende Code zeigt das Format von toolUseExamples für ein einzelnes Beispiel mit einem einzelnen Eingabeparameter und einem einzelnen Ausgabeparameter. In diesem Beispiel haben sowohl der Anfrage- als auch die Antwortparameter den Typ 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: Ein Beispiel für eine Abfrage, die diese Erweiterung nutzen kann. Geben Sie den Abfragetext mit EXAMPLE_QUERY an.
  • extensionOperation: Ein Erweiterungsvorgang, der für die Beantwortung von query geeignet ist. Verwenden Sie API_SERVICE_OPERATION_ID, um die ID eines in der API-Spezifikationsdatei definierten Erweiterungsvorgangs anzugeben.
  • displayName: Ein Anzeigename für das Beispiel. Verwenden Sie EXAMPLE_DISPLAY_NAME, um eine kurze Beschreibung anzugeben.
  • requestParams: Die Anfrageparameter, die für die extensionOperation- und Beispielwerte im Schlüssel/Wert-Format erforderlich sind. Verwenden Sie API_SERVICE_INPUT_VAR, um einen Eingabeparameter bereitzustellen, der in der API-Spezifikationsdatei definiert ist und API_SERVICE_OPERATION_ID entspricht. Verwenden Sie EXAMPLE_INPUT, um ein Beispiel für einen Eingabewert bereitzustellen, der EXAMPLE_QUERY entspricht.
  • responseParams: Die Antwortparameter der extensionOperation und Beispielwerte im Schlüssel/Wert-Format. Verwenden Sie API_SERVICE_OUTPUT_VAR, um einen Ausgabeparameter bereitzustellen, der in der API-Spezifikationsdatei definiert ist und dem API-Dienst entspricht. Verwenden Sie EXAMPLE_OUTPUT, um ein Beispiel für einen Ausgabewert bereitzustellen, der EXAMPLE_INPUT entspricht.
  • responseSummary: Ein Beispiel für eine Zusammenfassung, die die Anwendung als Antwort auf query bereitstellen kann. Verwenden Sie EXAMPLE_SUMMARY, um den Zusammenfassungstext bereitzustellen.

Das folgende Beispiel zeigt toolUseExamples für einen API-Dienst, der "hello" in der angeforderten Sprache angibt:

"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"
    }
],

Authentifizierungskonfiguration angeben

Sie müssen eine Authentifizierungskonfiguration angeben, wenn Sie eine Anfrage zum Importieren einer Erweiterung definieren.

Wenn die Erweiterung keine Authentifizierung erfordert, legen Sie die Variable authType auf NO_AUTH fest:

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

Wenn Ihre Erweiterung eine Authentifizierung erfordert, müssen Sie den Authentifizierungstyp in der Variable authType festlegen und eine Authentifizierungskonfiguration angeben. Sie können zwischen den folgenden Authentifizierungsmethoden wählen:

Authentifizierung von API-Schlüsseln

Zur Unterstützung der API-Schlüsselauthentifizierung kann Vertex AI in SecretManager für die Speicherung und den Zugriff von Secrets eingebunden werden. Die Vertex AI Extensions-Plattform speichert die Secret-Daten nicht direkt. Sie sind für die Verwaltung des Lebenszyklus Ihrer SecretManager-Ressource verantwortlich.

Geben Sie authConfig so an:

"authConfig": {
  "authType": "API_KEY_AUTH",
  "apiKeyConfig": {
    "name": "API_KEY_CONFIG_NAME",
    "apiKeySecret": "API_KEY_SECRET",
    "httpElementLocation": "HTTP_ELEMENT_LOCATION",
  },
}
  • API_KEY_CONFIG_NAME: Der Name des API-Schlüssels. In der API-Anfrage https://example.com/act?api_key=<API KEY> entspricht API_KEY_CONFIG_NAME beispielsweise api_key.
  • API_KEY_SECRET: SecretManager-Secret-Versionsressource, in der der Schlüssel gespeichert ist. Dieser Parameter hat folgendes Format: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

  • HTTP_ELEMENT_LOCATION: Der Speicherort des API-Schlüssels in der HTTP-Anfrage. Folgende Werte sind möglich:

    • HTTP_IN_QUERY
    • HTTP_IN_HEADER
    • HTTP_IN_PATH
    • HTTP_IN_BODY
    • HTTP_IN_COOKIE

    Weitere Informationen finden Sie unter Parameter beschreiben.

HTTP-Basisauthentifizierung

Zur Unterstützung der HTTP-Basisauthentifizierung wird Vertex AI in SecretManager für die Speicherung und den Zugriff von/auf Secrets eingebunden. Die Vertex AI Extensions-Plattform speichert die Secret-Daten nicht direkt. Sie müssen den Lebenszyklus Ihrer SecretManager-Ressource selbst verwalten.

Geben Sie authConfig so an:

"authConfig": {
  "authType": "HTTP_BASIC_AUTH",
  "httpBasicAuthConfig": {
    "credentialSecret": "CREDENTIAL_SECRET"
  },
}
  • CREDENTIAL_SECRET: SecretManager-Secret-Versionsressource, die die base64-codierten Anmeldedaten speichert. Dieser Parameter hat folgendes Format: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION.

Authentifizierung mit OAuth

Vertex AI unterstützt zwei Methoden der OAuth-Authentifizierung: Zugriffstoken und Dienstkonto.

Zugriffstoken

Geben Sie authConfig so an:

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

Lassen Sie das Feld oauthConfig leer, wenn Sie die Erweiterung importieren. Wenn Sie eine registrierte Erweiterung ausführen, müssen Sie im Feld oauthConfig der Bestätigungsanfrage ein Zugriffstoken angeben. Weitere Informationen finden Sie unter Erweiterung ausführen.

Dienstkonto

Geben Sie authConfig so an:

"authConfig": {
  "authType": "OAUTH",
  "oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI verwendet dieses Dienstkonto, um Zugriffstokens zu generieren.

Führen Sie die folgenden Schritte aus, damit Vertex AI Extension Service Agent Zugriffstokens von SERVICE_ACCOUNT_NAME abrufen kann.

  1. Rufen Sie die IAM-Seite auf.

    IAM aufrufen

  2. Klicken Sie auf den Tab Dienstkonten.

  3. Klicken Sie auf Ihr Dienstkonto. Der Wert von SERVICE_ACCOUNT_NAME in authConfig muss dem Namen Ihres Dienstkontos entsprechen.

  4. Klicken Sie auf den Tab Berechtigungen.

  5. Klicken Sie auf Zugriff erlauben.

  6. Geben Sie im Abschnitt Hauptkonten hinzufügen im Feld Neue Hauptkonten service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com ein. Dieses Hauptkonto entspricht dem Dienstkonto Vertex AI Extension Service Agent.

  7. Suchen Sie im Abschnitt Rollen zuweisen die Rolle Service Account Token Creator und wählen Sie sie aus. Diese Rolle umfasst die Berechtigung iam.serviceAccounts.getAccessToken.

  8. Klicken Sie auf Speichern.

OIDC-Authentifizierung

Vertex AI unterstützt zwei Methoden der OIDC-Authentifizierung: ID-Token und Dienstkonto.

ID-Token

Geben Sie authConfig so an:

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

Lassen Sie das Feld oidcConfig leer, wenn Sie die Erweiterung importieren. Wenn Sie eine registrierte Erweiterung ausführen möchten, müssen Sie im Feld oidcConfig der Ausführungsanfrage ein ID-Token angeben. Weitere Informationen finden Sie unter Erweiterung ausführen.

Dienstkonto

Geben Sie authConfig so an:

"authConfig": {
  "authType": "OIDC_AUTH",
  "oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
  • SERVICE_ACCOUNT_NAME: Vertex AI verwendet dieses Dienstkonto, um OIDC-Tokens (OpenID Connect) zu generieren. Vertex AI legt die Zielgruppe für das Token auf API_SERVICE_URL fest, wie in der API-Spezifikationsdatei definiert.

Führen Sie die folgenden Schritte aus, damit Vertex AI Extension Service Agent Zugriffstokens von SERVICE_ACCOUNT_NAME abrufen kann.

  1. Rufen Sie die IAM-Seite auf.

    IAM aufrufen

  2. Klicken Sie auf den Tab Dienstkonten.

  3. Klicken Sie auf Ihr Dienstkonto. Der Wert von SERVICE_ACCOUNT_NAME in authConfig muss dem Namen Ihres Dienstkontos entsprechen.

  4. Klicken Sie auf den Tab Berechtigungen.

  5. Klicken Sie auf Zugriff erlauben.

  6. Geben Sie im Abschnitt Hauptkonten hinzufügen im Feld Neue Hauptkonten service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com ein. Dieses Hauptkonto entspricht dem Dienstkonto Vertex AI Extension Service Agent.

  7. Suchen Sie im Abschnitt Rollen zuweisen die Rolle Service Account Token Creator und wählen Sie sie aus. Diese Rolle umfasst die Berechtigung iam.serviceAccounts.getOpenIdToken.

  8. Klicken Sie auf Speichern.

Erweiterung mit Vertex AI importieren

Nachdem Sie eine Erweiterungsimportanfrage definiert haben, können Sie die Erweiterung mit Vertex AI importieren.

  1. Legen Sie die folgenden Shell-Variablen fest:

    ENDPOINT="LOCATION-aiplatform.googleapis.com"
URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
    • PROJECT_ID: Ihr Projekt
    • LOCATION: eine Region Ihrer Wahl. Wenn Sie nicht sicher sind, wählen Sie us-central1 aus.

  2. Führen Sie den folgenden curl-Befehl aus, um die Importanfrage zu senden:

    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"

    Die Antwort hat folgendes Format:

    {
  "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. Legen Sie Shell-Variablen basierend auf der Ausgabe der Importanfrage fest:

    EXTENSION_ID=EXTENSION_ID
IMPORT_OPERATION_ID=IMPORT_OPERATION_ID

  4. Führen Sie den folgenden curl-Befehl aus, um den Status des Imports zu prüfen:

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

Erweiterungen verwalten

Führen Sie folgenden curl-Befehl aus, um alle registrierten Erweiterungen aufzulisten:

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

Führen Sie den folgenden curl-Befehl aus, um eine Erweiterung abzurufen:

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

Sie können die Dateien displayName, description oder toolUseExamples der Erweiterung aktualisieren. Wenn Sie beim Aktualisieren einer Erweiterung toolUseExamples angeben, ersetzt die Aktualisierung die Beispiele. Wenn Sie beispielsweise die Beispiele a und b haben, aktualisieren Sie die Erweiterung mit dem Beispiel c. Die aktualisierte Erweiterung enthält dann nur das Beispiel c. Beschreibung, führen Sie den folgenden curl-Befehl aus:

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.",
}'

Führen Sie den folgenden curl-Befehl aus, um eine Erweiterung zu löschen:

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

Erweiterung ausführen

Es gibt zwei Möglichkeiten, eine Erweiterung auszuführen:

  • execute: In diesem Modus liegt der Schwerpunkt ausschließlich auf der API-Ausführung. Die Erweiterung löst den angegebenen API-Vorgang aus und gibt die Rohergebnisse ohne weitere Verarbeitung zurück.

  • query: Dieser Modus ist für intelligente Interaktionen konzipiert. Dazu sind mehrere Schritte erforderlich:

    • Modellanfrage: Die Abfrage und das Schema der Erweiterung werden Gemini als Prompt und FunctionDeclaration zur Verfügung gestellt.
    • API-Ausführung: Wenn das Modell feststellt, dass die Verwendung des Tools erforderlich ist, ruft die Erweiterung den API-Vorgang automatisch im Namen des Modells auf und ruft die Ergebnisse ab.
    • Modellintegration: Die API-Ergebnisse werden in das Modell eingespeist, das sie verarbeitet, um die endgültige, kontextbezogen relevante Antwort zu generieren. Im Grunde fungiert query als Agent mit einem einzigen Tool, der die API verwendet, um seine Ziele zu erreichen.

In diesem Abschnitt wird beschrieben, wie Sie eine Erweiterung execute.

Wenn Ihre Erweiterung die OAuth-Authentifizierung und ein Zugriffstoken verwendet, lesen Sie die Informationen unter Erweiterung mit OAuth-Authentifizierung und einem Zugriffstoken ausführen.

Wenn Ihre Erweiterung die OIDC-Authentifizierung und ein ID-Token verwendet, finden Sie weitere Informationen unter Erweiterung mit OIDC-Authentifizierung und einem ID-Token ausführen.

Andernfalls können Sie es so ausführen:

  1. Erstellen Sie eine Datei mit dem Namen execute-extension.json und mit folgendem Inhalt:

    {
  "operation_id": "API_SERVICE_OPERATION_ID",
  "operation_params": {
    "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE"
  }
}
    • API_SERVICE_OPERATION_ID: Die ID des API-Dienstvorgangs, den Sie ausführen möchten. API-Dienstvorgänge werden in der API-Spezifikationsdatei definiert.
    • API_SERVICE_INPUT_VAR: eine Eingabevariable, die API_SERVICE_OPERATION_ID entspricht und in der API-Spezifikationsdatei definiert ist.
    • API_SERVICE_INPUT_VALUE: Ein Eingabewert für die Erweiterung.

  2. Führen Sie folgenden Befehl curl aus:

    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"

    Die Antwort hat folgendes Format:

    {
  "output": {
    "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}"
  }
}
    • API_SERVICE_OUTPUT_VAR: Ein Ausgabeparameter, der in der API-Spezifikationsdatei definiert ist und dem API-Dienst entspricht.
    • API_SERVICE_OUTPUT_VALUE: Ein Stringwert, der eine Serialisierung des Antwortobjekts ist. Wenn in Ihrer API-Spezifikationsdatei ein JSON-Antwortschema definiert ist, müssen Sie diesen Ausgabestring selbst in JSON parsen.

Erweiterung mit OAuth-Authentifizierung und einem Zugriffstoken ausführen

Wenn Ihre Erweiterung die OAuth-Authentifizierung und ein Zugriffstoken verwendet, können Sie sie so ausführen:

  1. Erstellen Sie eine Datei mit dem Namen execute-extension.json und mit folgendem Inhalt:

    {
  "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: Die ID des API-Dienstvorgangs, den Sie ausführen möchten. API-Dienstvorgänge werden in der API-Spezifikationsdatei definiert.

  2. Führen Sie folgenden Befehl curl aus:

    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"

Erweiterung mit OIDC-Authentifizierung und einem ID-Token ausführen

Wenn Ihre Erweiterung die OIDC-Authentifizierung und ein ID-Token verwendet, können Sie es mit folgenden Schritten ausführen:

  1. Erstellen Sie eine Datei mit dem Namen execute-extension.json und mit folgendem Inhalt:

    {
  "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: Die ID des API-Dienstvorgangs, den Sie ausführen möchten. API-Dienstvorgänge werden in der API-Spezifikationsdatei definiert.

  2. Führen Sie folgenden Befehl curl aus:

    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"

Nächste Schritte