Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

OpenAPI-Erweiterungen

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

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 die API eine Weiterleitung verwendet, bei der die Groß- und Kleinschreibung berücksichtigt wird (und Sie keine Aufrufe von Code an "Widgets" weitergeleitet haben), gibt das API-Back-End 404 aus. Wenn Sie jedoch eine Weiterleitung ohne Berücksichtigung der Groß- und Kleinschreibung verwenden, leitet das 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 Erweiterung x-google-backend gibt an, wie Anfragen an lokale oder Remote-Back-Ends weitergeleitet werden. Die Erweiterung kann auf der obersten Ebene und/oder der Vorgangsebene einer OpenAPI-Spezifikation angegeben werden.

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

Mit der Erweiterung x-google-backend können auch andere Einstellungen für lokale und Remote-Back-Ends wie Authentifizierung und Zeitlimits konfiguriert werden. Alle diese Konfigurationen können pro Vorgang angewendet werden.

Die Erweiterung x-google-backend enthält die folgenden Felder:

address

address: URL

Optional. Die URL des Ziel-Back-Ends. Das Schema der Adresse muss entweder http oder https sein.

Beim Routing an Remote-Back-Ends (serverlos) sollte die Adresse festgelegt und der Schemaabschnitt https sein.

Wenn ein Vorgang x-google-backend verwendet, aber address nicht angibt, leitet ESPv2 Anfragen an das lokale Back-End weiter, das vom Flag --backend angegeben wird.

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 für die Übereinstimmung mit address. Wenn address nicht festgelegt ist, setzt ESPv2 automatisch disable_auth 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-Back-End verwendet wird.

Beim Konfigurieren von Endpoints für Serverless sollte das Remote-Back-End sicher sein, um nur Traffic von ESPv2 zuzulassen. ESPv2 fügt beim Proxy-Anfragen ein Instanz-ID-Token an den Header Authorization an. Das Instanz-ID-Token stellt das Laufzeitdienstkonto dar, mit dem ESPv2 bereitgestellt wurde. Das Remote-Back-End kann dann anhand des angehängten Tokens überprüfen, ob die Anfrage von ESPv2 stammt.

Beispielsweise kann ein Remote-Back-End, das in Cloud Run bereitgestellt wird, IAM für Folgendes verwenden:

  1. Schränken Sie nicht authentifizierte Aufrufe ein, indem Sie roles/run.invoker vom speziellen allUsers-Mitglied widerrufen.
  2. Erlauben Sie nur ESPv2 das Back-End 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-Back-End eine JWT-basierte Authentifizierung verwendet und sich die erwartete Zielgruppe von dem 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 diese Funktion aktiviert ist, werden vom ESPv2 Header in Anfragen mutiert. Wenn für eine Anfrage der Header Authorization bereits festgelegt ist, ESPv2:

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

Wenn also ein API-Client den Header Authorization festlegt, sollte ein Back-End, das hinter ESPv2 ausgeführt wird, das gesamte JWT mit dem Header X-Forwarded-Authorization abrufen. Back-Endmuss Verifizieren Sie das JWT in diesem Header, da ESPv2 keine Überprüfung durchführt, wennAuthentifizierungsmethoden 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 ein Ziel-Back-End konfigurieren, sollten Sie IAP oder IAM nicht zum Authentifizieren von Anfragen von ESPv2 verwenden, wenn eine der folgenden Bedingungen zutrifft:

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

Setzen Sie in diesem Fall dieses Feld auf true.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Optional. Legt die Strategie für die vom ESPv2 verwendete Pfadübersetzung fest, wenn Anfragen an das Ziel-Back-End per Proxy weitergeleitet werden.

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 standardmäßig APPEND_PATH_TO_ADDRESS und wenn x-google-backend auf der Vorgangsebene der OpenAPI-Spezifikation verwendet wird, path_translation ist standardmäßig auf CONSTANT_ADDRESS festgelegt. Wenn das Feld address fehlt, wird path_translation nicht angegeben und tritt nicht auf.

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 serverlose GCP-Back-Ends.

Back-End-Unterstützung im ESP aktivieren

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

Der 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, nimmt er den ursprünglichen Anfragepfad und übersetzt ihn, bevor er eine Anfrage an das Ziel-Back-End sendet. 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 dadurch berechnet, dass 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
    • Mit OpenAPI-Pfadparametern
      • OpenAPI-Pfad: /hello/{name}
      • Anfragepfad: /hello/world
      • URL der Zielanfrage: https://my-project-id.appspot.com/hello/world
    • Ohne OpenAPI-Pfadparameter
      • OpenAPI-Pfad: /hello
      • Anfragepfad: /hello
      • URL der Zielanfrage: https://my-project-id.appspot.com/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 angepasste CORS-Unterstützung im Back-End-Code implementieren müssen, legen Sie allowCors: True fest, damit der ESP alle CORS-Anfragen an den Back-End-Code weiterleitet:

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 von der API akzeptierten Zielgruppen angezeigt. Diese Erweiterung akzeptiert einen einzelnen String mit durch ein Komma getrennten Werten. Zwischen den Zielgruppen dürfen sich keine Leerzeichen befinden.

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 zur Kennzeichnung des Messwerts in der Cloud Console auf der Seite Endpoints > Dienste auf dem Tab Kontingente angezeigt wird. 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 Cloud Console angefügt. Wenn Sie beispielsweise "Leseanfragen" als Anzeigenamen angeben, wird in der 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 (zum Beispiel "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 einem ganzzahligen Wert, der die maximale Anzahl an Anfragen darstellt, die für die angegebene Einheit zulässig sind (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