Nutzerhandbuch der Cloud Support API V2

Überblick

Weitere Informationen zu den Vorteilen und den Vorteilen der Cloud Support API finden Sie in der Übersicht zur Cloud Support API. Auf dieser Seite werden die ersten Schritte mit Version 2 der Cloud Support API beschrieben. Es gibt auch eine v2beta-Version, aber es gibt einige Unterschiede zwischen den beiden. Einige Änderungen und Funktionen sind möglicherweise in v2beta vor v2 verfügbar. Die v2 API ist jedoch für die meisten Anwendungsfälle wahrscheinlich besser geeignet.

Als Nächstes erfahren Sie, wie Sie die v2-API einrichten.

Einstieg

Bevor Sie die Cloud Support API verwenden können, müssen Sie Folgendes tun:

  1. Aktivieren Sie die Cloud Support API. Rufen Sie dazu in der Google Cloud Console die Seite „Cloud Support API“ auf und klicken Sie auf AKTIVIEREN.

  2. Stellen Sie ein Dienstkonto bereit. Folgen Sie dazu der Anleitung unter Dienstkonten erstellen. Weitere Informationen zu Dienstkonten

  3. Verwenden Sie den Tab „IAM“ in der Google Cloud Console, um dem Dienstkonto die Rolle Organization Viewer oder eine andere Rolle mit der Berechtigung resourcemanager.organizations.get zu gewähren.

    Sie können auch den Befehl gcloud organizations add-iam-policy-binding verwenden:

    gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/resourcemanager.organizationViewer \\
--member SERVICE_ACCOUNT

    Unter Organisations-ID abrufen erfahren Sie, wie Sie den richtigen Wert für „ORG_ID“ ermitteln.

  4. Gewähren Sie dem Dienstkonto die Rolle „Technischer-Support-Bearbeiter“ oder Technischer-Support-Betrachter. Führen Sie dazu folgenden Befehl aus:

    gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/cloudsupport.techSupportEditor \\
--member SERVICE_ACCOUNT

  5. Wenn Sie Integrationen von Drittanbietern wie JIRA verwenden, gewähren Sie der Drittanbieteranwendung Zugriff auf das Dienstkonto. Weitere Informationen zur Authentifizierung finden Sie unter Authentifizierung.

Wenn Sie OAuth 2.0 zur Authentifizierung verwenden möchten:

  1. Wenn Sie OAuth2 noch nicht für die Authentifizierung bei Google verwenden, richten Sie es ein, indem Sie OAuth 2.0 für den Zugriff auf Google APIs verwenden. Achten Sie besonders auf den Abschnitt zur inkrementellen Autorisierung.

  2. Achten Sie darauf, dass die folgenden zwei Bereiche den von Ihrer Anwendung verwendeten OAuth2-Client-IDs hinzugefügt werden:

    • Für den allgemeinen Zugriff auf Google Cloud: https://www.googleapis.com/auth/cloud-platform oder https://www.googleapis.com/auth/cloud-platform.read-only
    • Zugriff zum Abrufen oder Erstellen von Supportfällen und anderen supportbezogenen Daten: https://www.googleapis.com/auth/cloudsupport

Zugriffssteuerung und IAM-Rollen

Customer Care verwendet die folgenden IAM-Rollen, um den Zugriff auf Supportanfragen zu steuern. Sie können diese verwenden oder eigene benutzerdefinierte Rollen mit beliebigen Berechtigungen erstellen. Weitere Informationen zu IAM finden Sie unter Zugriffssteuerung mit IAM.

Rolle Berechtigungen
Tech Support Viewer cloudsupport.techCases.get
cloudsupport.techCases.list
cloudsupport.techCaseAttachments.list
cloudsupport.techCaseAttachments.download
cloudsupport.techCaseComments.list
cloudsupport.techCaseUpdates.list
Tech Support Editor Berechtigungen für Technischer-Support-Betrachter
cloudsupport.techCases.create
cloudsupport.techCases.update
cloudsupport.techCases.escalate
cloudsupport.techCases.close
cloudsupport.techCaseAttachments.create
cloudsupport.techCaseComments.create

Entscheiden, welche Bibliotheken zum Aufrufen der Cloud Support API verwendet werden sollen

Es gibt drei allgemeine Pfade, um die API aufzurufen.

  1. Verwenden Sie die Cloud-Clientbibliotheken der Cloud Support API für die Sprache, die Sie verwenden möchten. Diese sind für viele verschiedene Sprachen verfügbar, das Hochladen oder Herunterladen von Anhängen wird jedoch nicht unterstützt. Weitere Informationen zu diesem Bibliothekstyp finden Sie unter Cloud-Clientbibliotheken.

  2. Verwenden Sie die Google API-Bibliothek für Python, um einen Stub zum Aufrufen der Cloud Support API zu erstellen. Dies ist der alte Ansatz zum Aufrufen der API. Sie können damit Anhänge hoch- oder herunterladen. Weitere Informationen zu diesem Bibliothekstyp finden Sie unter Google API-Clientbibliotheken.

  3. Verwenden Sie cURL oder rufen Sie die API direkt auf. Dies hat den Vorteil, dass sie vollständig anpassbar ist, Sie aber alles selbst konfigurieren müssen.

Wenn Sie keine Anhänge verwenden müssen, empfehlen wir die Verwendung von Cloud-Clientbibliotheken. Andernfalls empfehlen wir die Verwendung der Google API-Bibliothek für Python.

Cloud-Clientbibliotheken verwenden

In der Cloud Support API sind Cloud-Clientbibliotheken verfügbar für:

Rufen Sie einfach die zugehörige Seite auf und folgen Sie der Anleitung.

Google API-Bibliothek für Python verwenden

Führen Sie die folgenden Schritte aus, um mit der Google API-Bibliothek für Python zu beginnen:

  1. Installieren Sie das Google Discovery-Paket mit pip.

    pip install google-api-python-client

  2. Erstellen Sie einen Stub in Ihrem Code.

    import googleapiclient.discovery

api_version = "v2"
supportApiService = googleapiclient.discovery.build(
    serviceName="cloudsupport",
    version=api_version,
    discoveryServiceUrl=f"https://cloudsupport.googleapis.com/$discovery/rest?version={api_version}",
)

  3. Rufen Sie den gewünschten Endpunkt auf. Wir haben Beispiele dafür für jeden Endpunkt in der Cloud Support API bereitgestellt. Beispiel: cases.list.

Wenn Sie die API mit der Google API-Bibliothek für Python aufrufen, werden die Standardanmeldedaten für die Umgebung verwendet, in der Ihr Programm ausgeführt wird. Prüfen Sie, ob das Dienstkonto in dieser Umgebung die im Abschnitt Erste Schritte genannten Berechtigungen hat.

cURL verwenden

Es gibt zwei Hauptmethoden, um Ihren cURL-Aufruf zu authentifizieren. Sie können ein Dienstkonto oder die Standardanmeldedaten für Anwendungen verwenden. Weitere Informationen zu Standardanmeldedaten für Anwendungen finden Sie unter Funktionsweise von Standardanmeldedaten für Anwendungen.

Mit Dienstkonto authentifizieren

  1. Authentifizieren Sie sich über die Google Cloud CLI.

    gcloud auth activate-service-account SERVICE_ACCOUNT_EMAIL \
  --key-file=/path/key.json \
  --project=PROJECT_ID

  2. Senden Sie die Anfrage.

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://cloudsupport.googleapis.com/v2/organizations/ORGANIZATION_ID/cases

Mit Standardanmeldedaten für Anwendungen authentifizieren

  1. Authentifizieren Sie sich über die Google Cloud CLI.

    gcloud auth application-default login

  2. Senden Sie die Anfrage. Fügen Sie unbedingt einen x-goog-user-project-Header ein. Dieser ist erforderlich, wenn Sie die Cloud Support API mit den Standardanmeldedaten für Anwendungen aufrufen.

    curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: $(gcloud config get-value project)" \
  https://cloudsupport.googleapis.com/v2/organizations/ORGANIZATION_ID/cases