Cloud Endpoints konfigurieren

Cloud Endpoints unterstützt APIs, die mit Version 2.0 der OpenAPI-Spezifikation beschrieben werden. Sie können ein OpenAPI-Dokument verwenden, um die API-Oberfläche zu beschreiben und Endpoints-Funktionen wie Authentifizierungsregeln und Kontingente zu konfigurieren.

Cloud Endpoints nutzt insbesondere folgende Pflichtfelder des OpenAPI-Dokuments:

  • host
  • info.title
  • info.version
  • operationId

Auf dieser Seite wird beschrieben, wie Endpoints die obigen Felder nutzt. Anhand dieser Informationen können Sie die Vorbereitung des OpenAPI-Dokuments für die Bereitstellung abschließen.

Voraussetzungen

Sie sollten Folgendes bereits haben:

host

Cloud Endpoints verwendet den Namen, den Sie im Feld host des OpenAPI-Dokuments als Namen Ihres Dienstes konfigurieren.

Der Name Ihres API-Dienstes muss in der Google Cloud eindeutig sein. Da Endpoints DNS-kompatible Namen verwendet, um Dienste zu identifizieren, wird empfohlen, als Dienstnamen den Domain- oder Subdomainnamen Ihrer API zu verwenden. Bei diesem Ansatz stimmt der Name, der auf der Seite Endpoints-Dienste angezeigt wird, mit dem überein, der in Anfragen an Ihre API verwendet wird. Wenn der Dienst- und der Domainname identisch sind, können Sie außerdem ein Cloud Endpoints-Portal für Ihre API-Nutzer erstellen. Endpoints stellt folgende Anforderungen an den Dienstnamen:

  • Der Domainname darf höchstens 253 Zeichen enthalten.
  • Der Domainname muss mit einem Kleinbuchstaben beginnen.
  • Für jeden Abschnitt des Domainnamens, der durch Punkte getrennt ist, gelten folgende Anforderungen:
    • Muss mit einem Kleinbuchstaben beginnen.
    • Darf nicht mit einem Bindestrich enden.
    • Die restlichen Zeichen können Kleinbuchstaben, Ziffern oder Bindestriche sein.
    • Die maximale Länge beträgt 63 Zeichen.

Sie können entweder eine eigene benutzerdefinierte Domain registrieren (z. B. example.com) oder eine von Google verwaltete verwenden.

Von Google verwaltete Domain verwenden

Google besitzt und verwaltet die Domains cloud.goog und appspot.com. Wenn Sie eine von Google verwaltete Domain verwenden möchten, müssen Sie Ihre Google Cloud-Projekt-ID als Teil des Dienstnamens angeben. Da Google Cloud-Projekte eine weltweit eindeutige Projekt-ID haben, sorgt diese Anforderung für einen eindeutigen Dienstnamen.

Der verwendete Domainname hängt von dem Back-End ab, auf dem Ihre API gehostet wird:

  • Für APIs, die in der flexiblen App Engine-Umgebung gehostet werden, müssen Sie die Domain appspot.com verwenden. Der Dienstname muss das folgende Format haben, wobei YOUR_PROJECT_ID Ihre Google Cloud-Projekt-ID darstellt:

    YOUR_PROJECT_ID.appspot.com

    Wenn Sie die API in App Engine bereitstellen, wird automatisch ein DNS-Eintrag mit dem Namensformat YOUR_PROJECT_ID.appspot.com erstellt.

  • Für APIs, die in Compute Engine, Google Kubernetes Engine oder Kubernetes gehostet werden, müssen Sie die Domain cloud.goog verwenden. Der Dienstname muss das folgende Format haben, wobei YOUR_API_NAME für den Namen Ihrer API steht:

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog

    Informationen zur Verwendung dieser Domain als Domainname der API finden Sie unter DNS in der Domain cloud.goog konfigurieren.

Benutzerdefinierte Domain verwenden

Wenn Sie keine von Google verwaltete Domain verwenden möchten, können Sie eine benutzerdefinierte Domain (z. B. myapi.mycompany.com) verwenden, für die Sie Nutzungsrechte haben. Bevor Sie die API-Konfiguration bereitstellen, führen Sie die Schritte unter Inhaberschaft prüfen aus.

info.title

Das Feld info.title ist ein nutzerfreundlicher Name für Ihre API. Auf der Seite Endpoints > Dienste in der Google Cloud Console wird der von Ihnen konfigurierte Text im Feld info.title angezeigt. Sollten Sie mehr als eine API pro Google Cloud-Projekt haben, wird der API-Name in einer Liste aufgeführt, wenn Sie die Seite öffnen. Sie können auf den API-Namen klicken, um eine weitere Seite zu öffnen, auf der die Kennzahlen der API, der Bereitstellungsverlauf und andere Informationen angezeigt werden.

info.version

Auf der Seite Endpoints > Dienste in der Google Cloud Console wird die Versionsnummer für Ihre API angezeigt. Bevor Sie Ihre API-Konfiguration zum ersten Mal bereitstellen:

  • Geben Sie im Feld info.version die Versionsnummer der entsprechenden API-Version ein, z. B. 1.0.

  • Geben Sie im Feld basePath die Hauptversionsnummer ein, z. B. /v1.

Weitere Informationen zur Versionierung Ihrer API finden Sie unter API-Lebenszyklus verwalten.

operationId

Obwohl die operationId ein optionales Feld in der OpenAPI-Spezifikation ist, benötigt Endpoints dieses Feld, da es für die interne Identifizierung des Vorgangs verwendet wird. Der String, den Sie für die operationId verwenden, muss in Ihrer API eindeutig sein. Eine Anleitung zur Benennung finden Sie in der OpenAPI-Spezifikation in der Beschreibung für operationId.

Nächste Schritte