API-Proxy aus einer YAML-Vorlage erstellen

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite erfahren Sie, wie Sie einen API-Proxy als Apigee-Featurevorlage in YAML definieren und mit der Google Cloud CLI bereitstellen. Zuerst erstellen Sie einen einfachen Proxy und dann ein vollständigeres Beispiel, das ein Gemini-Modell vorschaltet.

Weitere Informationen finden Sie unter Proxy mit YAML konfigurieren. Das vollständige Schema finden Sie in der YAML-Konfigurationsreferenz für API-Proxys.

Hinweis

  • Nur für Teil 2: Aktivieren Sie die Agent Platform API im Google Cloud-Projekt, in dem das Modell gehostet wird:

    gcloud services enable aiplatform.googleapis.com \
        --project=PROJECT_ID

    Ersetzen Sie PROJECT_ID durch die ID des Projekts, in dem das Modell gehostet wird, z. B. my-apigee-project. In dieser Schritt-für-Schritt-Anleitung wird das Projekt Ihrer Apigee-Organisation verwendet. Teil 1 benötigt diese API nicht. Sie müssen keine Region auswählen, da die Vorlage den globalen Endpunkt verwendet. Es kann einige Zeit dauern, bis die API nach der Aktivierung aktiv wird.

  • Installieren und initialisieren Sie das Google Cloud CLI.
  • Sie benötigen eine Apigee-Organisation und mindestens eine Umgebung. Notieren Sie sich die Namen der Organisation und der Umgebung. In den Beispielen werden ORG und ENV als Platzhalter verwendet (siehe Auf dieser Seite verwendete Platzhalter). Für das KI-Gateway in Teil 2 ist zusätzlich eine Intermediate- oder Comprehensive-Umgebung erforderlich (keine Base-Umgebung). Weitere Informationen finden Sie unter Apigee-Umgebungstypen.
  • Sie müssen die erforderlichen Berechtigungen haben:
    • Zum Importieren (Erstellen) eines API-Proxy: die Rolle API-Administrator (roles/apigee.apiAdmin) oder eine entsprechende Rolle, die apigee.proxies.create gewährt.
    • Zum Bereitstellen eines API-Proxy: Umgebungsadministrator (roles/apigee.environmentAdmin) für die Zielumgebung und API-Leser (roles/apigee.apiReaderV2) auf Projektebene.
    • Zum Erstellen des API-Produkts, des Entwicklers und der Anwendung, die den API-Schlüssel in Teil 2, Schritt 6 erzeugen: API-Administrator (roles/apigee.apiAdmin) und Entwickler-Administrator (roles/apigee.developerAdmin). Eine vollständige Liste der Rollen finden Sie unter Apigee-Rollen.

Auf dieser Seite verwendete Platzhalter

Ersetzen Sie jeden Platzhalter in den Befehlen durch Ihren eigenen Wert. Die meisten Werte sind bereits vorhanden und Sie schlagen sie nach. Sie wählen SA_NAME selbst aus und einige Werte werden generiert, während Sie die Schritte durchgehen.

Platzhalter Quelle Beschreibung
ORG Suchen Der Name Ihrer Apigee-Organisation. Dies ist normalerweise PROJECT_ID. Führen Sie den Befehl gcloud apigee organizations list aus, um die Organisationen aufzulisten, auf die Sie zugreifen können.
ENV Suchen Eine Umgebung in Ihrer Organisation, z. B. test. In Teil 1, Schritt 4 wird gezeigt, wie Sie sie auflisten.
PROJECT_ID Suchen Die ID des Google Cloud-Projekts, das Ihre Apigee-Organisation enthält, z. B. my-apigee-project. Führen Sie gcloud config get project aus, um das aktive Projekt auszugeben.
HOSTNAME Suchen Ein Hostname einer Umgebungsgruppe, die ENV enthält, z. B. api.example.com. Teil 1, Schritt 5 zeigt, wo Sie sie finden.
SA_NAME Sie wählen aus, Ein Name für das Dienstkonto, das Sie in Teil 2, Schritt 3 erstellen, z. B. apigee-ai-gateway.
PROJECT_NUMBER Suchen Die Projektnummer von PROJECT_ID, z. B. 123456789012. In Teil 2, Schritt 3 wird der Befehl gezeigt, mit dem sie ausgegeben wird.
REGION Sie wählen aus, Optional. Eine Region, in der Ihr Modell bereitgestellt wird, z. B. us-central1. Sie benötigen sie nur, wenn Sie das Feature gemini-target auf einen regionalen Endpunkt umstellen.
REVISION Generiert Die Proxy-Versionsnummer, die der Importbefehl in Teil 2, Schritt 4 ausgibt, z. B. 1.
API_KEY Generiert Der API-Schlüssel, den Apigee generiert, wenn Sie eine Entwickler-App in Teil 2, Schritt 6 registrieren.

Teil 1: Einfachen API-Proxy erstellen

In diesem Abschnitt erstellen Sie einen Proxy, der Anfragen an den Apigee-Mock-Zieldienst weiterleitet und eine Ratenbegrenzung erzwingt.

Schritt 1: Vorlage erstellen

Eine Vorlage ist die Datei, die Sie bereitstellen. Darin werden der Basispfad, die Routen und das Backend-Ziel des Proxys definiert und die einzuschließenden Features aufgeführt.

Erstellen Sie ein Projektverzeichnis für Ihre Vorlagen mit einem features-Unterverzeichnis für die verwendeten Features:

mkdir -p proxy-templates/features
cd proxy-templates

Wenn Sie diesen Teil abgeschlossen haben, sieht das Projektverzeichnis so aus:

proxy-templates/
  hello-proxy.yaml
  features/
    spike-arrest.yaml

Erstellen Sie im Verzeichnis proxy-templates eine Datei mit dem Namen 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:
- ./features/spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

In dieser Vorlage wird Folgendes definiert:

  • Ein Endpunkt mit dem Basispfad /hello. Clients rufen den Proxy über diesen Pfad auf.
  • Eine Route, die Anfragen an das Ziel mit dem Namen default sendet.
  • Ein Ziel, das auf die Backend-URL verweist.
  • Ein Feature, spike-arrest.yaml, das Sie als Nächstes erstellen.

Schritt 2: Feature erstellen

Ein Feature ist eine wiederverwendbare Konfigurationseinheit, die Richtlinien enthält. Eine Vorlage kann Richtlinien nicht direkt enthalten. Daher befindet sich die Richtlinie zur Ratenbegrenzung in einem Feature.

Erstellen Sie im Verzeichnis features eine Datei mit dem Namen 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}"

Diese Funktion:

  • Definiert eine SpikeArrest-Richtlinie, die die Anforderungsrate begrenzt.
  • Verwendet defaultEndpoint.flows, um die Richtlinie dem PreFlow der Anfrage hinzuzufügen, damit sie bei jeder Anfrage ausgeführt wird.
  • Deklariert einen Parameter, RATE, dessen Standardwert (30ps) beim Kompilieren des Proxys durch {RATE} ersetzt wird.

Schritt 3: Proxy importieren

Importieren Sie die Vorlage, um eine API-Proxy-Überarbeitung zu erstellen. Führen Sie diesen Befehl im Verzeichnis proxy-templates aus, das die Vorlage enthält:

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

Die Befehlszeile kompiliert die Vorlage und ihre Funktion in ein API-Proxy-Bundle, lädt es hoch und gibt die neue Proxy-Version aus. Beim Importieren wird eine Version erstellt, aber nicht bereitgestellt.

Schritt 4: Proxy bereitstellen

Listen Sie die Umgebungen in Ihrer Organisation auf:

gcloud apigee environments list --organization=ORG

Der Befehl gibt die Umgebungsnamen aus. Wählen Sie eine aus, die als ENV verwendet werden soll, und stellen Sie die Überarbeitung darin bereit:

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

Standardmäßig wird mit diesem Befehl die neueste Version bereitgestellt. Wenn Sie eine bestimmte Version bereitstellen möchten, übergeben Sie die Nummer als erstes Argument, z. B. gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Wenn bereits ein anderer Proxy im selben Basispfad bereitgestellt ist, fügen Sie --override hinzu, um ihn ohne Ausfallzeit zu ersetzen.

Schritt 5: Proxy aufrufen

Wenn Sie den bereitgestellten Proxy über das Netzwerk aufrufen möchten, muss Ihre Umgebung an eine Umgebungsgruppe mit einem routingfähigen Hostnamen angehängt sein. Wenn Sie Ihre Organisation gerade erst erstellt haben, prüfen Sie, ob dies eingerichtet ist, bevor Sie den Proxy aufrufen. Weitere Informationen finden Sie unter Umgebungen und Umgebungsgruppen.

Suchen Sie den Hostnamen einer Umgebungsgruppe, die Ihre Umgebung enthält:

  1. Rufen Sie in der Google Cloud Console Apigee > Verwaltung > Umgebungen auf.
  2. Wählen Sie den Tab Umgebungsgruppen aus.
  3. Suchen Sie die Umgebungsgruppe, die Ihre Umgebung enthält, und kopieren Sie einen Wert aus der Spalte Hostnamen.

Rufen Sie den Proxy unter diesem Hostnamen auf und verwenden Sie den Basispfad aus Ihrer Vorlage:

curl https://HOSTNAME/hello

Ersetzen Sie HOSTNAME durch den kopierten Hostnamen. Eine erfolgreiche Antwort stammt vom simulierten Zieldienst.

Teil 2: KI-Gateway für Gemini erstellen

In diesem Abschnitt wird ein vollständigerer Proxy erstellt: ein KI-Gateway, das Anfragen an ein Gemini-Modell auf der Gemini Enterprise Agent Platform weiterleitet, eine Ratenbegrenzung erzwingt und einen API-Schlüssel erfordert. Es verwendet eine Vorlage, drei Features und ein Dienstkonto.

Im Gegensatz zum einfachen Proxy in Teil 1 ruft dieser Proxy einen Google Cloud-Dienst (Agent Platform) auf. Das Feature gemini-target verwendet auth: GoogleAccessToken. Daher hängt Apigee an jede Anfrage an die Agent Platform ein Google OAuth-Token an. Dieses Token wird für ein Dienstkonto ausgestellt, das Sie erstellen und dann bei der Bereitstellung des Proxys angeben. Daher wird in diesem Teil ein Schritt zum Erstellen dieses Dienstkontos hinzugefügt (Schritt 3).

Prüfen Sie vor dem Start, ob die Agent Platform API im Projekt, in dem das Modell gehostet wird, aktiviert ist, wie unter Vorbereitung beschrieben. Sie müssen die Agent Platform noch nicht verwendet haben.

In Teil 2 ist PROJECT_ID die ID des Projekts Ihrer Apigee-Organisation, z. B. my-apigee-project. In Teil 2 wird dieses Projekt durchgängig verwendet: Sie aktivieren die API darin, erstellen das Dienstkonto darin und legen es als MODEL_PROJECT_ID-Wert der Vorlage fest.

Schritt 1: Vorlage erstellen

Erstellen Sie im Verzeichnis proxy-templates aus Teil 1 eine Datei mit dem Namen 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:
- ./features/spike-arrest.yaml
- ./features/verify-api-key.yaml
- ./features/gemini-target.yaml
parameters:
- name: MODEL_PROJECT_ID
  default: PROJECT_ID
- name: MODEL
  default: gemini-3.8-flash
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

In der Liste parameters werden Werte für die Parameter festgelegt, die vom Feature gemini-target deklariert werden. Dieses Feature erstellen Sie im nächsten Schritt. Ersetzen Sie PROJECT_ID durch die Projekt-ID, die Sie zum Aktivieren der API verwendet haben, z. B. my-apigee-project.

Schritt 2: Features erstellen

Die Vorlage verwendet drei Funktionen. Verwenden Sie das Feature spike-arrest.yaml aus Teil 1 wieder und erstellen Sie die anderen beiden im Verzeichnis features. Wenn Sie diesen Schritt abgeschlossen haben, sieht das Projektverzeichnis so aus:

proxy-templates/
  hello-proxy.yaml
  ai-gateway.yaml
  features/
    spike-arrest.yaml
    verify-api-key.yaml
    gemini-target.yaml

Erstellen Sie features/verify-api-key.yaml, um einen API-Schlüssel im Header x-api-key anzufordern:

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

Erstellen Sie features/gemini-target.yaml, um die Weiterleitung an ein Gemini-Modell zu ermöglichen, das mit einem Google-Zugriffstoken authentifiziert wird:

gateway: apigee
schemaVersion: 1.0.0
name: gemini-target
displayName: Gemini Target
type: feature
description: Routes requests to a Gemini model on the Gemini Enterprise Agent Platform, authenticated with a Google access token.
categories:
- llm
parameters:
- name: MODEL_PROJECT_ID
  displayName: Model Project ID
  description: Google Cloud project that hosts the Gemini model. Supplied by the template; no default.
- name: MODEL
  displayName: Model
  description: The Gemini model to route to.
  default: gemini-3.8-flash
  examples:
  - gemini-3.8-flash
  - gemini-4-argon
targets:
- name: gemini
  url: https://aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/global/publishers/google/models/{MODEL}:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

Mit der Funktion gemini-target werden zwei Parameter deklariert und in die Ziel-URL eingefügt:

  • MODEL_PROJECT_ID: das Google Cloud -Projekt, in dem das Modell gehostet wird. Es gibt keinen Standardwert. Daher muss die Vorlage auf Ihre Projekt-ID festgelegt werden.
  • MODEL: das aufzurufende Gemini-Modell. Der Standardwert des Features ist gemini-3.8-flash.

Wenn die Befehlszeile die Vorlage kompiliert, wird jeder Parameter so aufgelöst:

  1. Wenn die Liste parameters der Vorlage einen Eintrag mit demselben Namen und einem nicht leeren default enthält, verwendet die Befehlszeile diesen Wert.
  2. Andernfalls verwendet die Befehlszeile die default des Features.
  3. Wenn weder die eine noch die andere Option einen Wert festlegt, ersetzt die Befehlszeile {name} durch einen leeren String. Beim Import wird kein Fehler gemeldet. Wenn also MODEL_PROJECT_ID fehlt, wird eine Ziel-URL ohne Projekt-ID erstellt.

Es gibt kein Befehlszeilen-Flag, um Parameterwerte beim Importieren festzulegen. Wenn Sie ein anderes Projekt oder Modell verwenden möchten, bearbeiten Sie den Wert in der Liste parameters der Vorlage und importieren Sie die Vorlage noch einmal.

Das Feature gemini-target verwendet auth: GoogleAccessToken, damit Apigee jeder Anfrage an die Agent-Plattform ein Google-Zugriffstoken anhängt.

Die URL verwendet den globalen Endpunkt (Host aiplatform.googleapis.com und locations/global), der gemini-3.8-flash bereitstellt und Anfragen an verfügbare Kapazitäten in verschiedenen Regionen weiterleitet. Beim globalen Endpunkt müssen Sie keine Region auswählen.

Wenn Sie ein anderes Modell aufrufen möchten, setzen Sie MODEL in der Liste parameters der Vorlage auf die ID des Modells. Führen Sie folgenden Befehl aus, um die Gemini-Modelle aufzulisten, die Sie aufrufen können:

gcloud ai model-garden models list --model-filter=gemini

Jeder Wert in der Spalte MODEL_ID sieht so aus: google/gemini-3.8-flash@default. Legen Sie für MODEL den Teil zwischen google/ und @ fest, z. B. gemini-4-argon. Auf der Modellkarte in Model Garden in derGoogle Cloud Console wird dieselbe ID angezeigt. Wenn Sie prüfen möchten, ob ein Modell den globalen Endpunkt unterstützt, rufen Sie den Tab Global unter Standorte für Google-Modellendpunkte auf.

Wenn Sie steuern müssen, welche Region Anfragen verarbeitet, ersetzen Sie die Zeile url in features/gemini-target.yaml durch die regionale Form, die die Region sowohl im Host als auch im Pfad angibt:

  url: https://REGION-aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/REGION/publishers/google/models/{MODEL}:generateContent

Ersetzen Sie REGION durch eine Region, die Ihr Modell bereitstellt, wie in den Tabellen Google-Modellendpunktstandorte aufgeführt. Informationen dazu, wann Sie den globalen Endpunkt vermeiden sollten, finden Sie unter Globaler Endpunkt.

Schritt 3: Dienstkonto für den Proxy erstellen

Da das Feature gemini-target auth: GoogleAccessToken verwendet, ruft der bereitgestellte Proxy die Agent Platform als Dienstkonto auf. Erstellen Sie dieses Dienstkonto, gewähren Sie ihm Zugriff auf die Agent Platform und lassen Sie den Apigee-Dienst-Agent es verwenden. Sie geben dieses Dienstkonto an, wenn Sie den Proxy in Schritt 5 bereitstellen. Weitere Informationen finden Sie unter Google-Authentifizierung verwenden.

  1. Erstellen Sie ein nutzerverwaltetes Dienstkonto im selben Google Cloud -Projekt wie Ihre Apigee-Organisation. (Das Compute Engine-Standarddienstkonto wird nicht akzeptiert.) Weitere Möglichkeiten zum Erstellen eines Dienstkontos finden Sie unter Dienstkonten erstellen und verwalten.
    gcloud iam service-accounts create SA_NAME \
        --project=PROJECT_ID \
        --display-name="Apigee AI gateway"

    Wählen Sie einen aussagekräftigen Namen für SA_NAME aus, z. B. apigee-ai-gateway. Mit dem Befehl wird das Dienstkonto SA_NAME@PROJECT_ID.iam.gserviceaccount.com erstellt, z. B. apigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com.

  2. Gewähren Sie dem Dienstkonto Zugriff auf das Backend, das es aufruft. Weisen Sie für ein Agent Platform-Ziel die Rolle Agent Platform User (roles/aiplatform.user) zu:
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/aiplatform.user"

    Wenn die IAM-Richtlinie Ihres Projekts bereits bedingte Rollenbindungen enthält, fügen Sie diesem Befehl --condition=None hinzu.

  3. Lassen Sie den Apigee-Dienst-Agent Tokens für das Dienstkonto erstellen, indem Sie ihm die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) für das Dienstkonto zuweisen:
    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"

    Führen Sie gcloud projects describe PROJECT_ID --format='value(projectNumber)' aus, um PROJECT_NUMBER zu finden.

Schritt 4: Proxy importieren

Importieren Sie die Vorlage, um eine API-Proxy-Überarbeitung zu erstellen. Führen Sie diesen Befehl im Verzeichnis proxy-templates aus, das die Vorlage enthält:

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

Notieren Sie sich die Versionsnummer in der Befehlsausgabe. Sie benötigen sie in Schritt 5. Wenn Sie nur die Revisionsnummer ausgeben möchten, fügen Sie dem Importbefehl --format="value(revision)" hinzu.

Schritt 5: Proxy mit dem Dienstkonto bereitstellen

Die Bereitstellung des KI-Gateways unterscheidet sich in zwei Punkten vom einfachen Proxy in Teil 1:

  • Sie müssen das Dienstkonto angeben, das Sie in Schritt 3 erstellt haben. Wenn Sie ohne ein solches Konto bereitstellen, schlägt die Bereitstellung mit dem Fehler MISSING_SERVICE_ACCOUNT fehl.
  • Sie müssen die Bereitstellung in einer Intermediate- oder Comprehensive-Umgebung vornehmen. Dieser Proxy verwendet eine erweiterbare Richtlinie, die von einer Basis-Umgebung nicht unterstützt wird. Die Bereitstellung in einer solchen Umgebung schlägt mit dem Fehler Erweiterbarer Proxy kann nicht in einer Basisumgebung bereitgestellt werden fehl. Der Befehl gcloud apigee environments list gibt den Umgebungstyp nicht aus. Rufen Sie in der Google Cloud Console Apigee > Verwaltung > Umgebungen auf, um dies zu prüfen. Weitere Informationen finden Sie unter Apigee-Umgebungstypen.

Apigee-Benutzeroberfläche: Stellen Sie den Proxy bereit und geben Sie SA_NAME@PROJECT_ID.iam.gserviceaccount.com ein, wenn Sie nach einem Dienstkonto gefragt werden. Eine Anleitung finden Sie unter API-Proxy bereitstellen.

Deployment API: Rufen Sie die Deployments API auf und übergeben Sie das Dienstkonto als Suchparameter serviceAccount. Ersetzen Sie REVISION durch die Versionsnummer aus Schritt 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"

Die Bereitstellungsanfrage wird sofort zurückgegeben. Die Bereitstellung erfolgt asynchron. Fragen Sie den Bereitstellungsstatus der Überarbeitung ab, der PROGRESSING meldet, bis er zu READY wird:

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

Wenn der Proxy kompiliert wird, fügen die Features spike-arrest und verify-api-key ihre Richtlinien dem Anfrage-PreFlow hinzu (zuerst die Ratenbegrenzung, dann die API-Schlüsselprüfung). Das Feature gemini-target fügt das Agent Platform-Backend hinzu. Nach Abschluss der Bereitstellung authentifiziert sich der Proxy bei der Agent Platform als Ihr Dienstkonto.

Schritt 6: API-Schlüssel abrufen

Das Feature verify-api-key lehnt alle Anfragen ab, die keinen gültigen API-Schlüssel enthalten. Sie benötigen also einen Schlüssel, bevor Sie den Proxy aufrufen können. Ein API-Schlüssel ist ein Berechtigungsnachweis einer Entwickler-App, die mit einem API-Produkt verknüpft ist, das diesen Proxy enthält. Führen Sie die folgenden Aufgaben aus, die unter Veröffentlichungen – Übersicht beschrieben sind:

  1. Erstellen Sie ein API-Produkt, das den ai-gateway-Proxy enthält. Geben Sie im Produktformular Folgendes ein und klicken Sie dann auf Speichern:
    • Name und Anzeigename: ein beliebiger Wert, z. B. ai-gateway-product.
    • Umgebung: Die Umgebung, in der Sie den Proxy bereitgestellt haben (ENV).
    • Zugriff: Öffentlich. Lassen Sie Zugriffsanfragen automatisch genehmigen ausgewählt, damit der API-Schlüssel genehmigt wird, wenn Sie die App registrieren.
    • Klicken Sie im Bereich Vorgänge auf + VORGANG HINZUFÜGEN und legen Sie die folgenden Felder fest:
      • API-Proxy: ai-gateway.
      • Pfad: /. Anfragen werden an den Basispfad des Proxys (/v1/gemini) gesendet, ohne dass danach etwas folgt. Der Pfad / entspricht dem Basispfad. /** entspricht nur Pfaden darunter, sodass eine Anfrage an /v1/gemini mit dem Fehler oauth.v2.InvalidApiKeyForGivenResource fehlschlägt. Weitere Informationen finden Sie unter Ressourcenpfade konfigurieren.
      • Methoden: POST.
    • Lassen Sie die Felder API-Kontingentlimit, Kontingentlimit für LLM-Tokens, Kontingent des Vorgangs und den Abschnitt LLM-Vorgänge leer. Das Feature spike-arrest im Proxy erzwingt die Ratenbegrenzung.
  2. App-Entwickler registrieren
  3. Registrieren Sie eine Entwickler-App und wählen Sie das API-Produkt aus, wenn Sie die App erstellen, damit der neue Schlüssel von Anfang an mit dem Produkt verknüpft ist.

Durch die Registrierung der App wird der Schlüssel generiert. Informationen zum Abrufen finden Sie unter API-Schlüssel und Secret aufrufen.

Schritt 7: Proxy aufrufen

Suchen Sie den Hostnamen Ihrer Umgebungsgruppe, wie in Teil 1, Schritt 5 beschrieben, und rufen Sie dann den Proxy im Basispfad /v1/gemini auf. Übergeben Sie den API-Schlüssel im Header x-api-key und senden Sie einen Gemini-generateContent-Anfragetext:

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

Ersetzen Sie HOSTNAME durch den Hostnamen Ihrer Umgebungsgruppe und API_KEY durch den Schlüssel aus Schritt 6. Eine erfolgreiche Antwort ist die JSON-Ausgabe des Modells. Wenn Sie den Schlüssel weglassen, wird von der VerifyAPIKey-Richtlinie ein Autorisierungsfehler zurückgegeben. Das bestätigt, dass die verify-api-key-Funktion wirksam ist. Weitere Möglichkeiten zum Übergeben eines Schlüssels finden Sie unter Anfrage mit einem gültigen API-Schlüssel senden.

Nächste Schritte