Notifiche push

Panoramica

L'API Reseller utilizza l'API Pub/Sub per inviare notifiche push su diversi eventi di abbonamento Google Workspace. Ad esempio, puoi configurare le notifiche push per ricevere una notifica quando lo stato dell'abbonamento dei tuoi clienti cambia.

Prerequisiti

  • Abilita l'API Pub/Sub per il tuo progetto Google Cloud.
  • Concedi i ruoli IAM Pub/Sub al service account nel tuo progetto Cloud. La concessione del ruolo roles/pubsub.editor è un buon compromesso (facile e non troppo ampio), ma potresti voler 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 del service account come parametro. Solo i service account autorizzati con questo metodo possono iscriversi all'argomento che hai appena creato.

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

Una risposta riuscita 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 service account a utilizzare l'argomento, puoi chiamare di nuovo resellernotify.register.

Revocare l'accesso per un service account

L'API Reseller offre anche la possibilità di annullare la registrazione dei service account 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 la tua applicazione utilizza 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.
  • Sottoscrizione pull: la tua applicazione effettua periodicamente una chiamata HTTP per recuperare tutte le modifiche in coda.

Di seguito è riportata una richiesta di esempio per iscriversi 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 identificativo per l'abbonamento.
  • TOPIC_NAME: l'argomento Pub/Sub che hai creato in precedenza.
  • PUSH_NOTIFICATION_ENDPOINT: l'endpoint del gestore di notifiche push.

Una risposta riuscita 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'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 tipi di eventi possibili:

  • NEW_SUBSCRIPTION_CREATED: È stato creato un nuovo abbonamento.
  • SUBSCRIPTION_TRIAL_ENDED: La prova di un abbonamento è terminata.
  • PRICE_PLAN_SWITCHED: Il cliente ha eseguito la conversione da un piano flessibile a un piano annuale. Questo evento non viene attivato se il cliente esegue la conversione da un piano con impegno a un piano flessibile nell'ambito di un rinnovo.
  • COMMITMENT_CHANGED: l'impegno annuale è stato aumentato o diminuito.
  • SUBSCRIPTION_RENEWED: è stato rinnovato un abbonamento annuale.
  • SUBSCRIPTION_SUSPENDED: l'abbonamento è sospeso. Visualizza il campo subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: la sospensione è stata revocata per un abbonamento precedentemente sospeso.
  • SUBSCRIPTION_CANCELLED: l'abbonamento è stato annullato. Visualizza il campo subscription_cancellation_reason. Può essere utilizzato anche per rilevare i trasferimenti.

  • SUBSCRIPTION_CONVERTED: L'abbonamento è stato convertito. Di seguito sono riportati alcuni casi di esempio per questo evento:

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

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

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

  • LICENSE_ASSIGNMENT_CHANGED: la licenza è stata assegnata a un utente o revocata. Puoi utilizzare questo evento per monitorare in modo reattivo le modifiche al conteggio dei posti per gli abbonamenti flessibili.

Motivi dell'annullamento degli abbonamenti

Il motivo dell'annullamento dell'abbonamento viene compilato quando event_type è SUBSCRIPTION_CANCELLED. Di seguito sono riportati i possibili motivi di 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 esegue l'override di 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 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 compilato quando event_type è SUBSCRIPTION_SUSPENDED. Di seguito sono elencati i possibili motivi di sospensione:

  • PENDING_TOS_ACCEPTANCE: il cliente non ha eseguito l'accesso e non ha accettato i Termini di servizio di rivendita di Google Workspace.
  • RENEWAL_WITH_TYPE_CANCEL: l'impegno del cliente è terminato e il suo servizio è stato annullato al termine del periodo.
  • 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 è sospeso per un motivo interno a Google, ad esempio abuso.

Limitazioni di Pub/Sub

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