Notifiche push

Panoramica

L'API Reseller utilizza l'API Pub/Sub per inviare notifiche push sui diversi eventi di abbonamento di Google Workspace. Ad esempio, puoi impostare le notifiche push per ricevere notifiche quando lo stato degli abbonamenti dei tuoi clienti cambia.

Prerequisiti

  • Abilitare l'API Pub/Sub per il tuo progetto Google Cloud.
  • Concedi i ruoli IAM Pub/Sub all'account di servizio nel progetto Cloud. La concessione del ruolo roles/pubsub.editor è un buon compromesso (facile e non troppo ampio), ma ti consigliamo di utilizzare autorizzazioni Pub/Sub più specifiche.

crea un argomento

Per creare un argomento, devi registrarti con l'API dei rivenditori utilizzando il metodo resellernotify.register. Il metodo resellernotify.register utilizza un indirizzo email dell'account di servizio come parametro. Solo gli account di servizio autorizzati da questo metodo possono sottoscrivere un argomento appena creato.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Una risposta corretta restituisce un codice di stato HTTP 200 e una risposta JSON contenente il nome dell'argomento Pub/Sub.

Di seguito è riportato un esempio di risposta:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Per autorizzare account di servizio aggiuntivi a utilizzare l'argomento, puoi chiamare di nuovo resellernotify.register.

Revocare l'accesso per un account di servizio

L'API Reseller consente anche di annullare la registrazione degli account di servizio utilizzando l'endpoint resellernotify.unregister:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Iscriviti a un argomento

Dopo aver creato l'argomento Pub/Sub, devi configurare il modo in cui l'applicazione utilizza gli eventi di modifica. Scegli una delle seguenti opzioni:

  • Push abbonamento: devi fornire un callback HTTP POST. Pub/Sub usa questo callback per notificare l'applicazione ai nuovi eventi.
  • Abbonamento pull: l'applicazione periodicamente effettua una chiamata HTTP per ricevere tutte le modifiche in coda.

Di seguito è riportato un esempio di richiesta di sottoscrizione a un argomento:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Sostituisci quanto segue:

  • PROJECT: il tuo progetto Google Cloud.
  • SUBSCRIPTION_NAME: il nome che identifica l'abbonamento.
  • TOPIC_NAME: l'argomento Pub/Sub creato in precedenza.
  • PUSH_NOTIFICATION_ENDPOINT: l'endpoint del gestore delle notifiche push.

Una risposta corretta restituisce un codice di stato HTTP 200. Ecco un esempio di risposta:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Formati di notifica

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

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Di seguito è riportato l'oggetto message.data di esempio dopo la decodifica:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Tipi di eventi

Il seguente elenco contiene tutti i possibili tipi di evento:

  • NEW_SUBSCRIPTION_CREATED: è stato creato un nuovo abbonamento.
  • SUBSCRIPTION_TRIAL_ENDED: il periodo di prova di un abbonamento è terminato.
  • PRICE_PLAN_SWITCHED: il cliente è passato da un piano flessibile a un piano annuale. Questo evento non viene attivato se il cliente passa da un piano basato su impegno a un piano flessibile nell'ambito di un rinnovo.
  • COMMITMENT_CHANGED: l'impegno annuale è stato aumentato o diminuito.
  • SUBSCRIPTION_RENEWED: un abbonamento annuale è stato rinnovato.
  • SUBSCRIPTION_SUSPENDED: abbonamento sospeso. Controlla il campo subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: la sospensione è stata revocata per un abbonamento precedentemente sospeso.
  • SUBSCRIPTION_CANCELLED: l'abbonamento è stato annullato. Controlla il campo subscription_cancellation_reason. Può essere utilizzato anche per rilevare i trasferimenti.

  • SUBSCRIPTION_CONVERTED: l'abbonamento è stato convertito. Ecco alcuni casi di esempio per questo evento:

    • Converti l'abbonamento diretto in abbonamento del rivenditore.
    • Converti l'abbonamento a pagamento in un'offerta di tolleranza.
    • Converti l'abbonamento online in abbonamento offline.

  • SUBSCRIPTION_UPGRADE: è stato eseguito l'upgrade dello SKU dell'abbonamento. Ad esempio, è stato eseguito l'upgrade dell'abbonamento da Google Workspace Business Starter a Business Standard.

  • SUBSCRIPTION_DOWNGRADE: è stato eseguito il downgrade dello SKU dell'abbonamento. Ad esempio, è stato eseguito il downgrade dell'abbonamento da Google Workspace Business Standard a Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: la licenza è stata assegnata o revocata da un utente. Puoi utilizzare questo evento per monitorare in modo reattivo le variazioni del numero di utenze per gli abbonamenti flessibili.

Motivi dell'annullamento dell'abbonamento

Il motivo dell'annullamento dell'abbonamento viene compilato quando event_type è SUBSCRIPTION_CANCELLED. Di seguito sono riportati i possibili motivi dell'annullamento:

  • TRANSFERRED_OUT: il cliente è passato alla fatturazione diretta o a un altro rivenditore.
  • PURCHASE_OF_SUBSUMING_SKU: il cliente ha eseguito l'upgrade a uno SKU che sostituisce un altro. Ad esempio, se un cliente con Google Workspace Business Starter e Google Vault esegue l'upgrade a Google Workspace Business Plus, l'abbonamento a Vault viene incluso in quanto incluso in Google Workspace Business Plus.
  • RESELLER_INITIATED: il rivenditore ha annullato l'abbonamento.
  • OTHER: l'abbonamento è stato annullato per un motivo diverso da quello indicato.

Motivi della sospensione dell'abbonamento

Il motivo della sospensione dell'abbonamento viene compilato quando event_type è SUBSCRIPTION_SUSPENDED. Di seguito sono riportati i possibili motivi di sospensione:

  • PENDING_TOS_ACCEPTANCE: il cliente non ha eseguito l'accesso e non ha accettato i Termini di servizio del rivenditore Google Workspace.
  • RENEWAL_WITH_TYPE_CANCEL: l'impegno del cliente è terminato e il servizio è stato annullato al termine del periodo di validità.
  • RESELLER_INITIATED: il rivenditore ha sospeso manualmente l'abbonamento.
  • TRIAL_ENDED: la prova del cliente è scaduta e il cliente non ha selezionato un piano non di prova.
  • OTHER: il cliente è stato sospeso per un motivo interno di Google, ad esempio per abuso.

Limitazioni di Pub/Sub

L'ordinamento delle notifiche push non è garantito. I messaggi possono essere recapitati più volte e in situazioni estreme, per niente. Ti consigliamo di utilizzare reseller.subscriptions.get su tutte le sottoscrizioni modificate per eseguire il pull dello stato attuale.