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 Back-End-Ziele eines Proxys in YAML-Dateien, die als Apigee-Funktionsvorlagen bezeichnet werden. Apigee kompiliert sie dann für Sie zu einem 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-Laufzeitumgebung mit denselben Richtlinien und demselben Verhalten ausgeführt wie ein Proxy, den Sie in der Apigee UI oder aus einem XML-Bundle erstellen.

Warum Proxys in YAML definieren?

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 folgende Nutzer gedacht:

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

Wichtige Konzepte

Apigee-Funktionsvorlagen verwenden drei Dokumenttypen. Jeder 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 einer oder mehreren Funktionen und definiert die Endpunkte und Routen des Proxys.
Funktion feature Eine wiederverwendbare Konfigurationseinheit wie eine Authentifizierungs prü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 erstellt, wenn sie eine Vorlage mit ihren Funktionen kompiliert. Normalerweise ist dies eine Zwischenausgabe, die von der CLI generiert wird. Sie können aber auch eine Proxy-Datei direkt importieren, um sie in ein API-Proxy-Bundle 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 referenzierten Funktionsdateien, führt sie zusammen und erstellt eine einzelne Proxy-Definition.
  2. Konvertieren Die CLI konvertiert die Proxy-Definition in ein Standard Apigee-API-Proxy-Bundle (das ZIP-Archiv mit XML-Dateien, das Apigee erwartet).
  3. Importieren Die CLI lädt das Bundle in Apigee hoch, wodurch eine neue Version 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 beta 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.

Minimalbeispiel

Die folgende Vorlage definiert einen Proxy, der aus zwei Funktionen besteht: eine, die ein Back-End-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

Alle referenzierten Funktionsdateien müssen sich im selben Verzeichnis wie die Vorlage befinden. Ein vollständiges, ausführbares Beispiel und die verwendeten Funktionsdateien finden Sie unter API-Proxy aus einer YAML-Vorlage erstellen.

Das können Sie tun

  • Definieren Sie die Endpunkte, Basispfade, Routen, Abläufe und Back-End-Ziele eines Proxys in YAML.
  • Verpacken Sie wiederverwendbare Richtlinien und Ressourcen als Funktionen und fügen 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, stellen Sie sie dann mit dem Standardbefehl zum Bereitstellen bereit.

Beschränkungen

Beachten Sie beim Erstellen von Vorlagen und Funktionen Folgendes:

  • Funktionen sind lokale Dateien. Eine Vorlage kann nur auf Funktions dateien verweisen, die sich im selben Verzeichnis befinden. Das Referenzieren von Funktionen über eine URL oder aus einem freigegebenen Katalog wird nicht unterstützt.
  • Parameterwerte verwenden ihre Standardwerte. Funktionen können Parameter definieren, aber Parameterwerte werden auf den in der Funktion definierten Standardwert aufgelöst. Es gibt kein Befehlszeilen-Flag, um Parameterwerte beim Importieren zu überschreiben.
  • JSONPath-Parameter werden nicht unterstützt. Ein Parameter, der einen paths -Ausdruck (JSONPath) verwendet, führt zu einem Fehler bei der Kompilierung.
  • Tests werden nicht unterstützt. Ein tests-Abschnitt wird vom Schema akzeptiert , aber ignoriert und nicht in das generierte Bundle aufgenommen.
  • Das Schema ist streng. 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 UI und die Laufzeitumgebung arbeiten mit dem generierten Bundle. Es gibt in der UI keine Möglichkeit, zur YAML-Quelle zurückzukehren.

Nächste Schritte