Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

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, aber JSON wird ebenfalls unterstützt.

`x-google-api-management`

Erforderlich.

Mit der Erweiterung x-google-api-management werden API-Verwaltungseinstellungen der obersten Ebene für Ihren Dienst definiert. 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	KI-Funktionen konfigurieren, einschließlich Modell-Routing.
`mcp`	`MCP` oder `bool`	Nein	Leer	Aktivieren oder konfigurieren Sie MCP-Funktionen (Model Context Protocol).

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 Quota-Objekt 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 Maximalwert fest, den die Messwert erreichen kann, bevor Clientanfragen abgelehnt werden.

Objekt `Backends`

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 dem Adressfeld entspricht. 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. Bei 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 Sie, dass der Data-Plane-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 Strategie für die Pfadübersetzung 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 Standardwert für `pathTranslation` `APPEND_PATH_TO_ADDRESS`. Wenn `x-google-backend` auf 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 auf eine vollständige Antwort auf eine Anfrage gewartet werden soll. Antworten, die diese Frist überschreiten, führen 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 Lücke zwischen Nachrichten. Informationen zu den Zeitlimits für die einzelnen Anfragetypen finden Sie unter Stream-Deadline festlegen. Das Zeitlimit kann auf bis zu 3.600 Sekunden konfiguriert werden. Bei einem Nicht-Streaming-Gateway wird ein niedrigerer Maximalwert von 600 Sekunden erzwungen. Eine höhere Frist wird beim Erstellen oder Aktualisieren des Gateways abgelehnt und nicht beim Erstellen der API-Konfiguration.
`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`. Die Protokollanforderungen hängen vom Streamingtyp ab: - gRPC: Das Protokoll muss auf `h2` festgelegt werden. - WebSockets: Sie müssen `http/1.1` verwenden. - Server-Sent Events (SSE) und inkrementelle Antwortübermittlung: Sie können entweder `http/1.1` oder `h2` verwenden. Wir empfehlen `h2`, um die Leistung zu verbessern.

Objekt `AI`

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

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	Einstellungen für das Modellrouting konfigurieren

Objekt `Routing`

Das Routing-Objekt definiert Modellroutingregeln 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

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 keiner expliziten Regel entspricht.
`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 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 Anfragetext weitergeleitet, wenn ein Fallback auftritt.

Objekt `Rule`

Das Rule-Objekt definiert eine explizite Modellweiterleitungsregel.

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

Feld	Typ	Erforderlich	Standard	Beschreibung
`model`	`string`	Ja	Leer	Der eingehende String wird mit dem Attribut `model` in der JSON-Nutzlast des Clients abgeglichen. 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 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. Mit diesem Wert wird die Übersetzung durch den Bereitsteller ausgewählt. Er wird im Antwortfeld `model` zurückgegeben.

Objekt `MCP`

Mit dem MCP-Objekt werden MCP-Funktionen (Model Context Protocol) für Ihren Dienst konfiguriert. 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`

Mit dem ToolsList-Objekt werden Einstellungen für die MCP-Methode tools/list konfiguriert.

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 in Sachen Sicherheit wird dringend empfohlen, diese Option zu konfigurieren. Muss genau ein JWT-Sicherheitsschema angeben, das unter `components.securitySchemes` definiert ist. Die API-Schlüssel-Authentifizierung wird in der öffentlichen Vorschau nicht unterstützt.

`x-google-auth`

Optional.

Die Erweiterung x-google-auth definiert Authentifizierungseinstellungen in einem Security Scheme Object.

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 von Anmeldedaten an. Werte können ein Hostname oder eine E-Mail-Adresse sein.
`jwksUri`	`string`	Nein	Leer	Geben Sie den URI des öffentlichen Schlüsselsets 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: JWK-Satz-Format Beispiel: `jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"` 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 `jwksUri` auf den URI einer Datei fest, die den base64url-codierten Schlüsselstring enthält.
`audiences`	`[string]`	Nein	Leer	Liste der Zielgruppen, mit denen das Feld `aud` des JWT bei der JWT-Authentifizierung übereinstimmen muss.
`jwtLocations`	`[JwtLocations]`	Nein	Leer	Standorte für das JWT-Token anpassen Standardmäßig wird ein JWT im Header `Authorization` (mit dem Präfix „Bearer “), im Header `X-Goog-Iap-Jwt-Assertion` oder im Abfrageparameter `access_token` übergeben.

Objekt `JwtLocations`

Das JwtLocations-Objekt enthält benutzerdefinierte Speicherorte für das JWT-Token.

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 mit dem JWT oder den Namen für den Abfrageparameter mit dem JWT an.
`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 x-google-backend-Erweiterung verweist auf ein Backend, das in x-google-api-management.backends definiert ist. Wenn dieser Parameter 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 der obersten 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 x-google-model-router-Erweiterung verweist auf einen Modellrouter, der in x-google-api-management.ai.models.routing.routers definiert ist. Wenn sie verwendet wird, muss ihr 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 des einzelnen Vorgangs für Vorgänge definieren, die die HTTP-Methode POST verwenden. Sie können nicht sowohl x-google-model-router als auch x-google-backend für denselben Vorgang angeben. Außerdem können Sie in derselben API-Spezifikation nicht Vorgänge mit Modellrouting und Vorgänge ohne Modellrouting für verschiedene Pfade kombinieren. Außerdem können Sie das Modellrouting 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.

Akzeptiert entweder einen booleschen Wert oder ein Objekt.

Boolesche Form: Auf true setzen, um diesen Vorgang zu aktivieren. Legen Sie false fest, um die Funktion zu deaktivieren und eine globale Aktivierung zu überschreiben.
Objektform: Sie können die generierten Tool-Einstellungen aktivieren und überschreiben.

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 Spezifikation eindeutig sein.
`description`	`string`	Nein	Die Beschreibung des Vorgangs, falls vorhanden, ansonsten die Zusammenfassung	Die Beschreibung des MCP-Tools. Dies ist das primäre Signal, das ein LLM für die Auswahl von Tools 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.

Mit der Erweiterung x-google-endpoint werden die Eigenschaften eines Servers konfiguriert, der im servers-Array eines OpenAPI 3.x-Dokuments definiert ist. Nur ein Servereintrag in Ihrem OpenAPI-Dokument kann die x-google-endpoint-Erweiterung verwenden.

Die Erweiterung definiert auch andere Backend-Funktionen, darunter:

CORS: Sie können Cross-Origin Resource Sharing (CORS) aktivieren, indem Sie die Eigenschaft 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 im Pfad Pfadvorlagen verwendet werden, um anzugeben, dass das Verhalten für den doppelten Platzhalterabgleich verwendet werden soll.

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

Feld	Typ	Erforderlich	Beschreibung
`pattern`	`string`	Ja	Dieses Feld muss auf `**` festgelegt sein.

Einschränkungen bei OpenAPI-Erweiterungen

Für diese OpenAPI-Erweiterungen gelten bestimmte Einschränkungen. Weitere Informationen finden Sie unter Funktionseinschränkungen für OpenAPI 3.x.

OpenAPI 3.x-Erweiterungen in API Gateway

x-google-api-management

Objekt Metric

Objekt Quota

Objekt QuotaLimit

Objekt Backends

Objekt AI

Objekt Models

Objekt Routing

Objekt Router

Objekt DefaultModel

Objekt Rule

Objekt MCP

Objekt ToolsList

x-google-auth

Objekt JwtLocations

x-google-quota

x-google-backend

x-google-model-router

x-google-mcp-tool

x-google-endpoint

x-google-parameter

Einschränkungen bei OpenAPI-Erweiterungen

Nächste Schritte

`x-google-api-management`

Objekt `Metric`

Objekt `Quota`

Objekt `QuotaLimit`

Objekt `Backends`

Objekt `AI`

Objekt `Models`

Objekt `Routing`

Objekt `Router`

Objekt `DefaultModel`

Objekt `Rule`

Objekt `MCP`

Objekt `ToolsList`

`x-google-auth`

Objekt `JwtLocations`

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-mcp-tool`

`x-google-endpoint`

`x-google-parameter`