Notifiche push

Questa pagina descrive 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

Abilita l'API Pub/Sub per il tuo progetto cloud Google.
Concedi ruoli IAM Pub/Sub al service account nel tuo progetto Cloud. È consigliabile concedere il ruolo roles/pubsub.editor, ma puoi utilizzare autorizzazioni Pub/Sub più specifiche.

Crea un argomento

Per creare un argomento, registrati con l'API Reseller utilizzando il metodo resellernotify.register. Questo metodo accetta come parametro un indirizzo email del service account. Solo i service account autorizzati con questo metodo possono iscriversi all'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.

Revocare 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"
}

Iscriversi 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 notificare alla tua applicazione i nuovi eventi.
Sottoscrizione pull: la tua applicazione effettua periodicamente una chiamata HTTP per ottenere le modifiche in coda.

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 identificativo per l'abbonamento.
TOPIC_NAME: l'argomento Pub/Sub che hai 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 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 passa da un piano annuale 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. Vedi subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: La sospensione è stata revocata.
SUBSCRIPTION_CANCELLED: l'abbonamento è stato annullato. Vedi subscription_cancellation_reason. Può anche rilevare i trasferimenti.
SUBSCRIPTION_CONVERTED: L'abbonamento è stato convertito. Esempi di casi:
- 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: La SKU dell'abbonamento è stata aggiornata. Esempio: Da Google Workspace Business Starter a Business Standard.
SUBSCRIPTION_DOWNGRADE: è stato eseguito il downgrade dello SKU dell'abbonamento. Esempio: Google Workspace Business Standard a Business Starter.
LICENSE_ASSIGNMENT_CHANGED: La licenza è stata assegnata o revocata. Utilizza per monitorare le modifiche al numero di posti per gli abbonamenti flessibili.

Motivi dell'annullamento degli abbonamenti

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

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 ne sostituisce un altro. Esempio: un cliente con Google Workspace Business Starter e upgrade di Vault 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 compilato quando event_type è SUBSCRIPTION_SUSPENDED. Possibili cause:

PENDING_TOS_ACCEPTANCE: il cliente non ha accettato i Termini di servizio di rivendita di Google Workspace.
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 è sospeso per un motivo interno di Google, ad esempio abuso.

Limitazioni di Pub/Sub

L'ordine delle notifiche push non è sempre sequenziale. I messaggi potrebbero essere recapitati più volte o non essere recapitati affatto. Ti consigliamo di utilizzare reseller.subscriptions.get per gli abbonamenti modificati per eseguire il pull dello stato attuale.