Nutzerhandbuch für die Cloud Support API

Auf dieser Seite werden die ersten Schritte mit Version 1 der cloudsupport.googleapis.com API beschrieben. Version 2 dieser API ist derzeit nur als Pre-GA-Release verfügbar. Weitere Informationen finden Sie unter Beschreibungen der Startphase.

Prozessübersicht

In diesem Abschnitt wird der allgemeine Prozess für die ersten Schritte mit der API beschrieben.

  1. Das Customer Care-Team erstellt ein Supportkonto für den Kunden. Dies ist eine Voraussetzung für alle weiteren Vorgänge.

  2. Der Kunde gibt dem Customer Care-Team an, welche Projekt-ID er für den Zugriff auf die API verwenden möchte. Dieses Projekt wird als Nutzerprojekt für die API festgelegt.

    Dieses Projekt ist die Ressource, für die die API aktiviert ist. Für den Aufruf der API können jedoch die Anmeldedaten aus jedem Google Cloud-Projekt verwendet werden.

  3. Der Kunde generiert einen API-Schlüssel für das Nutzerprojekt. Der Kunde verwendet diesen API-Schlüssel, um Aufrufe an die API zu senden. Informationen zum Generieren eines API-Schlüssels finden Sie unter API-Schlüssel verwenden.

  4. Das Customer Care-Team lässt den API-Zugriff des Kundenteams zu (durch Anwenden der richtigen Sichtbarkeitslabel).

  5. Das Customer Care-Team erlaubt dem Kundensupportkonto den Zugriff auf Dienstkonten.

  6. Der Kunde aktiviert die Cloud Support API, indem er in der Google Cloud Console die Seite Cloud Support API aufruft und auf AKTIVIEREN klickt.

    Zur Seite "Cloud Support API"

Wenn Sie die Dienstkontointegration nutzen möchten:

  1. Der Kunde stellt mindestens ein Dienstkonten bereit. Dazu folgt er der Anleitung unter Details zu Dienstkonten.

  2. Der Kunde gewährt dem Dienstkonto die Rolle Organization Viewer auf dem Tab „IAM“ in der Google Cloud Console oder eine andere Rolle mit der Berechtigung resourcemanager.organizations.get.

    Dies kann auch programmatisch erfolgen: 

      gcloud organizations add-iam-policy-binding
  organizations/ord-id
  --role roles/resourcemanager.organizationViewer
  --member service-account

  3. Der Kunde fügt eines oder mehrere dieser Dienstkonten als Supportnutzer über die Seite Support > Einstellungen in der Google Cloud Console hinzu.

  4. Der Kunde lässt seinen JIRA-Connector oder andere Anwendungen durch Teilen der Anmeldedaten auf das Dienstkonto zugreifen. Die erforderlichen Schritte finden Sie unter Authentifizierung.

  5. Wenn der Kunde bereits ein Tool zur Verwaltung von Anmeldedaten hat, ist es sinnvoll, dasselbe Tool für Google Cloud-Dienstkonten zu nutzen.

  6. Die Anwendungen des Kunden führen reguläre API-Aufrufe aus (ganz wie es Endnutzer tun würden). Dabei werden die Anmeldedaten des Dienstkontos anstelle der Anmeldedaten des Endnutzers verwendet.

Wenn Sie die OAuth 2.0-Authentifizierung haben wollen:

  1. Wenn Sie sich nicht bereits bei Google mit OAuth2 authentifizieren, richten Sie dies ein.
    Folgen Sie dazu den Anleitungen für OAuth 2.0 für den Zugriff auf Google APIs. Achten Sie besonders auf den Abschnitt zur inkrementellen Autorisierung.
  2. Achten Sie darauf, dass die beiden folgenden 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
    • Für den Zugriff zum Abrufen oder Erstellen von Support-Tickets und anderen supportbezogenen Daten: https://www.googleapis.com/auth/cloudsupport

API-Definition abrufen

Die API-Definition wird als Google Cloud-Discovery-Dokument bereitgestellt.

Hier ein Beispiel: Ersetzen Sie <API_KEY> durch einen API-Schlüssel, den Sie in einem früheren Schritt aus dem Nutzerprojekt generiert haben.

curl 'https://cloudsupport.googleapis.com/$discovery/rest?key=<API_KEY>&labels=TRUSTED_TESTER&version=v1alpha2' > /tmp/cloudsupport.v1alpha2.json

REST API

Für alle unten aufgeführten Endpunkte sollte der Wert für <host> durch cloudsupport.googleapis.com ersetzt werden.

Supportanfragen

Supportanfragen abrufen und erstellen.

Erforderliche Rollen
Typ Rolle
IAM Supportkontobetrachter (Organisation)
IAM Organisationsbetrachter (Organisation)

GetCase

Ruft den angegebenen Supportfall ab.

REST-Format
GET <host>/v1/{name=supportAccounts/*/cases/*}
Parameter

Supportkonto und Fallnummer, die in der Anfrage-URL angegeben sind.

Beispiel
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases/5678

CreateCase

Erstellt einen Fall und ordnet ihn dem angegebenen Supportkonto zu.

REST-Format
POST <host>/v1/{parent=supportAccounts/*}/cases
Parameter
Name Typ Beschreibung
case Case

Ein Fallobjekt.

Beispiel:


     { \
        display_name: "My test case for Istio", \
        description: "Istio network latency spike", \
        category: "Compute", \
        component: "Istio", \
        subcomponent: "Networking", \
        time_zone: "-07:00", \
        cc_addresses: ["foo@domain.com", "bar@domain.com"], \
        project_id: "my-gcp-test-project-1234", \
        priority: 3 \
      }

Beispiel
curl -v -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type:  application/json' -X POST -d '{ display_name: "My app is down", description: "Datastore appears to be down so my app is broken.", component: "Cloud Datastore", subcomponent: "Availability / Latency", time_zone: "-07:00", project_id: "my-super-project", category: "Storage & Databases", priority: 3 }' https://cloudsupport.googleapis.com/v1/supportAccounts/gcp-sa-1234/cases

Clientbibliotheken erzeugen

Klonen Sie den Google APIs-Clientgenerator:

cd /tmp/; git clone https://github.com/google/apis-client-generator.git;

Prüfen Sie, ob Python 2.7 installiert ist:

sudo apt-get install python

Prüfen Sie, ob PIP installiert ist:

sudo apt-get install python-pip

Installieren Sie die Abhängigkeiten:

pip install google-apis-client-generator

Clientbibliotheken erstellen:

Dieser Befehl generiert eine oder zwei Warnungen, die mit WARNING:root:object without properties beginnen. Sie können ignoriert werden. Die Clientbibliothek wird weiterhin generiert.

./generate.sh --input=/tmp/cloudsupport.v1alpha2.json --output_dir=/tmp/cloudsupport_generated --language=java

Mit der API

Hinweis

  • Abhängigkeit von API-Clientbibliotheken für Java hinzufügen
  • Abhängigkeit von dem Code hinzufügen, der im obigen Schritt generiert wurde

  • Prüfen Sie, ob der Code erfolgreich erstellt wurde

    // Shared constants
String CLOUD_SUPPORT_SCOPE = "https://www.googleapis.com/auth/cloudsupport";

// Customer specific config
String SERVICE_ACCOUNT_ID = "<... service account id ...>";
File SERVICE_ACCOUNT_PRIVATE_KEY = new File("<... p12 key file ...>");
String SUPPORT_ACCOUNT_ID = "supportAccounts/gcp-sa-<......>";

// Service setup
JsonFactory jsonFactory = JacksonFactory.getDefaultInstance();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

// This section is for service account authentication
// If you are using OAuth2 instead, follow guide at
// https://developers.google.com/api-client-library/java/google-oauth-java-client/oauth2
GoogleCredential credential = new GoogleCredential.Builder()
  .setTransport(httpTransport)
  .setJsonFactory(jsonFactory)
  .setServiceAccountId(SERVICE_ACCOUNT_ID)
  .setServiceAccountPrivateKeyFromP12File(SERVICE_ACCOUNT_PRIVATE_KEY)
  .setServiceAccountScopes(Collections.singleton(CLOUD_SUPPORT_SCOPE))
  .build();

// Main API service is ready to use!
CloudSupport supportService = new CloudSupport.Builder(httpTransport, jsonFactory, credential).build();

// Each call will look something like this:
SupportAccount account = supportService.supportAccounts().get(SUPPORT_ACCOUNT_ID).execute();