Notifiche Pub/Sub

  • Assicurati di completare il codelab per la configurazione delle API per configurare un progetto Google Cloud e creare un account di servizio per chiamare l'API Cloud Channel.

  • Per questo codelab, consigliamo di utilizzare la console Channel Services.

  • Impara a conoscere i concetti di Pub/Sub.

Panoramica

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

Questa procedura è particolarmente utile per:

  • Rifletti sulle modifiche apportate direttamente nella Console Channel Services nei tuoi sistemi (ad esempio, un membro del team di assistenza annulla un diritto di Google Workspace).
  • Rileva gli eventi critici attivati dai clienti del rivenditore. Ad esempio:
    • Un cliente Google Workspace che accetta i Termini di servizio.
    • Un cliente Google Workspace verifica il dominio.
    • Un cliente Google Workspace che aggiunge utenti a un diritto flessibile.
    • Un cliente Google Workspace è in fase di trasferimento.

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

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

  2. Crea un argomento Pub/Sub. Questo argomento è di proprietà dei servizi del canale e devi specificare un account di servizio che può creare un abbonamento.

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

Per una sottoscrizione push, ospiti un webhook che riceve gli eventi emessi dai servizi Channel:

Notifiche push per Channel Services

Formato delle notifiche

Di seguito è riportata una notifica di Pub/Sub di esempio. I dati dei messaggi vengono trasmessi come una 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"
}

Gli stessi dati del messaggio sono decodificati:

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

Passaggio 1: abilita l'API Pub/Sub e prepara il tuo account di servizio

Per eseguire questo codelab è necessario quanto segue:

  • L'indirizzo email di un account di servizio del progetto. Questo indirizzo sarà simile a: service-account@project.iam.gserviceaccount.com.
  • Accesso a un account di super amministratore di un dominio di rivenditore (preferibilmente la tua Console Channel Services).
  • Il tuo ID account. Puoi trovarlo nelle Impostazioni della Console Channel Services.

Per preparare l'account di servizio:

  • Accedi alla sezione Libreria API in Google Cloud Console e abilita l'API Pub/Sub.
  • Concedi il ruolo IAM/Sub sul progetto al tuo account di servizio. Concedere roles/pubsub.editor è una buona opzione a questo scopo di questo codelab, ma è possibile utilizzare privilegi più dettagliati nell'integrazione in produzione. Puoi trovare i riferimenti completi nella pagina Controllo accesso Pub/Sub.

Passaggio 2: crea l'argomento per il tuo account

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

  1. Vai alla documentazione 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 i parametri del corpo della richiesta, seleziona serviceAccount e inserisci l'indirizzo email dell'account di servizio.
  4. Fai clic su Esegui e assicurati di accedere come super amministratore del dominio del rivenditore.

Dovresti ricevere 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 impostare la modalità di modifica degli eventi di modifica dell'applicazione. Sono disponibili due opzioni:

  • Abbonamento push: fornisci un callback HTTP POST. Pub/Sub utilizzerà questa notifica per informare la tua applicazione dei nuovi eventi.
  • Abbonamento Pull: l'applicazione effettua periodicamente richieste HTTP per ottenere modifiche alla coda.

In questo codelab, utilizzeremo Push e invieremo tutti gli eventi a una funzione Cloud che eseguirà l'accesso a Cloud Logging.

Trasferimento delle notifiche di Channel Services a una funzione Cloud

Passaggio 3a: crea una funzione Cloud

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

  1. Vai alla sezione Cloud Functions di Google Cloud Console. Potresti dover attivare l'API Cloud Functions.
  2. Fai clic su Crea funzione.
  3. Nella schermata Configurazione:
    1. Modifica il nome della funzione. (Facoltativo) Scegli un'area geografica diversa.
    2. Nel trigger HTTP, modifica Autenticazione in 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 qualsiasi runtime Node.js
    2. Cambia il punto di ingresso in log
    3. Nel file index.js, sostituisci il codice di esempio 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 al passaggio successivo mentre viene eseguito il deployment della funzione Cloud.

Passaggio 3b: crea l'abbonamento

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

Puoi eseguire questa operazione usando il codice chiamando l'API Pub/Sub con le credenziali dell'account di servizio. Assicurati di non impersonare il super amministratore del tuo dominio del rivenditore, necessario quando chiami l'API Cloud Channel.

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

  1. Fai clic su Attiva Cloud Shell nella parte superiore di Google Cloud Console.

  2. Una volta che 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 trigger del cloud Funzione 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
    
  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 controllare l'abbonamento configurato nella sezione Abbonamenti Pub/Sub.

Generare alcuni dati

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

Il modo più semplice è creare un cliente nella Console Channel Services ed eseguire il provisioning di un prodotto. Se hai terminato il codelab per il provisioning dell'area di lavoro end-to-end puoi creare un cliente con un'area di lavoro Google eseguendo il codice di esempio.

Vai alla funzione in Google Cloud Console e apri la scheda Log. Il seguente è un esempio di ciò che dovresti vedere.

Log di esempio per gli eventi Pub/Sub

Esegui la pulizia

  • Eliminazione funzione Cloud
  • Elimina l'abbonamento

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

Passaggi successivi

Questo codelab ti ha aiutato a scoprire in che modo Channel Services utilizza Pub/Sub per creare l'integrazione in modo reattivo e su larga scala.

Riferimento evento

Consulta il riferimento RPC per l'elenco di eventi generati dai servizi Channel.

Riferimento API

Questo codelab si avvale di Google Cloud Console, ma puoi eseguire questi passaggi a livello di programmazione. Ecco come fare:

Garanzie e best practice per 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 pubblicati più volte.

Best practice per l'endpoint push:

  • Poiché i messaggi potrebbero subire un ritardo, essere consegnati non inviati o inviati più volte, il tuo punto di vista dovrebbe essere enumerato e utilizzare customers.get e entitlements.get

  • Mentre il timeout predefinito di Pub/Sub per il push è di 10 secondi (può essere aumentato tramite l'abbonamento ackDeadline / Pub/Sub), ti consigliamo di utilizzare un'architettura basata su messaggi e creare l'endpoint risponde il più rapidamente possibile.

  • Se l'endpoint non è attivo o restituisce errori 5xx, Pub/Sub proverà nuovamente. Puoi trovare ulteriori informazioni su come ricevere i 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 di eventi

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

Ad esempio, l'applicazione di filtri con attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" consente di monitorare tutte le modifiche ai posti dell'area di lavoro di Google.