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, die zum Konfigurieren von API Gateway-Verhaltensweisen wie Backend-Routing, Authentifizierung und API-Verwaltungsfunktionen verwendet werden.

Die Beispiele sind zwar im YAML-Format, aber JSON wird 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 Ihrer API unter Berücksichtigung der Groß- und Kleinschreibung. API Gateway betrachtet beispielsweise /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 x-google-backend-Erweiterung gibt an, wie Anfragen an Remote-Backends weitergeleitet werden. Die Erweiterung kann auf der obersten Ebene, auf der Vorgangsebene oder auf beiden Ebenen einer OpenAPI-Spezifikation angegeben werden.

Mit der x-google-backend-Erweiterung können auch andere Einstellungen für Remote-Back-Ends konfiguriert werden, z. B. Authentifizierung und Zeitüberschreitungen. 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 jwt_audience in API Gateway automatisch auf den Standardwert address gesetzt. Wenn address nicht festgelegt ist, wird disable_auth von API Gateway automatisch auf true gesetzt.

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 fügt beim Proxying von Anfragen dem Header Authorization ein Instanz-ID-Token hinzu. Das Instanz-ID-Token repräsentiert das Laufzeit-Dienstkonto, 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 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 Back-End aufrufen, 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-Backends, 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, werden Header in Anfragen von API Gateway geändert. Wenn in einer Anfrage der Authorization-Header bereits festgelegt ist, führt das API-Gateway folgende Aktionen 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. Mit dieser Eigenschaft wird festgelegt, 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 vom 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 Strategie für die Pfadübersetzung fest, die vom API Gateway verwendet wird, wenn Anfragen an das Ziel-Backend weitergeleitet werden.

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

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 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. 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-Deadline festlegen. Die Standardfrist beträgt 15.0 Sekunden.

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

Die Frist kann auf bis zu 3600 Sekunden konfiguriert werden. Bei einem Nicht-Streaming-Gateway wird ein niedrigerer Höchstwert von 600 Sekunden erzwungen. Eine höhere Frist wird beim Erstellen oder Aktualisieren des Gateways und nicht beim Erstellen der API-Konfiguration abgelehnt.

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.

Für sichere HTTP-Back-Ends (https://), die HTTP/2 unterstützen, legen Sie dieses Feld auf h2 fest, um die Leistung zu verbessern. Dies ist die empfohlene Option für Google Cloud serverlose 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 Antwortübermittlung: Sie können entweder http/1.1 oder h2 verwenden. Wir empfehlen h2, um die Leistung zu verbessern.

Pfadübersetzung

Wenn API Gateway Anfragen verarbeitet, wird der ursprüngliche Anfragepfad ü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-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.

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 zur Unterstützung von CORS finden Sie unter API Gateway CORS-Unterstützung hinzufügen.

Wenn Sie benutzerdefinierte CORS-Unterstützung in Ihrem Backend-Code 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 x-google-jwks_uri (OpenAPI 2.0) oder jwksUri (OpenAPI 3.x) auf 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, die mit dem JWT-Feld aud während der JWT-Authentifizierung übereinstimmen müssen. Diese Erweiterung akzeptiert einen einzelnen String mit durch Kommas getrennten Werten. Zwischen den Zielgruppen sind keine Leerzeichen zulässig. Wenn nicht angegeben, 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. Mit einem Kontingent können Sie die Häufigkeit steuern, mit der Anwendungen die Methoden in Ihrer 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.

Zum besseren Verständnis 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 -Konsole „Leseanfragen pro Minute und Projekt“ angezeigt. Wenn nicht angegeben, wird den Nutzern Ihrer API auf den Seiten Kontingente unter IAM & Verwaltung und APIs & Dienste das 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 durchgesetzt wird 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 Ganzzahlwert, der die maximale Anzahl von Anfragen angibt, die für die angegebene Einheit zulässig sind (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 API enthält, ist der API-Name mit dem API Gateway-Dienstnamen identisch. (API Gateway verwendet den Namen, den Sie im Feld host des OpenAPI-Dokuments angeben, als Namen des 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 Versionierung festlegen.

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