Guida dell'utente dell'API Cloud Support V2

Panoramica

Per saperne di più sul motivo per cui dovresti utilizzare l'API Cloud Support e a cosa serve, consulta la panoramica dell'API Cloud Support. Questa pagina illustra come iniziare a utilizzare la versione 2 dell'API Cloud Support. È disponibile anche una versione v2beta, ma ci sono poche differenze tra le due. Alcune modifiche e funzionalità potrebbero essere disponibili nella versione v2beta precedente alla versione 2, ma l'API v2 è probabilmente più adatta alla maggior parte dei casi d'uso.

Ora parleremo di come configurare l'API v2.

Per iniziare

Prima di poter utilizzare l'API Cloud Support, segui questi passaggi:

Abilita l'API Cloud Support visitando la pagina dell'API Cloud Support nella console Google Cloud e facendo clic su ABILITA.
Esegui il provisioning di un account di servizio seguendo le istruzioni in Creare account di servizio. Per scoprire di più sugli account di servizio, vedi Panoramica degli account di servizio.
Utilizza la scheda IAM nella console Google Cloud per concedere all'account di servizio il ruolo Organization Viewer o un altro ruolo che conceda l'autorizzazione resourcemanager.organizations.get.

Puoi anche utilizzare il comando gcloud organizations add-iam-policy-binding:
```
gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/resourcemanager.organizationViewer \\
--member SERVICE_ACCOUNT
```
Per scoprire come trovare il valore corretto di "ORG_ID", vedi Recuperare l'ID organizzazione.

Concedi all'account di servizio il ruolo Editor assistenza tecnica o Visualizzatore assistenza tecnica. Per farlo, esegui:

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

Se utilizzi integrazioni di terze parti come JIRA, concedi all'applicazione di terze parti l'accesso all'account di servizio. Per ulteriori informazioni sull'autenticazione, vedi Panoramica dell'autenticazione.

Se vuoi utilizzare OAuth 2.0 per l'autenticazione:

Se non utilizzi già OAuth2 per l'autenticazione con Google, configuralo seguendo OAuth 2.0 per accedere alle API di Google. Presta particolare attenzione alla sezione sull'autorizzazione incrementale.
Assicurati che i seguenti due ambiti vengano aggiunti agli ID client OAuth2 utilizzati dalla tua applicazione:
- Per l'accesso generale a Google Cloud: https://www.googleapis.com/auth/cloud-platform o https://www.googleapis.com/auth/cloud-platform.read-only
- Per l'accesso in modo da recuperare o creare richieste di assistenza e altri dati relativi all'assistenza: https://www.googleapis.com/auth/cloudsupport

Controllo dell'accesso e ruoli IAM

L'assistenza clienti utilizza i seguenti ruoli IAM per controllare l'accesso alle richieste. Puoi utilizzarli o creare ruoli personalizzati con le autorizzazioni che preferisci. Per saperne di più su IAM, vedi Controllo dell'accesso con IAM.

Role	Autorizzazioni
`Tech Support Viewer`	cloudsupport.techCases.get cloudsupport.techCases.list cloudsupport.techCaseAttachments.list cloudsupport.techCaseAttachments.download cloudsupport.techCaseContacts.list cloudsupport.techCaseUpdates.list
`Tech Support Editor`	Autorizzazioni Visualizzatore assistenza tecnica cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCaseAttachments.create cloudsupport.techCaseContacts.create

Decidere quali librerie utilizzare per chiamare l'API Cloud Support

Esistono tre percorsi generali per chiamare l'API.

Utilizza le librerie client di Cloud dell'API Cloud Support per il linguaggio che vuoi utilizzare. Questi file sono disponibili in un'ampia gamma di lingue, ma non supportano il caricamento o il download degli allegati. Per saperne di più su questo tipo di libreria, consulta Librerie client Cloud
Utilizzare la libreria API di Google Python per creare uno stub per chiamare l'API Cloud Support. Questo è l'approccio legacy per chiamare l'API. che ti consente di caricare o scaricare gli allegati. Per ulteriori informazioni su questo tipo di libreria, consulta l'articolo Librerie client delle API di Google.
Utilizza cURL o chiama direttamente l'API. Questo presenta il vantaggio di essere completamente personalizzabile, ma richiede la configurazione manuale.

Se non è necessario utilizzare gli allegati, consigliamo di utilizzare le librerie client di Cloud. In caso contrario, consigliamo di utilizzare la libreria API di Google Python.

Utilizzo delle libreria client di Cloud

L'API Cloud Support dispone di librerie client Cloud per:

Per iniziare a utilizzarne uno, vai alla relativa pagina e segui le istruzioni.

Utilizzo della libreria API di Google Python

Per iniziare a utilizzare la libreria Python dell'API Google, segui questi passaggi:

Installa il pacchetto Google Discovery con pip.
```
pip install google-api-python-client
```

Crea uno stub nel tuo codice.

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}",
)

Chiama l'endpoint che ti interessa. Abbiamo fornito alcuni esempi in proposito per ogni endpoint nell'API Cloud Support. Ad esempio, vedi cases.list.

Quando effettui chiamate all'API con la libreria Python dell'API Google, questa utilizzerà le credenziali predefinite per l'ambiente in cui è in esecuzione il tuo programma. Assicurati che l'account di servizio nell'ambiente disponga delle autorizzazioni menzionate nella sezione Guida introduttiva.

Utilizzo di cURL

Esistono due modi principali per autenticare la chiamata cURL. Puoi usare un account di servizio o le credenziali predefinite dell'applicazione. Per scoprire di più sulle credenziali predefinite dell'applicazione, vedi Come funzionano le credenziali predefinite dell'applicazione.

Autenticazione con un account di servizio

Esegui l'autenticazione utilizzando Google Cloud CLI.

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

Invia la richiesta.

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

Autenticazione con le Credenziali predefinite dell'applicazione

Esegui l'autenticazione utilizzando Google Cloud CLI.
```
gcloud auth application-default login
```

Invia la richiesta. Assicurati di includere un'intestazione x-goog-user-project, che è obbligatoria quando chiami l'API Cloud Support con le credenziali predefinite dell'applicazione.

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