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 einem Gemini-Modell vorangestellt ist.

Hintergrundinformationen finden Sie unter Proxy mit YAML konfigurieren. Das vollständige Schema finden Sie in der Referenz zur YAML-Konfiguration von 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 das Google Cloud CLI.
  • Installieren Sie die gcloud-Betakomponente, um auf die in dieser Anleitung verwendeten Befehle zuzugreifen: 
    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 außerdem eine Zwischenphasen oder Umfassende-Umgebung erforderlich (keine Basis-Umgebung). Weitere Informationen finden Sie unter Apigee Umgebungstypen.
  • Prüfen Sie, ob Sie 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) in der Zielumgebung und API-Leser (roles/apigee.apiReaderV2) auf Projektebene.
    • Zum Erstellen des API-Produkts, des Entwicklers und der App, die den API-Schlüssel erzeugen in Teil 2, Schritt 6: 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. Sie definiert den Basispfad, die Routen und das Backend-Ziel Ihres Proxys und listet die einzuschließenden Features auf.

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:

  • Einen Endpunkt mit dem Basispfad /hello. Clients rufen den Proxy unter diesem 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 keine Richtlinien direkt enthalten. Daher befindet sich die Richtlinie zur Ratenbegrenzung 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}"

Dieses Feature:

  • 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-Überarbeitung zu erstellen. Führen Sie diesen Befehl im Verzeichnis mit Ihren Dateien aus:

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

Die CLI kompiliert die Vorlage und das Feature in ein API-Proxy-Bundle, lädt es hoch und gibt die neue Proxy-Version aus. Durch den Import 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

Standardmäßig wird mit diesem Befehl die neueste Überarbeitung bereitgestellt. Wenn Sie eine bestimmte Überarbeitung 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 mit demselben 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 angehängt sein, die einen routingfähigen Hostnamen hat. 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. Gehen Sie in der Google Cloud -Console zu Apigee > Verwaltung > Umgebungen.
  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 mit diesem Hostnamen und dem Basispfad aus Ihrer Vorlage auf:

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 erstellen Sie einen vollständigeren Proxy: ein KI-Gateway, das Anfragen an ein Gemini-Modell in Vertex AI weiterleitet, ein Ratenlimit erzwingt und einen API-Schlüssel erfordert. Dazu werden eine Vorlage, drei Features und ein Dienstkonto verwendet.

Im Gegensatz zum einfachen Proxy in Teil 1 ruft dieser Proxy einen Google Cloud-Dienst (Vertex AI) auf. Das Feature gemini-target verwendet auth: GoogleAccessToken, sodass Apigee jeder Anfrage an Vertex AI ein Google-OAuth-Token anhängt. 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: Features erstellen

Erstellen Sie im selben Verzeichnis die drei Featuredateien.

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

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

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 wurde:

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). Dieses Feature verwendet auth: GoogleAccessToken, sodass Apigee jeder Anfrage an Vertex AI ein Google-Zugriffstoken anhängt.

Modelle sind nicht an allen Standorten verfügbar und die URL hängt vom verwendeten Standort ab. Die vorherige URL ist die regionale Form, die für ein Modell funktioniert, das von 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 das Feature gemini-target auth: GoogleAccessToken verwendet, 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 Dienst konto 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-Nutzer (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. 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 gewähren: 
    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 ermitteln.

Schritt 4: Proxy importieren

Importieren Sie die Vorlage, um eine API-Proxy-Überarbeitung zu erstellen:

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

Notieren Sie sich die Überarbeitungsnummer in der Befehlsausgabe. Sie benötigen sie in Schritt 5. Wenn Sie nur die Versionsnummer 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 von der des einfachen Proxys in Teil 1:

  • Sie müssen das in Schritt 3 erstellte Dienstkonto angeben. Wenn Sie die Bereitstellung ohne Dienstkonto vornehmen, schlägt die Bereitstellung mit dem MISSING_SERVICE_ACCOUNT Fehler fehl.
  • Sie müssen die Bereitstellung in einer Zwischenphasen- oder Umfassenden 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 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 Eingabe eines Dienstkontos ein SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Eine Anleitung finden Sie unter API Proxy bereitstellen.

Deployment API:Rufen Sie die Deployments API auf und übergeben Sie das Dienstkonto als serviceAccount Abfrage parameter. Ersetzen Sie REVISION durch die Überarbeitungsnummer 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 lautet PROGRESSING, 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 Features spike-arrest und verify-api-key ihre Richtlinien dem PreFlow der Anfrage hinzu (zuerst Ratenbegrenzung, dann API-Schlüsselprüfung) und das Feature gemini-target fügt das Vertex AI-Backend hinzu. Nach Abschluss der Bereitstellung authentifiziert sich der Proxy bei Vertex AI 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 Anmeldedaten 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 Übersichtbeschrieben sind:

  1. Erstellen Sie ein API-Produkt, das den ai-gateway Proxy und die Umgebung enthält, in der Sie ihn bereitgestellt haben.
  2. Registrieren Sie einen App-Entwickler.
  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 des Schlüssels 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 mit dem 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. Dadurch wird bestätigt, dass das Feature verify-api-key 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