Endpoints-Konfiguration bereitstellen

OpenAPI | gRPC

Nachdem Sie Cloud Endpoints in einem OpenAPI-Dokument konfiguriert haben, stellen Sie es bereit, damit Endpoints über die Informationen verfügt, die zum Verwalten Ihrer API erforderlich sind. Die Endpoints-Konfiguration wird mit dem Befehl gcloud endpoints services deploy bereitgestellt. Dieser Befehl verwendet Service Infrastructure, die grundlegende Dienstplattform von Google. Sie wird von Endpoints und anderen Diensten verwendet, um APIs und Dienste zu erstellen und zu verwalten. Auf dieser Seite wird beschrieben, wie Sie ein OpenAPI-Dokument in Endpoints bereitstellen.

Vorbereitung

Sie sollten Folgendes bereits haben:

Ein Google Cloud-Projekt mit der Rolle Bearbeiter oder Inhaber. Nach der ersten Bereitstellung können Sie einem Nutzer, einer Gruppe oder einem Dienstkonto die restriktivere Rolle des Dienstkonfigurationsbearbeiters erteilen. Weitere Informationen finden Sie unter Zugriff auf die API gewähren und widerrufen.
Konfigurierte Endpoints
Wenn Sie einen benutzerdefinierten Domainnamen verwenden (z. B. my-api.example.com), müssen Sie ihn überprüfen, bevor Sie das OpenAPI-Dokument bereitstellen.

Google Cloud CLI für die Bereitstellung vorbereiten

Verwenden Sie das gcloud-Befehlszeilentool, um die Konfiguration bereitzustellen. Weitere Informationen zu den Befehlen finden Sie in der gcloud-Referenz.

So bereiten Sie die Bereitstellung vor:

Installieren und initialisieren Sie die gcloud CLI.
Aktualisieren Sie die gcloud CLI:
```
gcloud components update
```
Prüfen Sie, ob die gcloud CLI für den Zugriff auf Ihre Daten und Dienste berechtigt ist:
```
gcloud auth login
```
Ein neuer Browsertab wird geöffnet und Sie werden aufgefordert, ein Konto auszuwählen.
Legen Sie das Standardprojekt fest. Ersetzen Sie [YOUR-PROJECT-ID] durch Ihre GCP-Projekt-ID:
```
gcloud config set project [YOUR-PROJECT-ID]
```
Wenn Sie das API-Back-End in Kubernetes oder Kubernetes Engine bereitstellen, führen Sie den folgenden Befehl aus, um neue Nutzeranmeldedaten zur Verwendung als Standardanmeldedaten für Anwendungen abzurufen. Die Nutzeranmeldedaten sind für die Autorisierung von kubectl erforderlich.
```
gcloud auth application-default login
```
Ein neuer Browsertab wird geöffnet und Sie werden aufgefordert, ein Konto auszuwählen.

`openapi.json`-Syntax wird validiert…

Die OpenAPI-Dokumentdatei kann im YAML- oder JSON-Format vorliegen. Wenn sie im JSON-Format vorliegt, sollten Sie die Syntax vor dem Bereitstellen der Datei überprüfen. Wenn Sie überprüfen möchten, ob die JSON-Datei openapi.json richtig formatiert ist, können Sie sie in einem Texteditor wie vim öffnen, der die Prüfung von JSON unterstützt, oder einen JSONLint-Onlinedienst nutzen. Alternativ können Sie Python verwenden:

python -m json.tool openapi.json

Stellen Sie die JSON-Datei zur besseren Lesbarkeit optimiert dar:

python -m json.tool input.json > output.json

Ersetzen Sie input.json durch den Pfad zur Datei openapi.json. output.json ist die optimiert dargestellte JSON-Datei.

OpenAPI-Dokument überprüfen

Cloud Endpoints unterstützt derzeit nicht alle OpenAPI-Konstrukte. Vor dem Bereitstellen können Sie Ihr OpenAPI-Dokument überprüfen.

So überprüfen Sie Ihr OpenAPI-Dokument:

Geben Sie als Verzeichnis den Speicherort Ihres OpenAPI-Dokuments an.
Bestätigen Sie das Google Cloud-Projekt, in dem Sie den Dienst erstellen möchten. Wenn Sie einen benutzerdefinierten Domainnamen verwenden (z. B. myapi.example.com), müssen Sie die vom folgenden Befehl zurückgegebene Projekt-ID überprüfen, damit der Dienst nicht im falschen Projekt erstellt wird.
```
gcloud config list project
```
Wenn Sie das Standardprojekt ändern müssen, führen Sie den folgenden Befehl aus und ersetzen Sie [YOUR_PROJECT_ID] durch die ID des Google Cloud-Projekts, in dem Sie den Dienst erstellen möchten:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Führen Sie den folgenden Befehl aus und ersetzen Sie [YOUR_OPENAPI_DOCUMENT] durch den Namen des OpenAPI-Dokuments, das Ihre API beschreibt:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
```

Der Befehl gcloud ruft dann die Service Management API auf, um einen verwalteten Dienst mit dem Namen zu erstellen, den Sie im Feld host der Datei im OpenAPI-Dokument angegeben haben. Wenn Sie das Flag --validate-only angeben, wird trotzdem ein Dienst erstellt, die Konfiguration wird jedoch nicht bereitgestellt. Das OpenAPI-Dokument lässt sich nur überprüfen, wenn dabei ein Dienst erstellt wird. Sie können zwar den Dienst löschen, doch auch dann ist es in Service Management etwa 30 Tage lang nicht möglich, einen Dienst mit demselben Namen zu erstellen.

OpenAPI-Dokument bereitstellen

Zum Bereitstellen der API führen Sie die Google Cloud CLI aus, die Service Management verwendet, um Ihre API-Konfiguration hochzuladen und einen verwalteten Dienst zu erstellen (oder zu aktualisieren).

So stellen Sie Ihr OpenAPI-Dokument bereit:

Geben Sie als Verzeichnis den Speicherort Ihres OpenAPI-Dokuments an.
Überprüfen Sie anhand der Projekt-ID, die vom folgenden Befehl zurückgegeben wurde, ob der Dienst im richtigen Projekt erstellt wird.
```
gcloud config list project
```
Wenn Sie das Standardprojekt ändern müssen, führen Sie den folgenden Befehl aus und ersetzen Sie [YOUR_PROJECT_ID] durch die ID des Google Cloud-Projekts, in dem Sie den Dienst erstellen möchten:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Führen Sie den folgenden Befehl aus und ersetzen Sie [YOUR_OPENAPI_DOCUMENT] durch den Namen des OpenAPI-Dokuments, das Ihre API beschreibt:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
```

Wenn Sie den vorherigen Befehl zum ersten Mal ausführen, erstellt Service Management im Standardprojekt einen neuen Cloud Endpoints-Dienst mit dem Namen, den Sie im Feld host in Ihrem OpenAPI-Dokument eingegeben haben, und lädt die Dienstkonfiguration hoch.

Beim Erstellen und Konfigurieren des Diensts gibt Service Management Informationen an das Terminal aus. Nach erfolgreichem Abschluss des Vorgangs sehen Sie eine Zeile wie die folgende, die die Dienstkonfigurations-ID und den Dienstnamen enthält:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Im obigen Beispiel ist 2017-02-13r0 die Dienstkonfigurations-ID und echo-api.endpoints.example-project-12345.cloud.goog der Dienstname.

Nach der erfolgreichen Bereitstellung wird die API in der Google Cloud Console auf der Seite Endpunkte > Dienste angezeigt.

Wenn Sie eine Fehlermeldung erhalten, lesen Sie die Informationen unter Fehlerbehebung bei der Endpoints-Konfigurationsbereitstellung.

Neu bereitstellen

Wenn Sie Änderungen an Ihrem OpenAPI-Dokument vornehmen, müssen Sie es neu bereitstellen, damit Cloud Endpoints über die neueste Version der API-Dienstkonfiguration verfügt. Sie müssen den ESP nicht noch einmal bereitstellen oder neu starten, wenn Sie ihn zuvor mit der Option rollout auf managed festgelegt haben. Diese Option konfiguriert den ESP so, dass die zuletzt bereitgestellte Dienstkonfiguration verwendet wird. Wenn Sie diese Option innerhalb von 5 Minuten nach der Bereitstellung einer neuen Dienstkonfiguration angeben, erkennt der ESP die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option anstelle einer konkreten Konfigurations-ID anzugeben, die vom ESP verwendet werden soll.

Nach der ersten Bereitstellung der Endpoints-Konfiguration können Sie einem Nutzer, einem Dienstkonto oder einer Gruppe eine Rolle zuweisen, die eine erneute Bereitstellung der Endpoints-Konfiguration zulässt. Weitere Informationen finden Sie unter Zugriff auf die API gewähren und widerrufen.