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 Feature Template 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 verwendet.

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

Hinweis

  • Aktivieren Sie die Vertex AI API in Ihrem Google Cloud-Projekt, damit der Proxy mit Gemini-Modellen kommunizieren kann. 
    gcloud services enable aiplatform.googleapis.com
  • Installieren und initialisieren Sie die Google Cloud CLI.
  • Für den Zugriff auf die in dieser Anleitung verwendeten Befehle installieren Sie die „gcloud beta“-Komponente: 
    gcloud components install beta
  • 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. Für das KI-Gateway in Teil 2 ist zusätzlich eine Intermediate- oder Comprehensive-Umgebung (keine Base-Umgebung) erforderlich. 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 benötigen Sie die Rolle Environment Admin (roles/apigee.environmentAdmin) für die Zielumgebung und API Reader (roles/apigee.apiReaderV2) auf Projektebene.
    • Zum Erstellen des API-Produkts, des Entwicklers und der App, die den API-Schlüssel in Teil 2, Schritt 6 generieren: API-Administrator (roles/apigee.apiAdmin) und Entwickleradministrator (roles/apigee.developerAdmin). Die vollständige Liste der Rollen finden Sie unter Apigee-Rollen.

Teil 1: Einfachen API-Proxy erstellen

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

Schritt 1: Vorlage erstellen

Eine Vorlage ist die Datei, die Sie bereitstellen. Darin werden der Basispfad, die Routen und das Backend-Ziel Ihres Proxys definiert und die Funktionen aufgeführt, die enthalten sein sollen.

Erstellen Sie ein Verzeichnis für Ihren Proxy und dann 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:
- spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

Diese Vorlage definiert:

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

Schritt 2: Funktion erstellen

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

Erstellen Sie im selben Verzeichnis wie die Vorlage 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 Anfragerate 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-Revision zu erstellen. Führen Sie diesen Befehl in dem Verzeichnis aus, das Ihre Dateien enthält:

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

Die CLI kompiliert die Vorlage und ihr Feature in ein API-Proxy-Bundle, lädt es hoch und gibt die neue Proxy-Version aus. Beim Importieren wird eine Überarbeitung erstellt, aber nicht bereitgestellt.

Schritt 4: Proxy bereitstellen

Stellen Sie die Überarbeitung in einer Umgebung bereit:

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

Mit diesem Befehl wird standardmäßig die neueste Überarbeitung bereitgestellt. Wenn Sie eine bestimmte Revision bereitstellen möchten, übergeben Sie ihre Nummer als erstes Argument, z. B. gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Wenn bereits ein anderer Proxy unter demselben Basispfad bereitgestellt wird, 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 sie eingerichtet ist, bevor Sie den Proxy aufrufen. Weitere Informationen finden Sie unter Umgebungen und Umgebungsgruppen.

So finden 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 Hostnames.

Rufen Sie den Proxy über diesen Hostnamen auf und verwenden Sie dabei den Basispfad aus Ihrer Vorlage:

curl https://HOSTNAME/hello

Ersetzen Sie HOSTNAME durch den kopierten Hostnamen. Eine erfolgreiche Antwort stammt vom Mock-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 in Vertex AI weiterleitet, ein Ratenlimit erzwingt und einen API-Schlüssel erfordert. Es verwendet eine Vorlage, drei Funktionen und ein Dienstkonto.

Im Gegensatz zum einfachen Proxy in Teil 1 ruft dieser Proxy einen Google Cloud-Dienst (Vertex AI) auf. Für die Funktion gemini-target wird auth: GoogleAccessToken verwendet. Daher fügt Apigee jeder Anfrage an Vertex AI ein Google-OAuth-Token bei. 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).

Schritt 1: Vorlage erstellen

Erstellen Sie 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:
- spike-arrest.yaml
- verify-api-key.yaml
- gemini-target.yaml
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

Schritt 2: Funktionen erstellen

Erstellen Sie im selben Verzeichnis die drei Feature-Dateien.

Verwenden Sie das spike-arrest.yaml-Feature aus Teil 1 wieder.

Erstellen Sie verify-api-key.yaml, um einen API-Schlüssel im x-api-key-Header zu verlangen:

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 gemini-target.yaml, um Anfragen an ein Gemini-Modell weiterzuleiten, 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 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

Ersetzen Sie PROJECT_ID durch Ihre Google Cloud-Projekt-ID und REGION durch die Vertex AI-Region, die Sie verwenden (z. B. us-central1). Für diese Funktion wird auth: GoogleAccessToken verwendet, damit Apigee jedem Aufruf von Vertex AI ein Google-Zugriffstoken anhängt.

Modelle sind nicht überall verfügbar und die URL hängt vom verwendeten Standort ab. Die oben genannte URL ist die regionale Form, die für ein Modell funktioniert, das aus einer bestimmten Region bereitgestellt wird, z. B. gemini-2.5-flash in us-central1. Andere Modelle werden nur über den globalen Endpunkt bereitgestellt, der einen anderen Host und locations/global verwendet:

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

Informationen zu den Standorten, die von einem Modell unterstützt werden, finden Sie unter Generative AI an Vertex AI-Standorten.

Schritt 3: Dienstkonto für den Proxy erstellen

Da für die Funktion gemini-target auth: GoogleAccessToken verwendet wird, ruft der bereitgestellte Proxy Vertex AI als Dienstkonto auf. Erstellen Sie dieses Dienstkonto, gewähren Sie ihm Zugriff auf Vertex AI und lassen Sie es vom Apigee-Dienst-Agent 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"

    Dadurch wird das Dienstkonto SA_NAME@PROJECT_ID.iam.gserviceaccount.com erstellt.

  2. Gewähren Sie dem Dienstkonto Zugriff auf das Backend, das es aufruft. Gewähren Sie für ein Vertex AI-Ziel die Rolle 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"

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

  3. Erlauben Sie dem Apigee-Dienst-Agent, Tokens für das Dienstkonto zu 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-Revision zu erstellen:

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

Notieren Sie sich die Revisionsnummer 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 die Bereitstellung ohne eine dieser Dateien vornehmen, schlägt sie mit einem MISSING_SERVICE_ACCOUNT-Fehler fehl.
  • Sie müssen die Bereitstellung in einer Umgebung der Zwischenphase oder der umfassenden Umgebung vornehmen. Dieser Proxy verwendet eine erweiterbare Richtlinie, die in einer Base-Umgebung nicht unterstützt wird. Die Bereitstellung in einer solchen Umgebung schlägt mit dem Fehler Extensible proxy can not be deployed to a base environment fehl. Weitere Informationen finden Sie unter Apigee-Umgebungstypen.

Apigee-Benutzeroberfläche:Stellen Sie den Proxy bereit und geben Sie bei der Aufforderung zur Angabe eines Dienstkontos SA_NAME@PROJECT_ID.iam.gserviceaccount.com ein. Eine Anleitung finden Sie unter API-Proxy bereitstellen.

Deployment API:Rufen Sie die Deployments API auf und übergeben Sie das Dienstkonto als serviceAccount-Abfrageparameter. Ersetzen Sie REVISION durch die Revisionsnummer 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. Er wird als PROGRESSING gemeldet, bis er 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 Funktionen spike-arrest und verify-api-key ihre Richtlinien dem Anfrage-PreFlow hinzu (zuerst die Ratenbegrenzung, dann die API-Schlüsselprüfung). Die Funktion gemini-target fügt das Vertex AI-Back-End hinzu. Nach Abschluss der Bereitstellung authentifiziert sich der Proxy bei Vertex AI als Ihr Dienstkonto.

Schritt 6: API-Schlüssel abrufen

Die verify-api-key-Funktion 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 Anmeldedatum einer Entwickler-App, die mit einem API-Produkt verknüpft ist, das diesen Proxy enthält. Führen Sie die folgenden Aufgaben aus, die in der Übersicht zum Veröffentlichen beschrieben werden:

  1. Erstellen Sie ein API-Produkt, das den ai-gateway-Proxy und die Umgebung enthält, in der Sie ihn bereitgestellt haben.
  2. App-Entwickler registrieren
  3. Registrieren Sie eine Entwickler-App, die mit diesem API-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 der Umgebungsgruppe, wie in Teil 1, Schritt 5 beschrieben, und rufen Sie dann den Proxy über den Basispfad /v1/gemini auf. Übergeben Sie den API-Schlüssel im x-api-key-Header 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 ein Autorisierungsfehler von der VerifyAPIKey-Richtlinie zurückgegeben. Das bestätigt, dass die verify-api-key-Funktion aktiv ist. Weitere Möglichkeiten zum Übergeben eines Schlüssels finden Sie unter Anfrage mit einem gültigen API-Schlüssel senden.

Nächste Schritte