Notifiche Pub/Sub

Assicurati di completare il codelab di configurazione dell'API per configurare un progetto Google Cloud e creare un account di servizio per chiamare l'API Cloud Channel.
Ti consigliamo di utilizzare la Test Partner Sales Console per questo codelab.
Acquisisci familiarità con i concetti di Pub/Sub.

Panoramica

L'API Cloud Channel utilizza Pub/Sub per inviare notifiche su vari eventi relativi a clienti e diritti.

Ciò è particolarmente utile per:

Riflettere le modifiche apportate direttamente nella Partner Sales Console nei tuoi sistemi (ad esempio, un membro del tuo team di assistenza che annulla un diritto Google Workspace).
Rileva gli eventi critici che vengono attivati dai clienti del rivenditore. Ad esempio:
- Un cliente Google Workspace che accetta i Termini di servizio.
- Un cliente di Google Workspace che verifica il proprio dominio.
- Un cliente di Google Workspace che aggiunge utenti a un diritto flessibile.
- Un cliente di Google Workspace che sta per abbandonarlo.

La configurazione di Pub/Sub prevede tre passaggi:

Abilita l'API Pub/Sub e prepara il tuo account di servizio.
Creare un argomento Pub/Sub. Questo argomento è di proprietà di Channel Services e dovrai specificare un account di servizio che può creare un abbonamento.
Crea una sottoscrizione Pub/Sub. Questo abbonamento può essere push utilizzando i webhook (il metodo preferito) o pull.

Per un abbonamento push, dovrai ospitare un webhook che riceve gli eventi emessi da Channel Services:

Notifiche push per Channel Services

Formato delle notifiche

Di seguito è riportata una notifica Pub/Sub di esempio. I dati dei messaggi vengono trasmessi come stringa JSON con codifica base64.

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

Questi sono gli stessi dati dei messaggi, decodificati:

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

Passaggio 1: attiva l'API Pub/Sub e prepara l'account di servizio

Per eseguire questo codelab, sono necessari quanto segue:

L'indirizzo email di un account di servizio nel progetto. Questo indirizzo sarà simile a: service-account@project.iam.gserviceaccount.com.
Accesso a un account super amministratore del dominio del rivenditore (preferibilmente la tua Console Partner di test).
ID del tuo account. Lo puoi trovare nelle impostazioni della tua Partner Sales Console.

Per preparare l'account di servizio:

Vai alla sezione Libreria API nella console Google Cloud e abilita l'API Pub/Sub.
Concedi al tuo account di servizio il ruolo IAM Pub/Sub sul progetto. La concessione di roles/pubsub.editor (nome del ruolo = "Editor Pub/Sub") è sufficiente per questo codelab, ma ti consigliamo di utilizzare privilegi più granulari nell'integrazione di produzione. Puoi trovare i dettagli completi del ruolo IAM nella pagina Controllo dell'accesso Pub/Sub.
Se scegli di applicare un ruolo personalizzato, devi concedere a quel ruolo l'autorizzazione pubsub.subscriptions.create per creare sottoscrizioni.

Potrebbe verificarsi un ritardo dopo l'applicazione di questi ruoli e autorizzazioni al tuo account.

Passaggio 2: crea l'argomento per il tuo account

Per creare l'argomento Pub/Sub, devi utilizzare il metodo accounts.register. Questo metodo richiede l'indirizzo email di un account di servizio come parametro. Solo gli account di servizio autorizzati tramite questo metodo possono abbonarsi al nuovo argomento.

Vai alla documentazione su accounts.register e fai clic su Prova!.
Nel campo account, inserisci accounts/ACCOUNT_ID, sostituendo ACCOUNT_ID con il tuo ID account.
Fai clic su Aggiungi parametri per il corpo della richiesta, seleziona serviceAccount e inserisci l'indirizzo email del tuo account di servizio.
Fai clic su Esegui e assicurati di accedere come super amministratore del tuo dominio di rivenditore.

Dovresti ottenere una risposta 200 simile alla seguente:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

Questo è l'argomento Pub/Sub in cui verranno pubblicati gli eventi.

Passaggio 3: iscriviti all'argomento

Dopo aver creato l'argomento Pub/Sub, devi configurare il modo in cui l'applicazione utilizza gli eventi di modifica. Puoi scegliere tra due opzioni:

Push sottoscrizione: devi fornire un callback HTTP POST. Pub/Sub lo userà per notificare la tua applicazione ai nuovi eventi.
Abbonamento pull: l'applicazione effettua periodicamente chiamate HTTP per ricevere le modifiche in coda.

In questo codelab, utilizzeremo Push e invieremo tutti gli eventi a una Cloud Function che registrerà in Cloud Logging.

Invio delle notifiche di Channel Services a una Cloud Function

Passaggio 3a: crea una Cloud Function

In questo passaggio, creeremo una Cloud Function che registrerà i messaggi ricevuti.

Vai alla sezione Cloud Functions della console Google Cloud. Potresti dover abilitare l'API Cloud Functions.
Fai clic su Crea funzione.
Nella schermata Configurazione:
1. Modifica il nome della funzione. Se vuoi, scegli un'altra regione.
2. Nel trigger HTTP, cambia Autenticazione in Consenti chiamate non autenticate e fai clic su Salva.
3. Tieni presente l'URL attivatore. Ti servirà nel passaggio successivo.
4. Tocca Avanti.

Nella schermata Codice:

Scegli qualsiasi runtime Node.js
Modifica il Punto di ingresso in log
Nel file index.js, sostituisci il codice campione con:

exports.log = (req, res) => {
  if (req.body && req.body.message) {
    console.log(req.body);
    const message = req.body.message;
    // data is base64-encoded JSON
    const data = new Buffer.from(message.data, 'base64').toString();
    console.log(data);
  }
  res.status(200).send('OK');
};

Puoi procedere con il passaggio successivo durante il deployment della Cloud Function.

Passaggio 3b: crea la sottoscrizione

Solo gli account di servizio che sono stati registrati per l'argomento Channel Services (vedi il passaggio 2) possono creare un abbonamento.

Puoi farlo usando il codice chiamando l'API Pub/Sub con le credenziali del tuo account di servizio. Assicurati di non impersonare il super amministratore del tuo dominio rivenditore, che è obbligatorio per le chiamate all'API Cloud Channel.

Ai fini di questo codelab, utilizzerai lo strumento gcloud CLI su Cloud Shell.

Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
Quando la shell è pronta, esegui il comando seguente. Sostituisci i valori SERVICE_ACCOUNT con l'indirizzo email del tuo account di servizio, TOPIC con l'argomento creato nel passaggio 2 e PUSH_ENDPOINT con l'URL di trigger della funzione Cloud Function creata nel passaggio 3a:
```
SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
```

Attiva l'account di servizio nella shell:

gcloud iam service-accounts keys create sa-keys.json \
    --iam-account=$SERVICE_ACCOUNT
gcloud auth activate-service-account --key-file=sa-keys.json

Crea la sottoscrizione:

gcloud pubsub subscriptions create channel-pubsub-test \
    --topic=$TOPIC \
    --push-endpoint=$PUSH_ENDPOINT

Puoi verificare che l'abbonamento sia stato configurato nella sezione Abbonamenti di Pub/Sub.

Genera alcuni dati

Dopo aver completato i passaggi precedenti, potrai ricevere i dati.

Il modo più semplice è creare un cliente nella tua Partner Sales Console e eseguire il provisioning di un prodotto. Se hai completato il codelab sul provisioning end-to-end di Workspace, puoi creare un cliente con Google Workspace eseguendo il codice di esempio.

Vai alla funzione nella console Google Cloud e apri la scheda Log. Di seguito è riportato un esempio di ciò che dovresti vedere.

Log di esempio per eventi Pub/Sub

Esegui la pulizia

Elimina la Cloud Function
Elimina la sottoscrizione

L'argomento verrà pulito automaticamente quando non ha altri iscritti.

Passaggi successivi

Questo codelab ti ha aiutato a scoprire in che modo Channel Services sfrutta Pub/Sub per consentirti di creare la tua integrazione in modo reattivo e su larga scala.

Riferimento evento

Consulta il riferimento RPC per l'elenco degli eventi generati da Channel Services.

Riferimento API

Questo codelab utilizza la console Google Cloud, ma puoi eseguire questi passaggi in modo programmatico. Ecco come fare:

Utilizza accounts.register per creare l'argomento.
Utilizza l'API Pub/Sub subscriptions.create per creare la sottoscrizione Pub/Sub.
Consulta accounts.listSubscribers e accounts.unregister per ulteriori endpoint da utilizzare nell'integrazione.

Garanzie e best practice di Pub/Sub

Il ritardo tra un evento e la relativa notifica non è garantito. Analogamente, l'ordinamento delle notifiche non è garantito. Infine, i messaggi possono essere recapitati più volte.

Best practice per gli endpoint push:

Poiché i messaggi potrebbero subire ritardi, essere inviati fuori ordine o inviati più volte, il tuo endpoint dovrebbe essere idempotente e utilizzare customers.get e entitlements.get
Sebbene il timeout Pub/Sub predefinito per il push è 10 secondi (può essere aumentato tramite il valore ackDeadline della sottoscrizione Pub/Sub), è consigliabile utilizzare un'architettura basata su messaggi e fare in modo che l'endpoint risponda il più rapidamente possibile.
Se l'endpoint non è attivo o restituisce errori 5xx, Pub/Sub riproverà. Puoi trovare ulteriori informazioni su come ricevere messaggi tramite push nella documentazione di Pub/Sub.

Se preferisci utilizzare pull, puoi trovare informazioni su come ricevere messaggi tramite pull nella documentazione di Pub/Sub.

Filtro eventi

Poiché le notifiche di Channel Services includono attributes, puoi creare sottoscrizioni granulari creando abbonamenti Pub/Sub specifici con il filtro Pub/Sub.

Ad esempio, il filtro con attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" ti consente di tenere traccia di tutti i cambi di utenze in Google Workspace.