Cloud Endpoints konfigurieren

Auf dieser Seite werden die Konfigurationsdateien beschrieben, die zum Erstellen eines von Endpoints verwalteten gRPC-Dienstes erforderlich sind.

Vorbereitung

Sie sollten Folgendes bereits haben:

Dienstname auswählen

Cloud Endpoints verwendet den Namen, den Sie in der YAML-Datei für die gRPC API-Konfiguration festlegen, als Namen Ihres Dienstes.

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 die folgenden 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 Domain cloud.goog. 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. Wenn Sie die Domain cloud.goog verwenden möchten, muss der Dienstname das folgende Format haben, wobei YOUR_API_NAME der Name Ihrer API und YOUR_PROJECT_ID Ihre Google Cloud-Projekt-ID ist:

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.

Protokollpuffer konfigurieren

  1. Erstellen Sie eine .proto-Datei für Ihren Dienst. Einzelheiten können Sie im Entwicklerleitfaden
    nachlesen.

  2. Kompilieren Sie die Protokollpuffer mithilfe des protoc-Compilers für Ihre Sprache. Beispiel:

    protoc
  --proto_path=. \
  --include_imports \
  --include_source_info \
  --descriptor_set_out=api_descriptor.pb \
  bookstore.proto

    Im vorherigen Befehl ist --proto_path auf das aktuelle Arbeitsverzeichnis festgelegt. Wenn Sie in Ihrer gRPC-Build-Umgebung ein anderes Verzeichnis für .proto-Eingabedateien verwenden, ändern Sie --proto_path entsprechend, sodass der Compiler das Verzeichnis mit der gespeicherten .proto-Datei durchsucht.

    Wenn der protoc-Befehl zum Generieren der Deskriptordatei fehlschlägt, prüfen Sie, ob Folgendes gegeben ist:

    • Ihre Version von protoc ist aktuell.
    • Sie haben den --proto_path oder seine Kurzform -I für die Stammverzeichnisse für importierte .proto-Dateien angegeben. Weitere Informationen finden Sie in der Dokumentation zu Protokollpuffern.
    • Sie haben --include_imports angegeben.

    Wenn die Clients über HTTP mit JSON auf den gRPC-Dienst zugreifen sollen, müssen Sie angeben, wie Daten von HTTP mit JSON in gRPC übersetzt werden. Es empfiehlt sich, die in der .proto-Datei definierten APIs mit Annotationen zu versehen. Weitere Informationen finden Sie unter HTTP/JSON für gRPC transcodieren.

gRPC-Dienstkonfigurationsdatei konfigurieren

Sie müssen eine YAML-Datei für die gRPC-Dienstkonfiguration erstellen. In dieser Datei geben Sie den Namen des Dienstes und Nutzungsbeschränkungen an, beispielsweise erforderliche API-Schlüssel. Sie können die Datei api_config.yaml aus dem Bookstore-Beispiel als Modell verwenden.

  1. Speichern Sie eine Kopie von api_config.yaml.

  2. Geben Sie den Namen Ihres Dienstes in das Feld name ein. Beispiel:

    name: bookstore.endpoints.example-project-12345.cloud.goog

  3. Geben Sie den Titel ein, der in der Google Cloud Console auf der Seite Endpunkte > Dienste angezeigt wird. Beispiel:

    title: Bookstore gRPC API

  4. Geben Sie den API-Namen in das Feld apis:name ein. Der eingegebene Text muss exakt mit dem vollständig qualifizierten API-Namen aus der Datei .proto übereinstimmen. Beispiel:

    apis:
  - name: endpoints.examples.bookstore.Bookstore

  5. Konfigurieren Sie den Rest der Datei. Beispiel:

    #
# API usage restrictions.
#
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true

    Weitere Informationen finden Sie unter Regeln und Auswahlen.

Nächste Schritte

Weitere gRPC-Beispiele