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.

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.

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.

Backend-Objekt

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

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

Feld	Typ	Erforderlich	Standard	Beschreibung
address	string	Nein	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 Datenebenenproxy ein Instanz-ID-Token abruft und 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 bis zur vollständigen Antwort auf eine Anfrage gewartet werden soll. Bei Antworten, die länger als diese Frist dauern, tritt eine Zeitüberschreitung auf.
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.

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/[e-mail]" 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 Standorte 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.

Mit der Erweiterung x-google-quota werden Kontingentlimits definiert. Sie können diese Erweiterung auf der obersten Ebene Ihres OpenAPI-Dokuments oder für einen einzelnen Vorgang definieren.

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

Feld	Typ	Erforderlich	Beschreibung
self	map[string]int64	Ja	Das quota-Objekt (self) verweist auf alle im Objekt definierten Messwerte. Ordnen Sie in diesem Fall einen Messwert (z. B. read-requests) einem Betrag zu, um den Messwert zu erhöhen. Anfragen werden abgelehnt, wenn der Messwert das Kontingentlimit erreicht.

x-google-backend

Erforderlich.

Die x-google-backend-Erweiterung verweist auf ein Back-End, das in x-google-api-management definiert ist. 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.

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

Feld	Typ	Erforderlich	Beschreibung
self	string	Ja	Verweist auf die ID eines in x-google-api-management definierten Backends.

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	Muss auf ** festgelegt sein.

Einschränkungen von OpenAPI-Erweiterungen

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

Nächste Schritte

• OpenAPI-Spezifikation
• Gateway für die Verwendung von OpenAPI 3.0 ändern