OpenAPI 3.x-Erweiterungen in API Gateway

API Gateway akzeptiert eine Reihe von Google-spezifischen Erweiterungen der OpenAPI-Spezifikation, mit denen das Verhalten des Gateways konfiguriert wird. Mit diesen Erweiterungen können Sie API-Verwaltungseinstellungen, Authentifizierungsmethoden, Kontingentlimits und Backend-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.

Die Beispiele sind zwar im YAML-Format, JSON wird aber ebenfalls unterstützt.

x-google-api-management

Erforderlich.

Die Erweiterung x-google-api-management definiert die API-Verwaltungseinstellungen auf oberster 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 Verknüpfen Sie einen Namen mit den im OpenAPI-Dokument definierten Vorgängen.
ai AI Nein Leer Funktionen für künstliche Intelligenz konfigurieren, einschließlich Modell-Routing.
mcp MCP oder bool Nein Leer MCP-Funktionen (Model Context Protocol) aktivieren oder konfigurieren

Objekt Metric

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.

Objekt Quota

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 Geben Sie Kontingentlimits an.

Objekt QuotaLimit

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 Höchstwert fest, den der Messwert erreichen kann, bevor Clientanfragen abgelehnt werden.

Objekt Backends

Erforderlich.

Das Objekt Backends konfiguriert einen Backend-Dienst. 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 Backends 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-Backends, 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, dass der Datenebenen-Proxy ein Instanz-ID-Token abruft und an die Anfrage anhängt.
pathTranslation string Nein APPEND_PATH_TO_ADDRESS oder CONSTANT_ADDRESS Legen Sie die Pfadübersetzungsstrategie fest, wenn Anfragen an das Ziel-Backend weitergeleitet werden. Wenn x-google-backend auf der obersten Ebene festgelegt ist und kein path_translation angegeben ist, ist der Standard-pathTranslation APPEND_PATH_TO_ADDRESS. Wenn x-google-backend auf Vorgangsebene festgelegt ist und kein path_translation angegeben ist, wird standardmäßig CONSTANT_ADDRESS verwendet.
deadline double Nein 15.0 Geben Sie die Anzahl der Sekunden an, die auf eine vollständige Antwort auf eine Anfrage gewartet werden soll. Bei Antworten, die diese Frist überschreiten, kommt es zu einer Zeitüberschreitung. Bei einem SSE- oder Chunked-Transfer-Endpunkt begrenzt die Frist weiterhin die Dauer des gesamten Streams. Bei einem gRPC- oder WebSocket-Endpunkt begrenzt sie stattdessen die Zeitspanne zwischen Nachrichten. Informationen zu den Zeitlimits für die einzelnen Anfragetypen finden Sie unter Stream-Frist festlegen. Lassen Sie das Feld weg oder legen Sie es auf 0 fest, um die Standardeinstellung zu verwenden. Ein negativer Wert wird abgelehnt. Die Frist kann auf bis zu 3.600 Sekunden konfiguriert werden. Ein Nicht-Streaming-Gateway erzwingt ein niedrigeres Maximum von 600 Sekunden und lehnt eine höhere Frist beim Erstellen oder Aktualisieren des Gateways ab, nicht beim Erstellen der API-Konfiguration.
protocol string Nein http/1.1 Legen Sie das Protokoll zum Senden einer Anfrage an das Backend fest. Unterstützte Werte sind http/1.1 und h2. Die Protokollanforderungen hängen vom Streamingtyp ab:
- gRPC: Sie müssen das Protokoll auf h2 festlegen.
- WebSockets: Sie müssen http/1.1 verwenden.
- Server-Sent Events (SSE) und inkrementelle Antwortbereitstellung: Sie können entweder http/1.1 oder h2 verwenden. Wir empfehlen h2, um die Leistung zu verbessern.

Objekt AI

Das AI-Objekt konfiguriert Funktionen für künstliche Intelligenz für Ihren Dienst, z. B. Modell-Routing.

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

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

Objekt Models

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 Konfigurieren Sie die Einstellungen für das Modell-Routing.

Objekt Routing

Das Routing-Objekt definiert Modell-Routing-Regeln 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 Modell-Router definieren

Objekt Router

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 mit keiner expliziten Regel übereinstimmt.
rules [Rule] Nein Leer Liste der expliziten Modell-Routingregeln.

Objekt DefaultModel

Das Objekt DefaultModel 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 in x-google-api-management.backends deklariertes Backend.
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 Anfragetext weitergeleitet, wenn ein Fallback auftritt.

Objekt Rule

Das Rule-Objekt definiert eine explizite Modell-Routingregel.

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

Feld Typ Erforderlich Standard Beschreibung
model string Ja Leer Der eingehende String, der mit dem Attribut model in der JSON-Nutzlast des Clients abgeglichen wird. Bei OpenAI-kompatiblen Routen wird dieser String als ausgehendes model-Attribut im Anfragetext weitergeleitet und muss ein gültiger <provider>/<model-id>-String sein.
backend string Ja Leer Verweisen Sie auf ein in x-google-api-management.backends deklariertes Backend.
targetModel string Ja Leer Geben Sie die Zielmodell-ID im Format <provider>/<model-id> an. Mit diesem Wert wird die Übersetzung des Anbieters ausgewählt und im Feld model der Antwort zurückgegeben.

Objekt MCP

Das MCP-Objekt konfiguriert MCP-Funktionen (Model Context Protocol) für Ihren Dienst. Sie können mcp auf einen booleschen Wert oder ein Objekt festlegen. Legen Sie true fest, um MCP global für alle infrage kommenden Vorgänge mit Standardeinstellungen zu aktivieren.

In der folgenden Tabelle werden die Felder für das MCP-Objekt beschrieben:

Feld Typ Erforderlich Standard Beschreibung
tools-list ToolsList Nein Leer Konfigurieren Sie die Einstellungen für die MCP-Methode tools/list.

Objekt ToolsList

Das ToolsList-Objekt konfiguriert Einstellungen für die MCP-Methode tools/list.

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

Feld Typ Erforderlich Standard Beschreibung
security map Nein Leer Aktiviert die Authentifizierung für tools/list. Als Best Practice für die Sicherheit wird dringend empfohlen, diese Option zu konfigurieren. Es muss genau ein JWT- oder API-Schlüsselsicherheitsschema angegeben werden, das unter components.securitySchemes definiert ist.

x-google-auth

Optional.

Die Erweiterung x-google-auth definiert Authentifizierungseinstellungen in einem Sicherheitsschemaobjekt.

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

Feld Typ Erforderlich Standard Beschreibung
issuer string Nein Leer Geben Sie den Aussteller eines Berechtigungsnachweises an. Werte können ein Hostname oder eine E-Mail-Adresse sein.
jwksUri string Nein Leer

Geben Sie den URI des öffentlichen Schlüsselsatzes des Anbieters an, um die Signatur des JSON Web Tokens zu validieren. API Gateway unterstützt zwei asymmetrische öffentliche Schlüsselformate, die durch diese OpenAPI-Erweiterung definiert werden:

  1. JWK-Satz-Format Beispiel: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. X509. Beispiel: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Wenn Sie ein symmetrisches Schlüsselformat verwenden, legen Sie für jwksUri den URI einer Datei fest, die den base64url-codierten Schlüsselstring enthält.
audiences [string] Nein Leer Listen Sie Zielgruppen auf, mit denen das JWT-Feld aud während der JWT-Authentifizierung übereinstimmen muss.
jwtLocations [JwtLocations] Nein Leer Passen Sie die Speicherorte für das JWT-Token an. Standardmäßig wird ein JWT im Header Authorization (mit dem Präfix „Bearer “), im Header X-Goog-Iap-Jwt-Assertion oder im Suchparameter access_token übergeben.

Objekt JwtLocations

Das Objekt JwtLocations stellt benutzerdefinierte Speicherorte für das JWT-Token bereit.

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

Feld Typ Erforderlich Standard Beschreibung
header | query string Ja – Geben Sie den Namen für den Header an, der das JWT enthält, oder den Namen für den Suchparameter, der das JWT enthält.
valuePrefix string Nein Leer Nur für Kopfzeile. Wenn dieser Wert festgelegt ist, muss er mit dem Präfix des Headerwerts übereinstimmen, der das JWT enthält.

x-google-quota

Optional.

Die Erweiterung x-google-quota wird für einzelne Vorgänge verwendet, um anzugeben, welche in x-google-api-management.metrics definierten Messwerte von Anfragen an diesen Vorgang betroffen sind.

x-google-quota ist ein Objekt mit Schlüssel/Wert-Paaren, wobei jeder Schlüssel ein Messwertname und der Wert die ganzzahligen Kosten für jede Anfrage an den Vorgang ist. Beispiel:

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

x-google-backend

Erforderlich.

Die Erweiterung x-google-backend verweist auf ein in x-google-api-management.backends definiertes Backend. Wenn er verwendet wird, muss sein Wert ein String sein, der mit dem Namen eines in x-google-api-management.backends definierten Back-Ends übereinstimmt. Sie müssen diese Erweiterung für API Gateway festlegen. Sie können diese Erweiterung auf der obersten Ebene Ihres OpenAPI-Dokuments oder für einen einzelnen Vorgang definieren, um das Backend auf oberster Ebene zu überschreiben.

Beispiel:

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

x-google-model-router

Optional.

Die Erweiterung x-google-model-router verweist auf einen Modellrouter, der in x-google-api-management.ai.models.routing.routers definiert ist. Wenn er verwendet wird, muss sein Wert ein String sein, der mit dem Namen eines in x-google-api-management.ai.models.routing.routers definierten Routers übereinstimmt.

Diese Erweiterung wird nur in OpenAPI 3.x-Spezifikationen unterstützt. Sie kann nicht mit OpenAPI 2.0-Spezifikationen (Swagger) verwendet werden. Sie können diese Erweiterung nur auf der Ebene einzelner Vorgänge für Vorgänge mit der HTTP-Methode POST definieren. Sie können nicht sowohl x-google-model-router als auch x-google-backend für denselben Vorgang angeben. Außerdem können Sie Vorgänge mit und ohne Modell-Routing nicht über verschiedene Pfade innerhalb derselben API-Spezifikation kombinieren. Außerdem können Sie das Modell-Routing nicht in Verbindung mit dem Model Context Protocol (MCP) verwenden. Wenn Sie x-google-api-management.mcp aktivieren, ist diese Erweiterung nicht verfügbar.

Beispiel:

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

x-google-mcp-tool

Optional.

Die Erweiterung x-google-mcp-tool wird für einzelne Vorgänge verwendet, um sie als MCP-Tools verfügbar zu machen und optional den generierten Toolnamen und die Beschreibung zu überschreiben.

Diese Erweiterung wird nur in OpenAPI 3.x-Spezifikationen unterstützt. Sie kann nicht mit OpenAPI 2.0-Spezifikationen (Swagger) verwendet werden. Sie können diese Erweiterung nur auf der Ebene einzelner Vorgänge definieren.

Akzeptiert entweder einen booleschen Wert oder ein Objekt.

  • Boolesche Form: Legen Sie true fest, um diesen Vorgang zu aktivieren. Legen Sie false fest, um die Funktion zu deaktivieren und eine globale Aktivierung zu überschreiben.
  • Objektformular: Aktivieren Sie die generierten Tooleinstellungen und überschreiben Sie sie.

In der folgenden Tabelle werden die Felder für x-google-mcp-tool beschrieben, wenn es als Objekt verwendet wird:

Feld Typ Erforderlich Standard Beschreibung
name string Nein operationId des Vorgangs Der Name des MCP-Tools. Muss mit [A-Za-z0-9_.-]{1,128} übereinstimmen und in der gesamten Spezifikation eindeutig sein.
description string Nein Die Beschreibung des Vorgangs, wobei auf die Zusammenfassung zurückgegriffen wird Die Beschreibung des MCP-Tools. Dies ist das wichtigste Signal, das ein LLM für die Toolauswahl verwendet.

Beispiel:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

x-google-endpoint

Optional.

Die Erweiterung x-google-endpoint wird verwendet, um die Attribute eines Servers zu konfigurieren, der im Array servers eines OpenAPI 3.x-Dokuments definiert ist. Nur ein Servereintrag in Ihrem OpenAPI-Dokument kann die Erweiterung x-google-endpoint verwenden.

Die Erweiterung definiert auch andere Backend-Funktionen, darunter:

  • CORS: Sie können Cross-Origin Resource Sharing (CORS) aktivieren, indem Sie das Attribut allowCors auf true setzen.

  • Basispfad: Der auf dem Server mit x-google-endpoint festgelegte Basispfad wird für Ihre API verwendet. In der folgenden Konfiguration wird beispielsweise v1 als Basispfad festgelegt:

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

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

Feld Typ Erforderlich Standard Beschreibung
allowCors bool Nein false CORS-Anfragen zulassen.

x-google-parameter

Optional.

Die Erweiterung x-google-parameter wird für ein parameter-Element definiert. Dies kann verwendet werden, wenn der Pfad Pfadvorlagen verwendet, um anzugeben, dass das Verhalten für den Abgleich mit doppelten Platzhaltern verwendet werden soll.

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

Feld Typ Erforderlich Beschreibung
pattern string Ja Hier muss ** festgelegt sein.

Einschränkungen von OpenAPI-Erweiterungen

Diese OpenAPI-Erweiterungen unterliegen bestimmten Einschränkungen. Weitere Informationen finden Sie unter Einschränkungen von OpenAPI 3.x-Funktionen.

Nächste Schritte