Eigene Dokumentation über eine API synchronisieren

OpenAPI   |  gRPC

Am 21. März 2022 wurde das Cloud Endpoints-Portal eingestellt. Das Cloud Endpoints-Portal ist nach dem 21. März 2023 nicht mehr verfügbar. Der von Cloud Endpoints verwaltete API-Traffic ist von dieser Änderung nicht betroffen. Weitere Informationen finden Sie unter Verworfene Features.

Ihr Portal bietet eine spezielle API zum Synchronisieren Ihrer benutzerdefinierten Inhalte. So rufen Sie die API auf:

1. Synchronisieren Sie Ihre benutzerdefinierten Inhalte manuell mindestens einmal.
2. Erstellen Sie ein Dienstkonto mit der entsprechenden Autorisierung und dem richtigen Schlüssel.
3. Stellen Sie die HTTP-Anfrage, mit der Sie Ihre Inhalte synchronisieren.

Dieses Dokument enthält eine Anleitung zum Erstellen eines Dienstkontos sowie Beispiele zum Senden der Anfrage über Python oder die Befehlszeile.

Autorisiertes Dienstkonto erstellen

Wenn Sie Ihre benutzerdefinierten Inhalte mithilfe einer API synchronisieren möchten, benötigen Sie ein Dienstkonto mit der entsprechenden Autorisierung und dem richtigen Schlüssel. Weisen Sie dem Dienstkonto bei der Erstellung mit den folgenden Schritten die passende Rolle zu und rufen Sie die erforderliche Schlüsseldatei ab:

Console

1. Erstellen Sie ein Dienstkonto:

   1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.

      Zur Seite „Dienstkonten“

   2. Wählen Sie das Projekt aus, für das die API konfiguriert wurde.

   3. Klicken Sie auf Dienstkonto erstellen.

   4. Geben Sie im Feld Dienstkontoname einen Namen ein. Die Google Cloud Console füllt das Feld Dienstkonto-ID anhand dieses Namens aus.

   5. Optional: Im Feld Beschreibung des Dienstkontos können Sie eine entsprechende Beschreibung eingeben.

   6. Klicken Sie auf Erstellen und fortfahren.

   7. Klicken Sie auf Fertig, um das Erstellen des Dienstkontos abzuschließen.

      Schließen Sie das Browserfenster nicht. Sie verwenden es in der nächsten Aufgabe.

2. Laden Sie einen JSON-Schlüssel für das gerade erstellte Dienstkonto herunter:

   1. Klicken Sie in der Google Cloud Console auf die E-Mail-Adresse des von Ihnen erstellten Dienstkontos.
   2. Klicken Sie auf Schlüssel.
   3. Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.

   4. Klicken Sie auf Erstellen. Daraufhin wird eine JSON-Schlüsseldatei auf Ihren Computer heruntergeladen.

      Bewahren Sie die Schlüsseldatei sicher auf, da sie zur Authentifizierung als Ihr Dienstkonto verwendet werden kann. Sie können diese Datei beliebig verschieben und umbenennen.

   5. Klicken Sie auf Schließen.

3. Rufen Sie in der Google Cloud Console die Seite Endpunkte > Dienste für Ihr Projekt auf.

   Endpoints-Dienste

4. Klicken Sie auf den Namen der API, für die Sie benutzerdefinierte Inhalte synchronisieren möchten, um die Zugriffsberechtigungen zu ändern.

5. Wenn die Seitenleiste "Berechtigungen" nicht geöffnet ist, klicken Sie auf +Berechtigungen.

6. Geben Sie im Feld Mitglieder hinzufügen die E-Mail-Adresse des erstellten Dienstkontos ein, um ihm Zugriff auf die API zu gewähren.

7. Klicken Sie in der Drop-down-Liste Rolle auswählen auf Dienstverwaltung und wählen Sie für das Dienstkonto die Rolle Dienstkonfigurationsbearbeiter aus.

Glückwunsch! Sie haben das Dienstkonto erstellt, den privaten Schlüssel in eine JSON-Datei heruntergeladen und dem Dienstkonto die entsprechende Rolle zugewiesen.

gcloud

1. Geben Sie den folgenden Befehl ein, um die Projekt-IDs für Ihre Google Cloud-Projekte aufzurufen:

   gcloud projects list
   

2. Ersetzen Sie im folgenden Befehl [YOUR_PROJECT_ID], damit das Projekt, in dem sich Ihre API befindet, zum Standardprojekt wird:

   gcloud config set project [YOUR_PROJECT_ID]
   

   Wichtig: Sie müssen das Dienstkonto im selben Projekt erstellen, in dem sich auch die API befindet.

3. Prüfen Sie, ob die Google Cloud CLI (gcloud) die Berechtigung für den Zugriff auf Ihre Daten und Dienste in Google Cloud hat:

   gcloud auth login
   

   Wenn Sie mehrere Konten haben, wählen Sie das Konto aus, das sich im Google Cloud-Projekt mit der API befindet. Wenn Sie gcloud auth list ausführen, wird das von Ihnen ausgewählte Konto als aktives Konto für das Projekt angezeigt.

4. Führen Sie zum Erstellen eines Dienstkontos folgenden Befehl aus und ersetzen Sie [SERVICE_ACCOUNT_NAME] und [Service Account to Sync Custom Content] durch den zu verwendenden Namen bzw. Anzeigenamen:

   gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
     --display-name "[Service Account to Sync Custom Content]"
   

   Mit dem Befehl wird dem Dienstkonto eine E-Mail-Adresse im folgenden Format zugewiesen:

   [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   

   Diese E-Mail-Adresse wird für die nachfolgenden Befehle benötigt.

5. Erstellen Sie eine Schlüsseldatei für das Dienstkonto. Ersetzen Sie dabei [KEY_FILE] durch den Dateinamen für den Schlüssel:

   gcloud iam service-accounts keys create ~/[KEY_FILE] \
     --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   

6. Führen Sie folgenden Befehl aus, um dem Dienstkonto Zugriff auf die API mit dem benutzerdefinierten Inhalt zu gewähren. Ersetzen Sie dabei [YOUR_SERVICE_NAME] durch den Namen der API mit dem benutzerdefinierten Inhalt:

   gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
         --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
         --role roles/servicemanagement.configEditor
   

Anfrage zum Synchronisieren des benutzerdefinierten Inhalts senden

In den folgenden Beispielen wird gezeigt, wie Sie eine Anfrage zum Synchronisieren von benutzerdefiniertem Inhalt stellen. Die Anfrage sollte etwa so aussehen:

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

Ersetzen Sie [YOUR_PROJECT_ID] und [YOUR_SERVICE_NAME] durch die entsprechenden Werte. Wenn die Anfrage erfolgreich ist, wird in der Antwort der HTTP-Statuscode 200 zurückgegeben.

Die nächsten Beispiele zeigen, wie ein Zugriffstoken von den Autorisierungsservern von Google abgerufen und verwendet wird, um die Anfrage über Python oder die Befehlszeile an den Endpunkt Ihres Portals zu senden:

Python

1. Installieren Sie die erforderlichen Python-Bibliotheken:

       pip install --upgrade google-auth

2. Wenn Sie ein Credentials-Objekt aus den Anmeldedaten des Dienstkontos und den Bereichen erstellen möchten, die für den Endpunkt erforderlich sind, und die Anfrage zum Synchronisieren des Inhalts stellen möchten, ersetzen Sie im folgenden Skript [YOUR_PROJECT_ID], /path/to/service.json und [YOUR_SERVICE_NAME] durch die entsprechenden Werte:

   from google.oauth2 import service_account
   from google.auth.transport.requests import AuthorizedSession
   
   SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
   SERVICE_ACCOUNT_FILE = "/path/to/service.json"
   PROJECT_ID = "[YOUR_PROJECT_ID]"
   SERVICE_NAME = "[YOUR_SERVICE_NAME]"
   
   credentials = service_account.Credentials.from_service_account_file(
      SERVICE_ACCOUNT_FILE, scopes=SCOPES)
   authed_session = AuthorizedSession(credentials)
   endpoint =
   "https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
   result = authed_session.post(endpoint)
   print result

Befehlszeile

1. Öffnen Sie Cloud Shell oder ein Terminalfenster, wenn Sie die gcloud CLI auf Ihrem Linux-Computer installiert haben.
2. Ersetzen Sie zum Authentifizieren Ihres Dienstkontos [KEY_FILE] durch den Pfad zur Schlüsseldatei des Dienstkontos und führen Sie den folgenden Befehl aus:

   gcloud auth activate-service-account --key-file [KEY_FILE]

3. Rufen Sie über Ihr Dienstkonto ein Autorisierungstoken ab:

   ACCESS_TOKEN=$(gcloud auth print-access-token)

4. Wenn Sie die API aufrufen, übergeben Sie den Tokenwert als Inhabertoken in einem Autorisierungsheader: Ersetzen Sie [YOUR_PROJECT_ID] und [YOUR_SERVICE_NAME] durch die entsprechenden Werte:

   curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
   https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content