OpenAPI-Erweiterungen

Cloud Endpoints unterstützt eine Reihe von Google-spezifischen Erweiterungen der OpenAPI-Spezifikation. Diese konfigurieren das Verhalten des Extensible Service Proxys (ESP), des Extensible Service Proxys V2 (ESPv2) und von Service Control. Auf dieser Seite werden Google- bestimmte Erweiterungen des OpenAPI-Spezifikation

Obwohl die folgenden Beispiele im YAML-Format vorliegen, wird auch JSON unterstützt.

Namenskonvention

Die Namen von Google OpenAPI-Erweiterungen beginnen mit dem Präfix x-google-.

x-google-allow

x-google-allow: [configured | all]

Mit dieser Erweiterung wird auf der obersten Ebene einer OpenAPI-Spezifikation angegeben, welche URL-Pfade über den ESP zulässig sein sollen.

Die möglichen Werte sind configured und all.

Der Standardwert ist configured. Dabei werden nur die in der OpenAPI-Spezifikation aufgeführten API-Methoden über den ESP bedient.

Bei Verwendung von all werden nicht konfigurierte Aufrufe – mit oder ohne API-Schlüssel oder Nutzerauthentifizierung – über den ESP an die API weitergeleitet.

Bei der Verarbeitung von Aufrufen an die API durch den ESP wird die Groß- und Kleinschreibung berücksichtigt. Beispielsweise betrachtet der ESP /widgets und /Widgets als verschiedene API-Methoden.

Wenn all verwendet wird, müssen Sie in zwei Bereichen besonders vorsichtig vorgehen:

  • API-Schlüssel oder Authentifizierungsregeln
  • Back-End-Pfadweiterleitung an Ihren Dienst

Als Best Practice empfehlen wir, dass Sie Ihre API für eine Pfadweiterleitung konfigurieren, bei der die Groß- und Kleinschreibung berücksichtigt wird. Bei einer Weiterleitung mit Berücksichtigung von Groß- und Kleinschreibung gibt die API den HTTP-Statuscode 404 zurück, wenn die in der URL angeforderte Methode nicht mit dem in Ihrer OpenAPI-Spezifikation aufgeführten API-Methodennamen übereinstimmt. Beachten Sie, dass Webanwendungs-Frameworks wie Node.js Express eine Einstellung zum Aktivieren oder Deaktivieren von Weiterleitungen enthalten, bei denen die Groß- und Kleinschreibung berücksichtigt wird. Deren Standardverhalten hängt vom verwendeten Framework ab. Wir empfehlen deshalb, die Einstellungen in Ihrem Framework zu überprüfen, um sicherzustellen, dass eine Weiterleitung aktiviert ist, bei der die Groß- und Kleinschreibung berücksichtigt wird. Diese Empfehlung ergibt sich logisch aus der OpenAPI-Spezifikation Version 2.0, die besagt, dass bei allen Feldnamen in der Spezifikation die Groß- und Kleinschreibung berücksichtigt wird.

Beispiel

Wir gehen von folgenden Voraussetzungen aus:

  • x-google-allow ist auf all gesetzt.
  • Die API-Methode widgets ist in der OpenAPI-Spezifikation enthalten, Widgets jedoch nicht.
  • Sie haben Ihre OpenAPI-Spezifikation so konfiguriert, dass ein API-Schlüssel erforderlich ist.

Da widgets in der OpenAPI-Spezifikation aufgeführt ist, blockiert der ESP die folgende Anfrage, da sie keinen API-Schlüssel besitzt:

https://my-project-id.appspot.com/widgets

Da Widgets in der OpenAPI-Spezifikation nicht aufgeführt ist, leitet der ESP die folgende Anfrage ohne API-Schlüssel an Ihren Dienst weiter:

https://my-project-id.appspot.com/Widgets/

Wenn Ihre API eine Weiterleitung verwendet, bei der die Groß- und Kleinschreibung berücksichtigt wird (und Sie keine Aufrufe von Code an "Widgets" weitergeleitet haben), gibt Ihr API-Back-End 404 aus. Wenn Sie jedoch eine Weiterleitung ohne Berücksichtigung der Groß- und Kleinschreibung verwenden, leitet Ihr API-Back-End diesen Aufruf an "widgets" weiter.

Unterschiedliche Sprachen und Frameworks haben verschiedene Methoden zur Berücksichtigung der Groß- und Kleinschreibung und zur Weiterleitung. Details finden Sie in der Dokumentation zu Ihrem Framework.

x-google-backend

Die x-google-backend-Erweiterung gibt an, wie Anfragen an lokale oder remote Back-Ends weitergeleitet werden. Die Erweiterung kann auf der obersten und/oder der Vorgangsebene einer OpenAPI-Spezifikation angegeben werden.

Standardmäßig ist der ESP so konfiguriert, dass der gesamte Traffic an ein einzelnes lokales Backend geleitet wird. Die lokale Backend-Adresse wird durch das --backend-Flag angegeben (standardmäßig http://127.0.0.1:8081). Mit der x-google-backend-Erweiterung können Sie dieses Standardverhalten überschreiben und ein oder mehrere lokale oder remote Backends angeben, die Anfragen empfangen können.

Die Erweiterung x-google-backend kann auch andere Einstellungen für lokale und Remote-Back-Ends konfigurieren, z. B. Authentifizierung und Zeitlimits. Alle diese Konfigurationen können pro Vorgang angewendet werden.

Die x-google-backend-Erweiterung enthält folgende Felder:

address

address: URL

Optional. Die URL des Ziel-Back-Ends. Das Adressschema muss http oder https sein.

Beim Routing an remote Back-Ends (serverlos) sollte die Adresse festgelegt werden und der Schemateil sollte https sein.

Wenn ein Vorgang x-google-backend verwendet, aber nicht address angibt, leitet ESPv2 Anfragen an das lokale Backend weiter, das durch das --backend-Flag angegeben ist.

jwt_audience | disable_auth

Nur eine dieser beiden Attribute sollte festgelegt werden.

Wenn ein Vorgang x-google-backend verwendet, aber weder jwt_audience noch disable_auth angibt, verwendet ESPv2 automatisch jwt_audience, um dem address zu entsprechen. Ist address nicht festgelegt, setzt ESPv2 disable_auth automatisch auf true.

jwt_audience

jwt_audience: string

Optional. Die Zielgruppe für JWT, die angegeben wird, wenn der ESPv2 ein Instanz-ID-Token erhält, das dann beim Erstellen der Anfrage im Ziel-Backend verwendet wird.

Beim Konfigurieren von Endpoints für serverloses Computing sollte das Remote-Backend gesichert werden, um nur Traffic von ESPv2 zuzulassen. ESPv2 hängt beim Weiterleiten von Anfragen ein Instanz-ID-Token an den Header Authorization an. Das Instanz-ID-Token stellt das Laufzeitdienstkonto dar, das zur Bereitstellung von ESPv2 verwendet wurde. Das Remote-Backend kann dann prüfen, ob die Anfrage von ESPv2 basierend auf diesem angehängten Token stammt.

Ein in Cloud Run bereitgestelltes Backend kann IAM beispielsweise für Folgendes verwenden:

  1. Um nicht authentifizierte Aufrufe einzuschränken widerrufen Sie roles/run.invoker vom speziellen allUsers-Hauptkonto.
  2. Erlauben Sie nur ESPv2 das Backend aufrufen, indem Sie dem ESPv2-Laufzeitdienstkonto die Rolle roles/run.invoker zuweisen.

Standardmäßig erstellt ESPv2 das Instanz-ID-Token mit einer JWT-Zielgruppe, die mit dem Feld address ü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 Feld address 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.

Wenn dieses Feature aktiviert ist, werden Header von ESPv2 in Anfragen mutiert. Wenn für eine Anfrage der Header Authorization bereits festgelegt ist, führt ESPv2 Folgendes aus:

  1. den ursprünglichen Wert in einen neuen Header X-Forwarded-Authorization kopieren.
  2. den Header Authorization mit dem Instanz-ID-Token überschreiben.

Wenn ein API-Client den Authorization-Header festlegt, sollte ein Backend, das hinter ESPv2 ausgeführt wird, den X-Forwarded-Authorization-Header verwenden, um das gesamte JWT abzurufen. Das Backend muss das JWT in diesem Header prüfen, da ESPv2 keine Verifizierung durchführt, wenn die Authentifizierungsmethoden nicht konfiguriert sind.

disable_auth

disable_auth: bool

Optional. Dieses Attribut bestimmt, ob ESPv2 verhindern soll, dass ein Instanz-ID-Token abgerufen und es an die Anfrage angehängt.

Wenn Sie das Ziel-Backend konfigurieren, kann es eine gute Idee sein, IAP oder IAM nicht zum Authentifizieren von Anfragen von ESPv2 verwenden, wenn eine der folgenden Bedingungen zutrifft:

  1. Das Backend sollte nicht authentifizierte Aufrufe zulassen.
  2. Das Backend benötigt den ursprünglichen Authorization-Header des API-Clients und kann X-Forwarded-Authorization nicht verwenden (wie im jwt_audience-Abschnitt beschrieben).

Legen Sie in diesem Fall true für dieses Feld fest.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Optional. Legt die Strategie für die Pfadübersetzung fest, die von ESPv2 verwendet wird, wenn durch das Weiterleiten von Anfragen an das Ziel-Back-End.

Weitere Informationen zur Pfadübersetzung finden Sie im Abschnitt Weitere Informationen zur Pfadübersetzung.

Wenn x-google-backend auf der obersten Ebene der OpenAPI-Spezifikation verwendet wird, ist path_translation der Standardwert für APPEND_PATH_TO_ADDRESS. Wenn x-google-backend auf der Vorgangsebene der OpenAPI-Spezifikation verwendet wird, ist CONSTANT_ADDRESS der Standardwert für path_translation. Wenn das Feld address fehlt, bleibt path_translation weiter nicht angegeben und wird nicht zurückgegeben.

deadline

deadline: double

Optional. Die Anzahl der Sekunden, die bis zur vollständigen Antwort auf eine Anfrage gewartet werden muss. Bei Antworten, die länger als die konfigurierte Frist dauern, tritt eine Zeitüberschreitung auf. Die Standardfrist beträgt 15.0 Sekunden.

Nicht positive Werte werden nicht berücksichtigt. ESPv2 verwendet in diesen Fällen automatisch den Standardwert.

Die Frist kann nicht deaktiviert werden, aber sie kann auf eine hohe Zahl eingestellt werden, z. B. 3600.0 für eine Stunde.

protocol

protocol: [ http/1.1 | h2 ]

Optional. Das Protokoll, das zum Senden einer Anfrage an das Back-End verwendet wird. Die unterstützten Werte sind http/1.1 und h2.

Der Standardwert ist http/1.1 für HTTP- und HTTPS-Back-Ends.

Setzen Sie dieses Feld für sichere HTTP-Back-Ends (https://), die HTTP/2 unterstützen, auf h2, um die Leistung zu verbessern. Dies ist die empfohlene Option für Google Cloud Serverless Back-Ends.

Back-End-Unterstützung im ESP aktivieren

ESPv2 erkennt automatisch, ob x-google-backend konfiguriert ist.

ESP erfordert eine manuelle Konfigurationsänderung, um diese Funktion zu aktivieren. Aktivieren Sie die Unterstützung x-google-backend im ESP. Geben Sie dazu beim Ausführen des ESP-Containers das Argument --enable_backend_routing an. (Für die Laufzeiten, in denen Sie die ESP-Containeroptionen nicht steuern, ist diese Option bereits für Sie festgelegt.) Im Folgenden finden Sie ein Beispiel für die Aktivierung der Unterstützung x-google-backend bei der Bereitstellung des ESP-Containers in der GKE (dieses Beispiel baut auf dem Beispiel Anleitung zu Endpoints in GKE auf):

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

Weitere Informationen zur Pfadübersetzung

Da der ESP Anfragen verarbeitet, verwendet er den ursprünglichen Anfragepfad und übersetzen, bevor Sie eine Anfrage an das Ziel-Back-End senden. Wie diese Übersetzung erfolgt, hängt davon ab, welche Strategie Sie für die Pfadübersetzung verwenden. Es gibt zwei Strategien für die Pfadübersetzung:

  • APPEND_PATH_TO_ADDRESS: Der Anfragepfad im Ziel-Back-End wird berechnet, indem der ursprüngliche Anfragepfad an die URL address der Erweiterung x-google-backend angehängt wird.
  • CONSTANT_ADDRESS: Der Ziel-Anfragepfad bleibt gemäß der URL address der Erweiterung x-google-backend unverändert. Wenn der entsprechende OpenAPI-Pfad Parameter enthält, werden der Parametername und dessen Wert zu Abfrageparametern.

Beispiele:

  • APPEND_PATH_TO_ADDRESS
    • address: https://my-project-id.appspot.com/BASE_PATH
    • Mit OpenAPI-Pfadparametern
      • OpenAPI-Pfad: /hello/{name}
      • Anfragepfad: /hello/world
      • URL der Zielanfrage: https://my-project-id.appspot.com/BASE_PATH/hello/world
    • Ohne OpenAPI-Pfadparameter
      • OpenAPI-Pfad: /hello
      • Anfragepfad: /hello
      • URL der Zielanfrage: https://my-project-id.appspot.com/BASE_PATH/hello
  • CONSTANT_ADDRESS
    • address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
    • Mit OpenAPI-Pfadparametern
      • OpenAPI-Pfad: /hello/{name}
      • Anfragepfad: /hello/world
      • URL der Zielanfrage: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
    • Ohne OpenAPI-Pfadparameter
      • OpenAPI-Pfad: /hello
      • Anfragepfad: /hello
      • URL der Zielanfrage: https://us-central1-my-project-id.cloudfunctions.net/helloGET

x-google-endpoints

In diesem Abschnitt wird die Verwendung der Erweiterung x-google-endpoints beschrieben.

DNS in der Domain cloud.goog konfigurieren

Wenn Sie die Anwendung in Compute Engine oder Google Kubernetes Engine bereitgestellt haben, können Sie einen DNS-Eintrag für den Endpoints-Dienst in der Domain cloud.goog erstellen. Dazu fügen Sie Folgendes in das OpenAPI-Dokument ein:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

Geben Sie die Erweiterung x-google-endpoints auf oberster Ebene des OpenAPI-Dokuments an, also weder eingerückt noch verschachtelt. Verwenden Sie für den Domainnamen das folgende Format: .endpoints.PROJECT_ID.cloud.goog.

Beispiel:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  target: "192.0.2.1"

Die Domain .cloud.goog wird von Google verwaltet und ist für Kunden von Google Cloud freigegeben. Da Google Cloud-Projekt-IDs global eindeutig sind, ist ein Domainname im Format .endpoints.PROJECT_ID.cloud.goog ein eindeutiger Domainname für Ihre API.

Der Einfachheit halber sollten Sie für die Felder host und x-google-endpoints.name denselben Wert festlegen. Wenn Sie Ihr OpenAPI-Dokument bereitstellen, wird Folgendes von Service Management erstellt:

  • Ein verwalteter Dienst mit dem Namen, den Sie im Feld host angegeben haben.
  • Ein DNS-A-Eintrag mit dem Namen und der IP-Adresse, die Sie in der Erweiterung x-google-endpoints konfiguriert haben.

Für APIs, die in der flexiblen App Engine-Umgebung gehostet werden, können Sie die Domain appspot.com verwenden. Weitere Informationen finden Sie unter Endpoints konfigurieren.

ESP zum Zulassen von CORS-Anfragen konfigurieren

Wenn Ihre API von einer Webanwendung aufgerufen wird, die an einem anderen Ort gehostet wird, muss Ihre API Cross-Origin Resource Sharing (CORS) unterstützen. Weitere Informationen dazu, wie Sie den ESP für die Unterstützung von CORS konfigurieren, finden Sie unter CORS-Unterstützung zum ESP hinzufügen.

Wenn Sie die benutzerdefinierte CORS-Unterstützung in Ihrem Back-End-Code implementieren müssen, legen Sie allowCors: True, damit der ESP alle CORS-Anfragen an Ihren Back-End-Code:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

Geben Sie die Erweiterung x-google-endpoints auf oberster Ebene des OpenAPI-Dokuments an, also weder eingerückt noch verschachtelt.

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

x-google-issuer

x-google-issuer: URI | EMAIL_ADDRESS

Mit dieser Erweiterung wird im OpenAPI-Abschnitt securityDefinitions der Aussteller von Anmeldedaten angegeben. Als Werte sind Hostnamen oder E-Mail-Adressen zulässig.

x-google-jwks_uri

x-google-jwks_uri: URI

Der URI des öffentlichen Schlüsselsatzes des Anbieters, mit dem die Signatur des JSON Web Token geprüft wird.

Der ESP unterstützt zwei asymmetrische öffentliche Schlüsselformate, die durch die OpenAPI-Erweiterung x-google-jwks_uri definiert werden:

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

Wenn Sie ein symmetrisches Schlüsselformat verwenden, setzen Sie x-google-jwks_uri auf den URI einer Datei, die den base64url-codierten Schlüsselstring enthält.

Wenn Sie x-google-jwks_uri weglassen, folgt der ESP dem OpenID Connect Discovery-Protokoll, um den JWKS-URI für den angegebenen OpenID-Anbieter automatisch zu ermitteln. Der ESP sendet eine Anfrage an x-google-issuer/.well-known/openid-configuration, parst die JSON-Antwort und liest die JWKS-URI aus dem Feld jwks_uri der obersten Ebene.

Wenn Sie x-google-jwks_uri weglassen, führt dies zu höheren Kaltstartzeiten, da der ESP beim Start einen zusätzlichen Remote-Aufruf vornehmen muss. Daher wird empfohlen, dieses Feld nur auszulassen, wenn sich der JWKS-URI häufig ändert. Die meisten zertifizierten OpenID-Anbieter wie Google, Auth0 und Okta verfügen über stabile JWKS-URIs.

x-google-jwt-locations

Standardmäßig wird ein JWT entweder im Header Authorization (mit dem Präfix "Bearer "), im Header X-Goog-Iap-Jwt-Assertion oder im Abfrageparameter access_token übergeben. Informationen zur Weitergabe von JWTs finden Sie unter Authentifizierter Aufruf an eine Endpoints-API.

Alternativ können Sie die Erweiterung x-google-jwt-locations im Abschnitt OpenAPI securityDefinitions verwenden, um die angepassten Standorte anzugeben, von denen das JWT-Token extrahiert werden soll.

Die Erweiterung x-google-jwt-locations akzeptiert eine Liste von JWT-Standorten. Jeder JWT-Speicherort enthält die folgenden Felder:

Element Beschreibung
header/query Erforderlich. Der Name des Headers, der das JWT enthält, oder der Name des Abfrageparameters, der das JWT enthält.
value_prefix Optional. Nur für Kopfzeile. Wenn value_prefix festgelegt ist, muss sein Wert mit dem Präfix des Header-Werts übereinstimmen, der das JWT enthält.

Beispiel:

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

Wenn Sie nur einen Teil der Standard-JWT-Standorte unterstützen möchten, müssen Sie sie explizit in der Erweiterung x-google-jwt-locations auflisten. Wenn Sie beispielsweise nur den Header Authorization mit dem Präfix "Bearer " unterstützen möchten:

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

x-google-audiences

x-google-audiences: STRING

Mit dieser Erweiterung im OpenAPI-Abschnitt securityDefinitions wird eine Liste der Zielgruppen angegeben, mit denen das JWT-aud-Feld bei der JWT-Authentifizierung übereinstimmen muss. Diese Erweiterung akzeptiert einen einzelnen String mit durch Kommas getrennten Werten. Zwischen den Zielgruppen dürfen sich keine Leerzeichen befinden. Wenn es nicht angegeben ist, sollte das JWT-Feld aud mit dem Feld host im OpenAPI-Dokument übereinstimmen, es sei denn, das Flag --disable_jwt_audience_service_name_check wird verwendet. Wenn das Flag verwendet wird und x-google-audiences ist nicht angegeben, das JWT-Feld aud ist nicht aktiviert.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

x-google-management

Die Erweiterung x-google-management steuert verschiedene Aspekte der API-Verwaltung und enthält die in diesem Abschnitt beschriebenen Felder.

metrics

Sie verwenden metrics in Verbindung mit Kontingenten und x-google-quota, um ein Kontingent für Ihre API zu konfigurieren. Damit steuern Sie, wie oft Anwendungen die Methoden in der API aufrufen können. Beispiel:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

Das Feld metrics enthält eine Liste mit den folgenden Schlüssel/Wert-Paaren:

Element Beschreibung
name Erforderlich. Der Name für diesen Messwert. In der Regel ist dies der Anfragetyp (z. B. "Leseanfragen" oder "Schreibanfragen"), der den Messwert eindeutig identifiziert.
displayName

Optional, aber empfohlen. Der Text, der angezeigt wird, um den Messwert auf den Tab Kontingente auf Endpunkten > Seite Dienste im Menü Google Cloud Console Dieser Text wird auch Nutzern Ihrer API auf den Kontingente-Seiten unter IAM und Verwaltung und APIs und Dienste angezeigt. Der Anzeigename darf nicht länger als 40 Zeichen sein.

Für eine bessere Lesbarkeit wird die Einheit aus dem zugehörigen Kontingentlimit automatisch an den Anzeigenamen in der Google Cloud Console angefügt. Wenn Sie beispielsweise „Leseanfragen“ als Anzeigenamen angeben, wird in der Google Cloud Console „Leseanfragen pro Minute pro Projekt“ angezeigt. Wird keine Angabe gemacht, wird den Nutzern Ihrer API auf der Seite Kontingente unter IAM und Verwaltung und APIs und Dienste "unlabeled quota" (unbenanntes Kontingent) angezeigt.

Zur Wahrung der Konsistenz mit den Anzeigenamen von Google-Diensten, die auf der Seite Kontingente aufgeführt und den Nutzern Ihrer API angezeigt werden, empfehlen wir für den Anzeigenamen Folgendes:

  • Verwenden Sie "Anfragen", wenn Sie nur einen Messwert haben.
  • Wenn Sie mehrere Messwerte haben, sollte jeder den Anfragetyp beschreiben und das Wort "Anfragen" enthalten (z. B. "Leseanfragen" oder "Schreibanfragen").
  • Verwenden Sie "Kontingenteinheiten" anstelle von "Anfragen", wenn die mit dem Messwert verbundenen Kosten größer als 1 sind.
valueType Erforderlich. Muss INT64 lauten
metricKind Erforderlich. Muss DELTA sein

quota

Das Kontingentlimit für einen definierten Messwert wird im Abschnitt quota angegeben. Beispiel:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

Das Feld quota.limits enthält eine Liste mit den folgenden Schlüssel/Wert-Paaren:

Element Beschreibung
name Erforderlich. Name des Limits, das innerhalb des Diensts eindeutig sein muss. Der Name kann Groß- und Kleinbuchstaben, Zahlen und "-" (Bindestrich) enthalten und darf maximal 64 Zeichen lang sein.
metric Erforderlich. Der Name des Messwerts, für den das Limit gilt. Der Name muss mit dem im Namen eines Messwerts angegebenen Text übereinstimmen. Wenn der angegebene Text nicht mit dem Namen eines Messwerts übereinstimmt, wird beim Bereitstellen des OpenAPI-Dokuments ein Fehler ausgegeben.
unit Erforderlich. Die Einheit des Limits. Derzeit wird nur "1/min/{project}" unterstützt. Das bedeutet, dass das Limit pro Projekt erzwungen und die Nutzung minütlich zurückgesetzt wird.
values Erforderlich. Das Limit für den Messwert. Dieses muss als Schlüssel/Wert-Paar im folgenden Format angeben werden: 
STANDARD: YOUR-LIMIT-FOR-THE-METRIC
Sie ersetzen YOUR-LIMIT-FOR-THE-METRIC durch eine Ganzzahl Wert, der die maximal zulässige Anzahl von Anfragen für die angegebene Einheit darstellt (derzeit nur pro Minute, pro Projekt). Beispiel:
values:
  STANDARD: 5000

x-google-quota

Die Erweiterung x-google-quota wird im OpenAPI-Abschnitt paths verwendet, um eine Methode in Ihrer API einem Messwert zuzuordnen. Auf Methoden, für die x-google-quota nicht definiert ist, werden keine Kontingentlimits angewendet. Beispiel:

x-google-quota:
  metricCosts:
    read-requests: 1

Die Erweiterung x-google-quota enthält folgendes Element:

Element Beschreibung
metricCosts Ein benutzerdefiniertes Schlüssel/Wert-Paar: "YOUR-METRIC-NAME": METRIC-COST.
  • "YOUR-METRIC-NAME":: Der Text für "YOUR-METRIC-NAME" muss mit einem definierten Messwertnamen übereinstimmen.
  • METRIC-COST:: Eine Ganzzahl, die die Kosten für jede Anfrage definiert. Erfolgt eine Anfrage, wird der zugeordnete Messwert um die angegebenen Kosten erhöht. Durch die Kosten können Methoden den Messwert mit unterschiedlicher Häufigkeit nutzen. Wenn ein Messwert beispielsweise ein Kontingentlimit von 1.000 und Kosten von 1 hat, kann die aufrufende Anwendung 1.000 Anfragen pro Minute senden, bevor das Limit überschritten wird. Bei Kosten von 2 für den gleichen Messwert kann eine aufrufende Anwendung nur 500 Anfragen pro Minute senden, bevor sie das Limit überschreitet.

Beispiele für Kontingente

Im folgenden Beispiel wird das Hinzufügen eines Messwerts und eines Limits für Lese- und Schreibanfragen gezeigt:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

x-google-api-name

Wenn Ihr Dienst nur eine einzige API enthält, entspricht der API-Name dem Namen des Endpoints-Dienstes. (Endpoints verwendet den Namen, den Sie im Feld host des OpenAPI-Dokuments als Namen Ihres Dienstes angeben.) Enthält der Dienst mehrere APIs, geben Sie die API-Namen an. Fügen Sie dazu dem OpenAPI-Dokument die Erweiterung x-google-api-name hinzu. Mit der Erweiterung x-google-api-name können Sie einzelne APIs explizit mit Namen angeben und für jede API eine unabhängige Versionsverwaltung einrichten.

Sie können z. B. einen Dienst mit dem Namen api.example.com mit zwei APIs (producer und consumer) mit den folgenden OpenAPI-Dokumentfragmenten konfigurieren:

  • Producer API in producer.yaml: 

    swagger: 2.0
host: api.example.com
x-google-api-name: producer
info:
  version: 1.0.3

  • Consumer API in consumer.yaml:

    swagger: 2.0
host: api.example.com
x-google-api-name: consumer
info:
  version: 1.1.0

Sie können die beiden OpenAPI-Dokumente gemeinsam bereitstellen mit:

gcloud endpoints services deploy producer.yaml consumer.yaml