Notifiche push

Panoramica

L'API Reseller utilizza l'API Pub/Sub per inviare notifiche push su diversi eventi di abbonamento di Google Workspace. Ad esempio, puoi configurare le notifiche push per ricevere una notifica quando cambiano gli stati degli abbonamenti dei tuoi clienti.

Prerequisiti

  • Abilita l'API Pub/Sub per il tuo progetto Google Cloud.
  • Concedi i ruoli IAM Pub/Sub al tuo 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 all'API Reseller utilizzando il metodo resellernotify.register. Il metodo resellernotify.register accetta un indirizzo email dell'account di servizio come parametro. Solo gli account di servizio autorizzati da questo metodo possono iscriversi al 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 altri account di servizio a utilizzare il tuo argomento, puoi chiamare nuovamenteresellernotify.register.

Revocare l'accesso per un account di servizio

L'API Reseller offre anche la possibilità 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"
}

Iscriversi a un argomento

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

  • Abbonamento push: fornisci un callback HTTP POST. Pub/Sub utilizza questo callback per notificare alla tua applicazione i nuovi eventi.
  • Abbonamento pull: l'applicazione effettua periodicamente una chiamata HTTP per recuperare tutte le modifiche in coda.

Di seguito è riportato un esempio di richiesta di iscrizione 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: un nome che identifica il tuo abbonamento.
  • TOPIC_NAME: l'argomento Pub/Sub creato in precedenza.
  • PUSH_NOTIFICATION_ENDPOINT: l'endpoint del gestore delle notifiche push.

Una risposta positiva restituisce un codice di stato HTTP 200. Di seguito è riportato un esempio di risposta: 

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

Formati 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": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Di seguito è riportato l'esempio di oggetto message.data 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

L'elenco seguente contiene tutti i possibili tipi di eventi:

  • NEW_SUBSCRIPTION_CREATED: è stato creato un nuovo abbonamento.
  • SUBSCRIPTION_TRIAL_ENDED: la prova di un abbonamento è terminata.
  • 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 con impegno a un piano flessibile nell'ambito di un rinnovo.
  • COMMITMENT_CHANGED: l'impegno annuale è aumentato o diminuito.
  • SUBSCRIPTION_RENEWED: è stato rinnovato un abbonamento annuale.
  • SUBSCRIPTION_SUSPENDED: l'abbonamento è sospeso. Consulta il campo subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: la sospensione è stata revocata per un abbonamento precedentemente sospeso.
  • SUBSCRIPTION_CANCELLED: l'abbonamento è stato annullato. Consulta 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:

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

  • SUBSCRIPTION_UPGRADE: è stato eseguito l'upgrade dello SKU dell'abbonamento. Ad esempio, l'upgrade dell'abbonamento è stato eseguito 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 a un utente. Puoi utilizzare questo evento per monitorare in modo reattivo le modifiche al numero di posti per gli abbonamenti flessibili.

Motivi dell'annullamento degli abbonamenti

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

  • TRANSFERRED_OUT: il cliente ha eseguito il trasferimento alla fatturazione diretta o a un altro rivenditore.
  • PURCHASE_OF_SUBSUMING_SKU: il cliente ha eseguito l'upgrade a uno SKU che supera 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 incorporato perché è incluso in Google Workspace Business Plus.
  • RESELLER_INITIATED: il rivenditore ha annullato l'abbonamento.
  • OTHER: l'abbonamento è stato annullato per un motivo diverso da quelli elencati.

Motivi della sospensione dell'abbonamento

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

  • PENDING_TOS_ACCEPTANCE: il cliente non ha eseguito l'accesso e non ha accettato i Termini di servizio di Google Workspace rivenduto.
  • 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 senza prova.
  • OTHER: il cliente è stato sospeso per un motivo interno di Google, ad esempio per abuso.

Limitazioni di Pub/Sub

L'ordine delle notifiche push non è garantito. I messaggi potrebbero essere recapitati più volte e, in situazioni estreme, potrebbero non essere recapitati affatto. Ti consigliamo di utilizzare reseller.subscriptions.get su tutti gli abbonamenti modificati per recuperare lo stato corrente.