Eigene Dokumentation über eine API synchronisieren

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 Cloud Console die Seite Dienstkonten auf.

      Zur Seite „Dienstkonten“

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

    3. Klicken Sie auf Dienstkonto erstellen.

    4. Geben Sie im Feld Dienstkontoname einen Namen ein. Die 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 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 Cloud Console die Seite Endpoints > 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.

Das wars! 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]
    
  3. Prüfen Sie, ob die Google Cloud-Befehlszeile (gcloud) für den Zugriff auf Ihre Daten und Dienste in Google Cloud berechtigt ist:

    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. Zur Erstellung eines Credentials-Objekts aus den Anmeldedaten des Dienstkontos und den Bereichen, die der Endpunkt erfordert, und zur Durchführung der Anfrage zur Synchronisierung des Inhalts, ersetzen Sie im folgenden Skript [YOUR_PROJECT_ID], /path/to/service.json und [YOUR_SERVICE_NAME] mit den entsprechenden Werten:
    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 auf Ihrem Linux-Computer die gcloud-Befehlszeile 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