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 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:

Feld	Typ	Erforderlich	Standard	Beschreibung
`model`	`string`	Ja	Leer	Der eingehende String, der mit dem Attribut `model` in der JSON-Nutzlast des Clients abgeglichen wurde. 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.

`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. Als Werte sind Hostnamen oder E-Mail-Adressen zulässig.
`jwksUri`	`string`	Nein	Leer	Geben Sie den URI des öffentlichen Schlüsselsatzes des Anbieters an, mit dem die Signatur des JSON Web Token geprüft wird. 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 für `jwksUri` den URI einer Datei mit dem base64url-codierten Schlüsselstring fest.
`audiences`	`[string]`	Nein	Leer	Hier können Sie Zielgruppen auflisten, 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.

`JwtLocations`-Objekt

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 des Headers, der das JWT enthält, oder den Namen des Abfrageparameters, der das JWT enthält, an.
`valuePrefix`	`string`	Nein	Leer	Nur für Kopfzeile. Wenn festgelegt, muss sein Wert mit dem Präfix des Header-Werts ü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 Ganzzahlkosten 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 Back-End, das in x-google-api-management.backends definiert ist. Wenn sie verwendet wird, muss ihr Wert ein String sein, der mit dem Namen eines in x-google-api-management.backends definierten Backends ü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 Back-End 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 Vorgänge mit Modellrouting und Vorgänge ohne Modellrouting nicht über verschiedene Pfade in derselben API-Spezifikation hinweg mischen.

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-endpoint`

Optional.

Mit der Erweiterung x-google-endpoint werden die Eigenschaften eines Servers konfiguriert, 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 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 ist für ein parameter-Element definiert. Dies kann verwendet werden, wenn im Pfad Pfadvorlagen verwendet werden, 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	Dieser muss auf `**` festgelegt sein.

Einschränkungen von OpenAPI-Erweiterungen

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

OpenAPI 3.x-Erweiterungen in API Gateway

x-google-api-management

Metric-Objekt

Quota-Objekt

Quota Limit-Objekt

Backends-Objekt

AI-Objekt

Models-Objekt

Routing-Objekt

Router-Objekt

DefaultModel-Objekt

Rule-Objekt

x-google-auth

JwtLocations-Objekt

x-google-quota

x-google-backend

x-google-model-router

x-google-endpoint

x-google-parameter

Einschränkungen von OpenAPI-Erweiterungen

Nächste Schritte

`x-google-api-management`

`Metric`-Objekt

`Quota`-Objekt

`Quota Limit`-Objekt

`Backends`-Objekt

`AI`-Objekt

`Models`-Objekt

`Routing`-Objekt

`Router`-Objekt

`DefaultModel`-Objekt

`Rule`-Objekt

`x-google-auth`

`JwtLocations`-Objekt

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-endpoint`

`x-google-parameter`