OpenAPI 2.0-Erweiterungen in API Gateway

API Gateway akzeptiert eine Reihe von Google-spezifischen Erweiterungen der OpenAPI-Spezifikation, mit denen das Verhalten des Gateways konfiguriert wird. Auf dieser Seite werden benutzerdefinierte Google-spezifische Erweiterungen der OpenAPI-Spezifikation 2.0 beschrieben, mit denen API Gateway-Verhaltensweisen wie Backend-Routing, Authentifizierung und API-Verwaltungsfunktionen konfiguriert werden.

Die Beispiele sind zwar im YAML-Format, JSON wird aber ebenfalls unterstützt.

Namenskonvention

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

x-google-allow

x-google-allow: [configured | all]

Diese Erweiterung wird auf der obersten Ebene einer OpenAPI-Spezifikation verwendet, um anzugeben, welche URL-Pfade über API Gateway zulässig sein sollen.

Die möglichen Werte sind configured und all.

Der Standardwert ist configured. Das bedeutet, dass nur die API-Methoden, die Sie in Ihrer OpenAPI-Spezifikation aufgeführt haben, über API Gateway bereitgestellt werden.

Wenn all verwendet wird, werden nicht konfigurierte Aufrufe – mit oder ohne API-Schlüssel oder Nutzerauthentifizierung – über API Gateway an Ihre API weitergeleitet.

API Gateway verarbeitet Aufrufe an Ihre API unter Berücksichtigung der Groß- und Kleinschreibung. Beispielsweise betrachtet API Gateway /widgets und /Widgets als unterschiedliche 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 Ihrer OpenAPI-Spezifikation aufgeführt ist, blockiert API Gateway die folgende Anfrage, da sie keinen API-Schlüssel enthält:

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

Da Widgets nicht in Ihrer OpenAPI-Spezifikation aufgeführt ist, leitet API Gateway 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 Erweiterung x-google-backend gibt an, wie Anfragen an Remote-Backends weitergeleitet werden. Die Erweiterung kann auf der obersten Ebene, der Vorgangsebene oder auf beiden Ebenen einer OpenAPI-Spezifikation angegeben werden.

Mit der Erweiterung x-google-backend können auch andere Einstellungen für Remote-Back-Ends konfiguriert werden, 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

Erforderlich. 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.

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, wird von API Gateway automatisch der jwt_audience-Wert so festgelegt, dass er mit dem address-Wert übereinstimmt. Wenn address nicht festgelegt ist, setzt API Gateway disable_auth automatisch auf true.

jwt_audience

jwt_audience: string

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

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

Ein in Cloud Run bereitgestelltes Remote-Backend kann Identity and Access Management (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 API Gateway, das Backend aufzurufen, indem Sie dem API Gateway-Laufzeitdienstkonto die Rolle roles/run.invoker zuweisen.

Standardmäßig erstellt API Gateway das Instanz-ID-Token mit einer JWT-Zielgruppe, die dem Feld address entspricht. 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. Bei Remote-Back-Ends, die in App Engine oder mit Identity-Aware Proxy (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, ändert API Gateway Header in Anfragen. Wenn für eine Anfrage der Header Authorization bereits festgelegt ist, führt API Gateway 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 API Gateway 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 API Gateway keine Verifizierung durchführt, wenn die Authentifizierungsmethoden nicht konfiguriert sind.

Konfigurationsbeispiele finden Sie unter API-Konfiguration erstellen.

disable_auth

disable_auth: bool

Optional. Dieses Attribut bestimmt, ob API Gateway das Abrufen eines Instanz-ID-Tokens und das Anhängen an die Anfrage verhindern soll.

Wenn Sie das Ziel-Backend konfigurieren, kann es eine gute Idee sein, IAP oder IAM nicht zum Authentifizieren von Anfragen von API Gateway zu 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 Pfadübersetzungsstrategie fest, die von API Gateway verwendet wird, wenn Anfragen an das Ziel-Backend weitergeleitet werden.

Weitere Informationen zur Pfadübersetzung finden Sie im Abschnitt 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 nicht angegeben und wird nicht verwendet.

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. Bei einem SSE- oder Chunked-Transfer-Endpunkt begrenzt die Frist weiterhin die Dauer des gesamten Streams. Bei einem gRPC- oder WebSocket-Endpunkt begrenzt sie stattdessen die Lücke zwischen Nachrichten. Informationen zu den Zeitlimits für die einzelnen Anfragetypen finden Sie unter Stream-Frist festlegen. Die Standardfrist beträgt 15.0 Sekunden.

Lassen Sie das Feld weg oder legen Sie es auf 0 fest, um die Standardeinstellung zu verwenden. Bei einem negativen Wert wird ebenfalls der Standardwert verwendet. Dies ist jedoch veraltet: Wenn Sie eine API-Konfiguration mit einem negativen Wert erstellen, wird eine Warnung in den Vorgangsmetadaten zurückgegeben und in einer zukünftigen Version wird der Wert abgelehnt.

Die Frist kann auf bis zu 3600 Sekunden konfiguriert werden. Ein Nicht-Streaming-Gateway erzwingt ein niedrigeres Maximum von 600 Sekunden und lehnt eine höhere Frist beim Erstellen oder Aktualisieren des Gateways ab, nicht beim Erstellen der API-Konfiguration.

protocol

protocol: [ http/1.1 | h2 ]

Optional. Das Protokoll, das zum Senden einer Anfrage an das Backend 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.

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

Die Protokollanforderungen hängen vom Streamingtyp ab:

  • gRPC: Sie müssen das Protokoll auf h2 festlegen.
  • WebSockets: Sie müssen http/1.1 verwenden.
  • Server-Sent Events (SSE) und inkrementelle Antwortbereitstellung: Sie können entweder http/1.1 oder h2 verwenden. Wir empfehlen h2 für eine bessere Leistung.

Informationen zur Pfadübersetzung

Wenn API Gateway Anfragen verarbeitet, wird der ursprüngliche Anfragepfad übernommen und übersetzt, bevor eine Anfrage an das Ziel-Backend gesendet wird. 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-Backend 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.

API Gateway für 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. Informationen zum Konfigurieren von API Gateway für die Unterstützung von CORS finden Sie unter CORS-Unterstützung zu API Gateway hinzufügen.

Wenn Sie in Ihrem Backend-Code benutzerdefinierte CORS-Unterstützung implementieren müssen, legen Sie allowCors: True fest, damit API Gateway alle CORS-Anfragen an Ihren Backend-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.

Das Feld x-google-jwks_uri (OpenAPI 2.0) oder jwksUri (OpenAPI 3.x) ist erforderlich. API Gateway unterstützt zwei asymmetrische öffentliche Schlüsselformate, die durch diese OpenAPI-Erweiterung definiert werden:

  • JWK-Satz-Format Beispiel:

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Beispiel:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    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 x-google-jwks_uri (OpenAPI 2.0) oder jwksUri (OpenAPI 3.x) den URI einer Datei fest, die den base64url-codierten Schlüsselstring enthält.

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.

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

Diese Erweiterung wird im OpenAPI-Abschnitt securityDefinitions verwendet, um eine Liste von Zielgruppen bereitzustellen, mit denen das JWT-Feld aud während der JWT-Authentifizierung übereinstimmen sollte. Diese Erweiterung akzeptiert einen einzelnen String mit durch Kommas getrennten Werten. Zwischen den Zielgruppen sind keine Leerzeichen zulässig. Wenn es nicht angegeben ist, sollte das JWT-Feld aud mit dem Feld host im OpenAPI-Dokument übereinstimmen.

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 Identifizierung des Messwerts auf dem Tab Kontingente auf der Seite Endpunkte > Dienste in derGoogle Cloud Console angezeigt wird. Dieser Text wird auch Nutzern Ihrer API auf den Seiten Kontingente unter IAM & Verwaltung und APIs & Dienste angezeigt. Der Anzeigename darf nicht länger als 40 Zeichen sein.

Aus Gründen der Lesbarkeit wird die Einheit des zugehörigen Kontingentlimits automatisch an den Anzeigenamen in derGoogle Cloud Console angehängt. Wenn Sie beispielsweise „Leseanfragen“ als Anzeigenamen angeben, wird in derGoogle Cloud Console „Leseanfragen pro Minute und Projekt“ angezeigt. Wenn Sie nichts angeben, wird den Nutzern Ihrer API auf den Seiten Kontingente unter IAM & Verwaltung und APIs & Dienste „Kontingent ohne Label“ 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. Es wird nur „1/min/{project}“ unterstützt. Das bedeutet, dass das Limit pro Projekt erzwungen und die Nutzung jede Minute zurückgesetzt wird.
Werte 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
Ersetzen Sie YOUR-LIMIT-FOR-THE-METRIC durch einen ganzzahligen Wert, der die maximal zulässige Anzahl von Anfragen für die angegebene Einheit (nur pro Minute, pro Projekt) darstellt. 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 API enthält, ist der API-Name mit dem API Gateway-Dienstnamen identisch. (API Gateway verwendet den Namen, den Sie im Feld host Ihres OpenAPI-Dokuments angeben, als Namen Ihres Dienstes.) 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 benennen und für jede API eine unabhängige Versionsverwaltung einrichten.

Sie können beispielsweise einen Dienst namens api.example.com mit zwei APIs, producer und consumer, mit den hier gezeigten 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 api-gateway api-configs create API_CONFIG_ID \
  --api=my-api \
  --openapi-spec="producer.yaml,consumer.yaml" \
  --project=my-project-id