OpenAPI 3.x-Erweiterungen in API Gateway

API Gateway unterstützt eine Reihe von Google-spezifischen Erweiterungen der OpenAPI-Spezifikation, die das Verhalten des Gateways konfigurieren. Mit diesen Erweiterungen können Sie API-Verwaltungseinstellungen, Authentifizierungsmethoden, Kontingentlimits und Back-End-Integrationen direkt in Ihrem OpenAPI-Dokument angeben. Wenn Sie diese Erweiterungen kennen, können Sie das Verhalten Ihres Dienstes anpassen und in API Gateway-Funktionen einbinden.

Auf dieser Seite werden Google-spezifische Erweiterungen der OpenAPI-Spezifikation 3.x beschrieben.

Obwohl die folgenden Beispiele im YAML-Format vorliegen, wird auch JSON unterstützt.

x-google-api-management

Erforderlich.

Die x-google-api-management-Erweiterung definiert API-Verwaltungseinstellungen der obersten Ebene für Ihren Dienst. Platzieren Sie diese Erweiterung im Stammverzeichnis Ihres OpenAPI-Dokuments.

In der folgenden Tabelle werden die Felder für x-google-api-management beschrieben:

Feld Typ Erforderlich Standard Beschreibung
metrics map[string]Metric Nein Leer Definieren Sie Messwerte, um Kontingentlimits zu erzwingen.
quota map[string]Quota Nein Leer Geben Sie Kontingentlimits für Ihren Dienst an.
backends map[string]Backend Ja Leer Backend-Dienste konfigurieren.
apiName string Nein Leer Weisen Sie den im OpenAPI-Dokument definierten Vorgängen einen Namen zu.
ai AI Nein Leer Konfigurieren Sie KI-Funktionen, einschließlich des Modell-Routings.

Metric-Objekt

Das Objekt Metric definiert einen Messwert, der für die Kontingenterzwingung verwendet wird.

In der folgenden Tabelle werden die Felder für Metric beschrieben:

Feld Typ Erforderlich Standard Beschreibung
displayName string Nein Leer Anzeigename des Messwerts.

Quota-Objekt

Das Objekt Quota definiert Kontingentlimits.

In der folgenden Tabelle werden die Felder für Quota beschrieben:

Feld Typ Erforderlich Standard Beschreibung
limits map[string]QuotaLimit Nein Leer Kontingentlimits festlegen

Quota Limit-Objekt

Das QuotaLimit-Objekt definiert ein bestimmtes Kontingentlimit.

In der folgenden Tabelle werden die Felder für QuotaLimit beschrieben:

Feld Typ Erforderlich Beschreibung
metric string Ja Verweisen Sie auf einen Messwert, der in diesem OpenAPI-Dokument deklariert ist.
values int64 Ja Legen Sie den Maximalwert fest, den die Messwert erreichen kann, bevor Clientanfragen abgelehnt werden.

Backends-Objekt

Erforderlich.

Mit dem Backends-Objekt wird ein Backend-Dienst konfiguriert. Sie müssen entweder jwtAudience oder disableAuth festlegen.

In der folgenden Tabelle werden die Felder für Backends beschrieben:

Feld Typ Erforderlich Standard Beschreibung
address string Ja Leer Geben Sie die URL des Back-Ends an.
jwtAudience string Nein Leer Standardmäßig erstellt API Gateway das Instanz-ID-Token mit einer JWT-Zielgruppe, die mit dem Adressfeld übereinstimmt. Die manuelle Angabe von jwt_audience ist nur erforderlich, wenn das Ziel-Backend eine JWT-basierte Authentifizierung verwendet und sich die erwartete Zielgruppe vom im Adressfeld angegebenen Wert unterscheidet. Für Remote-Back-Ends, die in App Engine oder mit IAP bereitgestellt werden, müssen Sie die JWT-Zielgruppe überschreiben. App Engine und IAP verwenden ihre OAuth-Client-ID als erwartete Zielgruppe.
disableAuth bool Nein False Verhindern Sie, dass der Data-Plane-Proxy ein Instanz-ID-Token abruft und es an die Anfrage anhängt.
pathTranslation string Nein APPEND_PATH_TO_ADDRESS oder CONSTANT_ADDRESS Legt die Strategie für die Pfadübersetzung fest, wenn Anfragen an das Ziel-Back-End per Proxy weitergeleitet werden. Wenn x-google-backend auf der obersten Ebene festgelegt ist und kein path_translation angegeben ist, ist der Standardwert für pathTranslation APPEND_PATH_TO_ADDRESS. Wenn x-google-backend auf der Vorgangsebene festgelegt ist und kein path_translation angegeben ist, ist der Standardwert CONSTANT_ADDRESS.
deadline double Nein 15.0 Geben Sie an, wie viele Sekunden lang auf eine vollständige Antwort auf eine Anfrage gewartet werden soll. Bei Antworten, die länger als diese Frist dauern, tritt eine Zeitüberschreitung auf. Die maximale Frist beträgt 600 Sekunden.
protocol string Nein http/1.1 Legen Sie das Protokoll für das Senden einer Anfrage an das Backend fest. Unterstützte Werte sind http/1.1 und h2.

AI-Objekt

Mit dem AI-Objekt werden KI-Funktionen für Ihren Dienst konfiguriert, z. B. das Modellrouting.

In der folgenden Tabelle werden die Felder für AI beschrieben:

Feld Typ Erforderlich Standard Beschreibung
models Models Nein Leer KI-Modellintegrationen konfigurieren

Models-Objekt

Das Models-Objekt definiert modellspezifische Konfigurationen.

In der folgenden Tabelle werden die Felder für Models beschrieben:

Feld Typ Erforderlich Standard Beschreibung
routing Routing Nein Leer Einstellungen für das Modellrouting konfigurieren

Routing-Objekt

Das Routing-Objekt definiert Modellweiterleitungsregeln und Router.

In der folgenden Tabelle werden die Felder für Routing beschrieben:

Feld Typ Erforderlich Standard Beschreibung
routers map[string]Router Nein Leer Benannte Modellrouter definieren

Router-Objekt

Das Router-Objekt definiert einen benannten Modellrouter.

In der folgenden Tabelle werden die Felder für Router beschrieben:

Feld Typ Erforderlich Standard Beschreibung
defaultModel DefaultModel Ja Leer Das erforderliche Fallback-Modellziel, das verwendet wird, wenn eine eingehende Anfrage keiner expliziten Regel entspricht.
rules [Rule] Nein Leer Liste der expliziten Modell-Routingregeln.

DefaultModel-Objekt

Das DefaultModel-Objekt gibt das Fallback-Ziel an.

In der folgenden Tabelle werden die Felder für DefaultModel beschrieben:

Feld Typ Erforderlich Standard Beschreibung
backend string Ja Leer Verweisen Sie auf ein Backend, das in x-google-api-management.backends deklariert ist.
targetModel string Ja Leer Geben Sie die Zielmodell-ID im Format <provider>/<model-id> an. Bei OpenAI-kompatiblen Routen wird dieser Wert als ausgehendes model-Attribut im Anfragebody weitergeleitet, wenn ein Fallback auftritt.

Rule-Objekt

Das Rule-Objekt definiert eine explizite Modellroutingregel.

In der folgenden Tabelle werden die Felder für Rule beschrieben: