Proxy mit YAML konfigurieren

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Sie können einen Apigee API-Proxy in YAML definieren und mit der Google Cloud CLI bereitstellen. Das ist eine Alternative zum Erstellen des herkömmlichen XML-Proxy-Bundles. Sie beschreiben die Endpunkte, Routen, Richtlinien und Backend-Ziele eines Proxys in YAML-Dateien, die als Apigee Feature Templates bezeichnet werden. Apigee kompiliert sie dann für Sie in ein Standard-API-Proxy-Bundle.

Da das Ergebnis ein gewöhnliches Apigee-API-Proxy-Bundle ist, wird ein auf diese Weise erstellter Proxy in derselben Apigee-Laufzeit mit denselben Richtlinien und demselben Verhalten wie ein Proxy ausgeführt, den Sie über die Apigee-Benutzeroberfläche oder aus einem XML-Bundle erstellen.

Warum YAML zum Definieren von Proxys verwenden?

Das herkömmliche Apigee API-Proxy-Format ist ein ZIP-Archiv mit XML-Dateien. YAML bietet eine Alternative, die viele Entwickler schneller lesen, schreiben und überprüfen können und die gut mit KI-gestützten und agentenbasierten Tools funktioniert. Apigee-Funktionsvorlagen sind für Folgendes konzipiert:

  • API-Entwickler und ‑Architekten, die ein prägnantes, deklaratives Format bevorzugen und die Proxykonfiguration in der Quellcodeverwaltung behalten möchten.
  • KI-Experten, die eine standardisierte Möglichkeit suchen, ein Apigee-Gateway vor ein Modell-Backend zu stellen.
  • Plattform- und DevOps-Teams, die wiederverwendbare Teile der Proxykonfiguration verpacken und konsistent auf viele Proxys anwenden möchten.

Wichtige Konzepte

Apigee-Featurevorlagen verwenden drei Dokumenttypen. Jede Datei ist eine YAML-Datei, die durch das Feld type identifiziert wird.

Dokumenttyp type Wert Zweck
Vorlage template Der Einstiegspunkt, den Sie bereitstellen. Eine Vorlage besteht aus einem oder mehreren Features und definiert die Endpunkte und Routen des Proxys.
Funktion feature Eine wiederverwendbare Konfigurationseinheit, z. B. eine Authentifizierungsprüfung, ein Ratenlimit oder ein Back-End-Ziel, die Sie in eine Vorlage einfügen. Funktionen enthalten die Richtlinien und Ressourcen.
Proxy proxy Der vollständig aufgelöste Proxy, den die CLI beim Kompilieren einer Vorlage mit ihren Funktionen erzeugt. Normalerweise ist dies eine Zwischenausgabe, die von der CLI generiert wird. Sie können aber auch eine Proxydatei direkt importieren, um sie in ein API-Proxy-Set zu übersetzen.

Sie erstellen Vorlagen und Funktionen. Apigee generiert den Proxy für Sie während der Kompilierung.

Funktionsweise

Wenn Sie eine Vorlage importieren, führt die Google Cloud CLI die folgenden Schritte lokal aus und lädt das Ergebnis dann in Apigee hoch:

  1. Kompilieren: Die CLI liest Ihre Vorlage und die Feature-Dateien, auf die sie verweist, führt sie zusammen und erstellt eine einzelne Proxydefinition.
  2. Konvertieren: Die CLI konvertiert die Proxydefinition in ein Standard-API-Proxy-Bundle für Apigee (die ZIP-Datei mit XML-Dateien, die von Apigee erwartet wird).
  3. Importieren Mit der CLI wird das Bundle in Apigee hochgeladen, wodurch eine neue Überarbeitung des API-Proxy erstellt wird.

Durch das Importieren eines Proxys wird er nicht live geschaltet. In einem separaten Schritt stellen Sie die Überarbeitung in einer Umgebung bereit, genau wie bei jedem anderen API-Proxy:

YAML template + feature files
  |  gcloud apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

Eine detaillierte Anleitung finden Sie unter API-Proxy aus einer YAML-Vorlage erstellen.

Ein kleines Beispiel

In der folgenden Vorlage wird ein Proxy definiert, der zwei Funktionen umfasst: eine, die ein Backend-Ziel hinzufügt, und eine, die eine Antwortnachricht hinzufügt:

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

Jede referenzierte Feature-Datei muss sich im selben Verzeichnis wie die Vorlage befinden. Ein vollständiges, ausführbares Beispiel und die verwendeten Feature-Dateien finden Sie unter API-Proxy aus einer YAML-Vorlage erstellen.

Das können Sie tun

  • Definieren Sie die Endpunkte, Basispfade, Routen, Abläufe und Backend-Ziele eines Proxys in YAML.
  • Verpacken Sie wiederverwendbare Richtlinien und Ressourcen als Funktionen und stellen Sie sie in einer Vorlage zusammen.
  • Fügen Sie die Back-End-Authentifizierung für Google Cloud-Ziele hinzu, z. B. ein Google-Zugriffstoken für ein Vertex AI-Back-End.
  • Importieren Sie eine Vorlage als neue API-Proxy-Überarbeitung mit der Google Cloud CLI und stellen Sie sie dann mit dem Standardbereitstellungsbefehl bereit.

Beschränkungen

Beachten Sie beim Erstellen von Vorlagen und Funktionen Folgendes:

  • Funktionen sind lokale Dateien. Eine Vorlage kann nur auf Feature-Dateien verweisen, die sich im selben Verzeichnis befinden. Das Verweisen auf Funktionen über eine URL oder aus einem freigegebenen Katalog wird nicht unterstützt.
  • Parameterwerte verwenden ihre Standardwerte. Für Funktionen können Parameter definiert werden, aber Parameterwerte werden auf den in der Funktion definierten Standardwert aufgelöst. Es gibt kein Befehlszeilen-Flag, mit dem Parameterwerte beim Import überschrieben werden können.
  • JSONPath-Parameter werden nicht unterstützt. Ein Parameter, der einen paths-Ausdruck (JSONPath) verwendet, führt zu einem Kompilierungsfehler.
  • Tests werden nicht unterstützt. Ein tests-Abschnitt wird vom Schema akzeptiert, aber ignoriert und nicht in das generierte Bundle aufgenommen.
  • Das Schema ist strikt. Unbekannte Felder verursachen einen Fehler. Nur gateway: apigee und schemaVersion: 1.0.0 werden unterstützt.
  • Bei der Fehlerbehebung wird das generierte XML verwendet. Die Apigee-Benutzeroberfläche und die Laufzeitumgebung arbeiten mit dem generierten Bundle. Es gibt keinen Roundtrip zurück zur YAML-Quelle in der Benutzeroberfläche.

Nächste Schritte