Integrazione dell'assistenza

Questa sezione descrive il flusso di lavoro di assistenza quando intendi fornire assistenza come parte del tuo prodotto.

Il tuo sistema deve essere integrato con Google in modo da poter fornire assistenza ai clienti che hanno acquistato i tuoi prodotti tramite Google. L'integrazione si basa su Google per fornirti quanto segue:

  • Una chiave che utilizzerai per verificare l'idoneità all'assistenza degli utenti durante la procedura di registrazione.

  • Un'API (l'API Subscriptions) a cui puoi trasmettere la chiave per sondare periodicamente lo stato dell'idoneità all'assistenza degli utenti.

Ottenere l'ID assistenza dell'utente

L'integrazione con l'assistenza è incentrata su un ID account esterno, che i tuoi utenti vedono come ID assistenza.

Per ottenere l'ID supporto dei tuoi utenti, devi creare un flusso di lavoro per l'assistenza e fornire un URL all'inizio del flusso di lavoro. Google ti invierà quindi l'ID account esterno nell'URL.

Se implementi il flusso di lavoro dell'assistenza, devi accettare l'ID account esterno nell'URL. L'ID account esterno può far parte del percorso dell'URL o come valore parametro di ricerca, come negli esempi seguenti:

# External account ID in path
http://example.com/mysupportpage/{external_account_id}?someparameter=yes

# External account ID as a query parameter
http://example.com/mysupportpage?eid={external_account_id}&something_else

Il testo {external_account_id} nell'URL viene sostituito con l'ID account esterno. Se in Google Cloud Marketplace sono presenti più prodotti, ti consigliamo di includere un parametro di ricerca per identificare il prodotto a cui è destinato l'URL.

Usare l'API Subscriptions

Dopo aver ottenuto l'ID account esterno dell'utente, puoi utilizzare in qualsiasi momento l'API Abbonamenti forniti da Google per verificare l'idoneità dell'assistenza al suo account. L'idoneità viene monitorata controllando la presenza di entità denominate sottoscrizioni.

Ogni abbonamento ha un numero ID univoco e viene creato un abbonamento unico per cliente per ogni prodotto elencato in Cloud Marketplace. In questo modo, puoi anche eseguire query per un abbonamento in base all'ID abbonamento per avere ulteriori dettagli sulla cronologia di un cliente insieme al prodotto, ad esempio la data di inizio e di fine e così via.

Accedere all'API Subscriptions

L'API Subscriptions è un'API non pubblica, pertanto gli sviluppatori e i progetti che richiedono l'accesso devono essere inclusi nella lista consentita.

Per ricevere l'autorizzazione e la configurazione, procedi nel seguente modo:

  1. Invia un elenco di indirizzi email per gli sviluppatori che devono accedere alla documentazione dell'API al tuo Partner Engineer di Google Cloud Marketplace o all'indirizzo cloud-partner-onboarding@google.com. Questi devono essere gli indirizzi email esatti che gli sviluppatori utilizzeranno per accedere a http://console.developers.google.com. Questi sviluppatori saranno aggiunti al gruppo che concede l'autorizzazione per accedere alla documentazione relativa agli abbonamenti.

  2. Invia l'ID progetto del tuo prodotto al Partner Engineer di Google Cloud Marketplace e richiedi l'autorizzazione a chiamare l'API. Se necessario, puoi aggiungere più progetti alla lista consentita.

  3. Per abilitare l'API Cloud Billing, espandi il menu in alto a sinistra nella pagina https://console.developers.google.com e fai clic su API e servizi, quindi cerca e abilita l'API Cloud Billing.

  4. Crea un account di servizio OAuth2 associato al progetto e invia l'indirizzo email per questo account al Partner Engineer di Google Cloud Marketplace. L'utente potrà essere autorizzato a leggere tutti gli abbonamenti per te e verrà autorizzato per tutte le richieste ad eccezione di quelli effettuate richiedendo l'autorizzazione del cliente tramite una finestra di dialogo OAuth.

Poiché non è un'API pubblica, l'API Subscriptions non è inclusa nella libreria client Python per impostazione predefinita. Se prevedi di utilizzare la libreria client Python con questa API, devi anche contattare il tuo Google Partner Engineer per ricevere accesso al file di rilevamento.

Nell'esempio di inizializzazione riportato di seguito, il nome del file di rilevamento è impostato sul percorso in cui è stato scaricato il file di rilevamento.

   # Load the local copy of the discovery document
   f = file(os.path.join(os.path.dirname(__file__),
         "cloudbilling-subscriptions_discovery.json"), "r")
   discovery = f.read()
   f.close()

   # Construct a service from the local documents
   service = build_from_document(discovery,
         base="https://www.googleapis.com/",
         http=http)

La libreria client supporta anche l'autenticazione OAuth, per le credenziali del cliente e per gli account di servizio OAuth2. Per ulteriori informazioni, consulta la documentazione relativa a OAuth 2.0 nella libreria client delle API di Google per Python.

Eseguire query sull'API Subscriptions

Per ottenere l'autorizzazione per accedere ai dati degli abbonamenti, devi creare un account di servizio OAuth2 e indicarci l'account che intendi utilizzare per autorizzare le richieste API. Google concederà a tale account di servizio l'accesso per leggere i tuoi abbonamenti per tutti i clienti. Per ulteriori informazioni, consulta Utilizzo di OAuth 2.0 per applicazioni server-server.

L'API è un'API RESTful di sola lettura che restituisce le risorse di abbonamento che possono essere utilizzate per ottenere le seguenti informazioni:

  • name: un identificatore per una singola risorsa di abbonamento.
  • externalAccountId: identificatore per un singolo account di fatturazione.
  • version: un numero di versione che si aggiorna ogni volta che il record viene modificato. Può essere utilizzata per rilevare facilmente le modifiche dall'ultima lettura.
  • status: uno dei seguenti valori:
    • ATTIVO: l'abbonamento è attualmente attivo e il cliente dovrebbe essere in grado di ricevere assistenza da te. Un abbonamento è considerato attivo se l'account ha una VM attiva negli ultimi 30 giorni.
    • COMPLETE: l'abbonamento non è più attivo, perché il cliente non ha VM attive in esecuzione con il tuo prodotto, e non lo è stato negli ultimi 30 giorni.

  • subscribedResources: elenco delle risorse coperte da questa sottoscrizione.
  • startDate: la data di inizio dell'abbonamento, formattata come stringa nel formato RFC 3339.
  • endDate: la data di scadenza dell'abbonamento (se è terminata), formattata come stringa nel formato RFC 3339.
  • Etichetta per il timestamp dell'ultimo battito cardiaco (con chiave): il valore di questa etichetta indica il timestamp dell'ultimo battito del cuore di qualsiasi VM che esegue il prodotto. Ad esempio: cloudmarketplacepartner.googleapis.com/last_heartbeat_us

Quando un cliente fa clic sul link per accedere al tuo sito da Google Cloud Console, devi verificare che sia autorizzato a utilizzare il link effettuando le seguenti richieste:

  1. Elenca le iscrizioni per l'ID account esterno
  2. Trova l'abbonamento attivo per il prodotto
  3. Ricevere informazioni sull'abbonamento utilizzando l'ID abbonamento

Se il cliente è un utente autorizzato, la richiesta avrà esito positivo. Se il cliente non è un utente autorizzato per l'abbonamento, la chiamata restituisce un codice di errore non autorizzato (HTTP 403).

Per questo motivo, devi richiedere l'autorizzazione del cliente a leggere i dati dei suoi abbonamenti durante la procedura di registrazione, utilizzando un flusso di richiesta OAuth standard.

Le richieste successive di aggiornamento dei dati dell'abbonamento utilizzano l'account di servizio creato in precedenza.

Flusso di registrazione dell'assistenza clienti

Dopo che un cliente ha eseguito il deployment del tuo prodotto tramite Cloud Marketplace o tramite le API Compute Engine, Google Cloud Console mostra loro un link al tuo sito per completare la registrazione per ricevere assistenza. Il link includerà l'ID account esterno da utilizzare per l'account.

Il tuo sito deve consentire al cliente di creare un account e fornire tutte le informazioni di contatto di cui ha bisogno; Google non ti fornirà informazioni personali del cliente. È tua responsabilità gestire una mappatura tra il suo account e l'ID account esterno fornito da Google.