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.

• Per questo codelab, ti consigliamo di utilizzare la Test Partner Sales Console.

• Acquisisci familiarità con Pub/Sub concetti.

Panoramica

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

Ciò è particolarmente utile per:

• Rifletti le modifiche apportate direttamente nella Partner Sales Console nei tuoi sistemi operativi (ad esempio, un utente del team di assistenza che annulla diritto Google Workspace).
• Rileva gli eventi critici attivati dai clienti del rivenditore. Per esempio:
  • Un cliente Google Workspace che accetta i Termini di servizio.
  • Un cliente di Google Workspace che verifica il proprio dominio.
  • Un cliente Google Workspace che aggiunge utenti con un diritto flessibile.
  • Un cliente di Google Workspace sta per essere 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 specificherai un account di servizio che può creare un abbonamento.

3. Creare una sottoscrizione Pub/Sub. Questo abbonamento può essere push mediante 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 dei messaggi sono una stringa JSON codificata in 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: abilita l'API Pub/Sub e prepara l'account di servizio

Per eseguire questo codelab, ti occorrono:

• L'indirizzo email di un account di servizio nel tuo progetto. L'indirizzo sarà simile a: [e-mail].
• Accesso a un account di super amministratore del dominio rivenditore (preferibilmente il tuo Testare Partner Sales Console).
• Il tuo ID account. Puoi trovarlo nelle Impostazioni del tuo 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. È sufficiente concedere roles/pubsub.editor (nome ruolo = "Editor Pub/Sub") per questo codelab, ma ti consigliamo di usare privilegi più granulari per l'integrazione in produzione. Puoi trovare i dettagli completi dei ruoli IAM nella pagina Controllo dell'accesso Pub/Sub.
• Se invece scegli di applicare un ruolo personalizzato, devi concedere a quel ruolo pubsub.subscriptions.create autorizzazione 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 comando accounts.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 sezione accounts.register documentazione 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 e assicurati di accedere come super amministratore del tuo rivenditore. dominio.

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.

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 consuma eventi di modifica. Sono disponibili due opzioni:

• Sottoscrizione push: devi fornire un callback POST HTTP. Pub/Sub utilizzalo per notificare nuovi eventi alla tua applicazione.
• Sottoscrizione pull: l'applicazione effettua periodicamente chiamate HTTP per ricevere modifiche in coda.

In questo codelab, utilizzeremo il comando push e invieremo tutti gli eventi a un funzione Cloud Run che registra Cloud Logging.

Passaggio 3a: crea una funzione Cloud Run

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

1. Vai alla sezione nella sezione Funzioni di Cloud Run della nella 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 una regione diversa.
   2. Nell'attivatore HTTP, imposta Autenticazione su Consenti chiamate non autenticate e fai clic su Salva.
   3. Prendi nota dell'URL attivatore. 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 che sono stati registrati per l'argomento Channel Services (vedi il passaggio 2) per creare un abbonamento.

Puoi farlo con il codice chiamando l'API Pub/Sub con il tuo servizio le credenziali dell'account. Assicurati di non rubare l'identità del tuo dominio di rivenditore Super amministratore, obbligatorio quando si chiama 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. Quando la shell è pronta, esegui questo 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 trigger della funzione Cloud Run creato 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 la sottoscrizione:

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

Puoi verificare se l'abbonamento è configurato andando al 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 terminato codelab sul provisioning end-to-end di Workspace puoi creare un cliente con Google Workspace eseguendo l'esempio le API nel tuo codice.

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

Nota: in rari casi, potrebbero essere necessari alcuni minuti prima che Pub/Sub per iniziare a ricevere eventi dall'argomento.

Esegui la pulizia

• Elimina la funzione Cloud Run
• Elimina la sottoscrizione

L'argomento verrà ripulito automaticamente quando non sono presenti abbonati rimanenti.

Passaggi successivi

Questo codelab ti ha mostrato come utilizzare Channel Services 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 queste in modo programmatico. 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 da usare nell'integrazione.

Garanzie e best practice di Pub/Sub

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

Best practice per gli endpoint per il push:

• Poiché i messaggi possono subire ritardi, essere inviati in ordine non corretto o essere inviati più volte, dovrebbe essere idempotente e usare customers.get e entitlements.get

• Il timeout predefinito di Pub/Sub per il push è 10 secondi (può essere aumentato tramite il modulo ackDeadline), è consigliabile utilizzare un'architettura basata su messaggi e rendere l'endpoint risponde il più velocemente possibile.

• Se il tuo endpoint non è attivo o restituisce errori 5xx, Pub/Sub riprova. Puoi trovare ulteriori informazioni su come ricevere messaggi tramite push nella documentazione di Pub/Sub.

Se preferisci usare il comando pull, puoi trovare informazioni su come ricevere messaggi mediante il pull nella documentazione di Pub/Sub.

Filtro degli eventi

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

Ad esempio, l'applicazione di filtri con attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" ti consente di monitorare tutti Modifiche alle utenze per Google Workspace.