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

• Abilita l'API Pub/Sub per il tuo progetto Google Cloud.
• Concedi i ruoli IAM Pub/Sub al tuo account di servizio 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 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": "[e-mail]"
}

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": "[e-mail]"
}

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:

• Abbonamento 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.

Nota: utilizza un client Pub/Sub per effettuare questa richiesta. Devi autenticarti utilizzando uno dei service account registrati nel passaggio precedente. Per saperne di più, consulta Sottoscrittore.

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 diminuito.
• SUBSCRIPTION_RENEWED: è stato rinnovato un abbonamento annuale.
• SUBSCRIPTION_SUSPENDED: l'abbonamento è 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:
  • 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 rivenduti 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 per comportamenti illeciti.

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 sugli abbonamenti modificati per recuperare lo stato attuale.