OpenAPI 3.x-Erweiterungen

Cloud Endpoints 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 ihn in Endpoints-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 Nein Leer Backend-Dienste konfigurieren
apiName string Nein Leer Verknüpfen Sie einen Namen mit den im OpenAPI-Dokument definierten Vorgängen.
allowCors bool Nein False Alle CORS-Anfragen (OPTIONS) an das Backend weiterleiten.

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 Endpoints 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, ist der Standardwert für pathTranslation APPEND_PATH_TO_ADDRESS. Wenn x-google-backend für einen Vorgang festgelegt 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.
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 Endpoints 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

Erforderlich.

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
target string Nein Geben Sie die IP-Adresse an, zu der der Host aufgelöst wird.
allowCors bool Nein false CORS-Anfragen zulassen

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
  • Weitere Informationen zu bestimmten Endpunkten oder ESPv2-Konfigurationen finden Sie in der Endpoints-Dokumentation.