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 Partner Sales Console di test 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.

Questa opzione è particolarmente utile per:

• Riflettere le modifiche apportate direttamente nella Partner Sales Console nei tuoi sistemi (ad esempio, un membro del team di assistenza che annulla un diritto di Google Workspace).
• Rileva gli eventi critici attivati dai clienti a cui vendi i tuoi prodotti. Ad esempio:
  • Un cliente Google Workspace che accetta i Termini di servizio.
  • Un cliente Google Workspace che verifica il proprio dominio.
  • Un cliente Google Workspace che aggiunge utenti con un diritto flessibile.
  • Un cliente Google Workspace che viene trasferito.

La configurazione di Pub/Sub prevede i seguenti tre passaggi:

1. Attiva l'API Pub/Sub e prepara il tuo account di servizio.

2. Creare un argomento Pub/Sub. Questo argomento è di proprietà di Channel Services e dovrai specificare un account di servizio che possa creare un abbonamento.

3. Crea una sottoscrizione Pub/Sub. Questa sottoscrizione può essere push utilizzando gli webhook (il metodo preferito) o pull.

Per una sottoscrizione push, devi ospitare un webhook che riceva gli eventi emessi dai servizi di canale:

Formato delle notifiche

Di seguito è riportato un esempio di notifica Pub/Sub. I dati del messaggio 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"
}

Si tratta degli stessi dati del messaggio, 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, devi disporre di quanto segue:

• L'indirizzo email di un account di servizio nel tuo progetto. L'indirizzo sarà simile al seguente: [e-mail].
• Accesso a un account super amministratore del dominio del rivenditore (preferibilmente la Console Partner Sales di test).
• Il tuo ID account. Puoi trovarlo nelle impostazioni della Partner Sales Console.

Per preparare l'account di servizio:

• Vai alla sezione Libreria API nella console Google Cloud e attiva l'API Pub/Sub.
• Concedi al tuo account di servizio il ruolo IAM Pub/Sub nel progetto. La concessione del ruolo 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 dei ruoli IAM nella pagina Controllo dell'accesso Pub/Sub.
• Se scegli di applicare un ruolo personalizzato, devi concedere a quel ruolo l'autorizzazionepubsub.subscriptions.create per creare sottoscrizioni.

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

Attenzione: riceverai errori 403 se non sono presenti ruoli IAM nell'account di servizio.

Passaggio 2: crea l'argomento per il tuo account

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

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

Dovresti ricevere una risposta 200 simile alla seguente:

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

Si tratta dell'argomento Pub/Sub in cui verranno pubblicati gli eventi.

Nota: questo valore è necessario nel passaggio 3b.

Passaggio 3: iscriviti all'argomento

Dopo aver creato l'argomento Pub/Sub, devi configurare il modo in cui l'applicazione consumerà gli eventi di modifica. Sono disponibili due opzioni:

• Abbonamento push: fornisci un callback POST HTTP. Pub/Sub lo utilizzerà per notificare alla tua applicazione i 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 funzione Cloud Run che registrerà in Cloud Logging.

Passaggio 3a: crea una funzione Cloud Run

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

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

4. Nella schermata Codice:

   1. Scegli un runtime Node.js
   2. Modifica Punto di ingresso in log
   3. 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 funzione Cloud Run.

Passaggio 3b: crea l'abbonamento

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

Puoi farlo con il codice chiamando l'API Pub/Sub con le credenziali del tuo account di servizio. Assicurati di non rubare l'identità del super amministratore del dominio del rivenditore, che è obbligatoria quando chiami l'API Cloud Channel.

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

1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

2. Una volta che la shell è pronta, esegui il seguente comando. Sostituisci i valori di 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 attivazione della funzione Cloud Run creata nel passaggio 3a:

   SERVICE_ACCOUNT=[e-mail]
   TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
   PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
   

3. 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
   

4. Crea l'abbonamento:

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

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

Genera alcuni dati

Dopo aver completato i passaggi precedenti, puoi iniziare a ricevere i dati.

Il modo più semplice è creare un cliente nella Partner Sales Console e eseguire il provisioning di un prodotto. Se hai completato il codelab di provisioning di Workspace end-to-end puoi creare un cliente con un account 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.

Nota: in rari casi, l'abbonamento Pub/Sub può richiedere alcuni minuti per iniziare a ricevere eventi dall'argomento.

Esegui la pulizia

• Elimina la funzione Cloud Run
• Eliminare l'abbonamento

L'argomento verrà ripulito automaticamente quando non avrà più abbonati.

Passaggi successivi

In questo codelab hai scoperto in che modo Channel Services sfrutta Pub/Sub per consentirti di creare l'integrazione in modo reattivo e su larga scala.

Riferimento evento

Consulta la documentazione di 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 tramite programmazione. Ecco come fare:

• Utilizza accounts.register per creare l'argomento.
• Utilizza le API Pub/Sub subscriptions.create per creare l'abbonamento Pub/Sub.
• Consulta accounts.listSubscribers e accounts.unregister per altri endpoint che puoi utilizzare nell'integrazione.

Garanzie e best practice di Pub/Sub

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

Best practice per gli endpoint push:

• Poiché i messaggi potrebbero essere in ritardo, inviati fuori sequenza o più volte, il tuo endpoint deve essere idempotente e utilizzare customers.get e entitlements.get.

• Sebbene il timeout Pub/Sub predefinito per il push sia di 10 secondi (questo valore può essere aumentato tramite il valore ackDeadline dell'abbonamento 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 è disponibile o restituisce errori 5xx, Pub/Sub tenterà di nuovo. Puoi trovare ulteriori informazioni su come ricevere messaggi tramite push nella documentazione di Pub/Sub.

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

Filtro eventi

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

Ad esempio, filtrare con attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" ti consente di monitorare tutte le modifiche ai posti di Google Workspace.