Notifiche push

In questa pagina viene descritto come utilizzare le notifiche push con l'API Reseller.

Panoramica

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

Prerequisiti

Crea un argomento

Per creare un argomento, registrati all'API Reseller utilizzando il resellernotify.register metodo. Questo metodo accetta un indirizzo email del service account come parametro. Solo i service account autorizzati da questo metodo possono abbonarsi al tuo argomento.

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.

Esempio di risposta:

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

Per autorizzare altri service account, chiama di nuovo resellernotify.register.

Revoca l'accesso per un service account

L'API Reseller può 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"
}

Abbonati a un argomento

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

  • Sottoscrizione push: fornisci un callback HTTP POST. Pub/Sub utilizza questo callback per inviare una notifica alla tua applicazione in merito ai nuovi eventi.
  • Sottoscrizione pull: l'applicazione effettua periodicamente una chiamata HTTP per ottenere le modifiche in coda.

Esempio di richiesta di abbonamento 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 creato in precedenza.
  • PUSH_NOTIFICATION_ENDPOINT: l'endpoint del gestore delle notifiche push.

Una risposta riuscita restituisce un codice di stato HTTP 200. 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 sono una stringa JSON con codifica base64.

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

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 dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Tipi di evento

Tipi di evento possibili:

  • NEW_SUBSCRIPTION_CREATED: è stato creato un nuovo abbonamento.
  • SUBSCRIPTION_TRIAL_ENDED: la prova di un abbonamento è terminata.
  • PRICE_PLAN_SWITCHED: il cliente ha convertito un piano flessibile in un piano annuale. Questo evento non viene attivato se il cliente converte un piano annuale in un piano flessibile nell'ambito di un rinnovo.
  • COMMITMENT_CHANGED: l'impegno annuale è stato aumentato o ridotto.
  • SUBSCRIPTION_RENEWED: è stato rinnovato un abbonamento annuale.
  • SUBSCRIPTION_SUSPENDED: l'abbonamento è stato sospeso. Consulta subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: la sospensione è stata revocata.
  • SUBSCRIPTION_CANCELLED: l'abbonamento è stato annullato. Consulta subscription_cancellation_reason. Può anche rilevare i trasferimenti.
  • SUBSCRIPTION_CONVERTED: l'abbonamento è stato convertito. Esempi di casi d'uso:
    • Converti l'abbonamento diretto in abbonamento del rivenditore.
    • Converti l'abbonamento a pagamento in offerta di periodo di tolleranza.
    • Converti l'abbonamento online in abbonamento offline.
  • SUBSCRIPTION_UPGRADE: è stato eseguito l'upgrade dello SKU dell'abbonamento. Esempio: da Google Workspace Business Starter a Business Standard.
  • SUBSCRIPTION_DOWNGRADE: è stato eseguito il downgrade dello SKU dell'abbonamento. Esempio: da Google Workspace Business Standard a Business Starter.
  • LICENSE_ASSIGNMENT_CHANGED: la licenza è stata assegnata o revocata. Utilizza questa opzione per monitorare le modifiche al numero di postazioni per gli abbonamenti flessibili.

Motivi dell'annullamento degli abbonamenti

Il motivo dell'annullamento viene inserito quando event_type è SUBSCRIPTION_CANCELLED. Possibili cause:

  • TRANSFERRED_OUT: il cliente ha eseguito la transizione 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. Esempio: un cliente con Google Workspace Business Starter e Vault esegue l'upgrade a Business Plus, che include Vault.
  • RESELLER_INITIATED: il rivenditore ha annullato l'abbonamento.
  • OTHER: l'abbonamento è stato annullato per un altro motivo.

Motivi della sospensione degli abbonamenti

Il motivo della sospensione viene inserito quando event_type è SUBSCRIPTION_SUSPENDED. Possibili cause:

  • PENDING_TOS_ACCEPTANCE: il cliente non ha accettato i Termini di servizio di Google Workspace rivenduti.
  • RENEWAL_WITH_TYPE_CANCEL: l'impegno del cliente è terminato e il servizio è stato annullato.
  • RESELLER_INITIATED: il rivenditore ha sospeso manualmente l'abbonamento.
  • TRIAL_ENDED: la prova del cliente è scaduta senza che sia stato 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 è sempre sequenziale. I messaggi potrebbero essere recapitati più volte o non essere recapitati. Ti consigliamo di utilizzare reseller.subscriptions.get per gli abbonamenti modificati per eseguire il pull dello stato attuale.