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 die 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 kann auf der obersten Ebene und/oder Vorgangsebene einer OpenAPI-Spezifikation angegeben werden, um verschiedene Teile des Back-End-Routings zu steuern. Der ESP wird mit einem einzelnen Ziel-Back-End über das --backend Flag (standardmäßig 127.0.0.1:8081, wenn nicht konfiguriert) konfiguriert. Beim Start des ESP wird der gesamte Traffic an dieses Ziel gesendet. Es gibt jedoch einige Situationen, in denen das Senden von Traffic an ein einzelnes Back-End nicht ausreicht:

  • Wenn Sie den Zugriff auf den ESP-Zielspeicherort im Back-End nicht steuern können, z. B. wenn Sie Cloud Functions oder Cloud Run verwenden.
  • Wenn Ihre API mehrere Back-Ends bedient.

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

address

address: URL

Erforderlich. Die URL des Ziel-Back-Ends.

jwt_audience | disable_auth

jwt_audience: STRING

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

disable_auth: BOOL

Optional Wenn Sie IAP oder IAM nicht als Ziel-Back-End-Authentifizierung verwenden möchten, legen Sie true fest.

Wenn weder jwt_audience noch disable_auth eingestellt sind oder disable_auth als false eingestellt ist, ist die Zielgruppe gleich dem Feld address und ein ID-Token mit der Zielgruppe wird dem Anfrageheader Authorization hinzugefügt.

Bei einer Anfrage mit dem Header Authorization wird dessen Wert in einen neuen Header X-Forwarded-Authorization kopiert, wenn ESP diesen überschreiben muss.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Optional Legt die Strategie für die vom ESP verwendete Pfadübersetzung fest, wenn Anfragen ans Ziel-Back-End gesendet werden.

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 Beta 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: STRING

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.

Back-End-Unterstützung im ESP 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 so konfigurieren, dass er CORS-Anfragen zulässt

Wenn die API von einer an einem anderen Ort gehosteten Webanwendung aufgerufen wird, muss die 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 akzeptieren 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 (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 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