Notifiche push

Panoramica

L'API dei rivenditori utilizza l'API Pub/Sub per il push su diverse funzionalità di Google Workspace eventi di abbonamento. Ad esempio, puoi configurare per ricevere una notifica quando il cliente stati degli abbonamenti modifica.

Prerequisiti

  • Abilita l'API Pub/Sub per il tuo progetto Google Cloud.
  • Concedi ruoli IAM Pub/Sub al tuo account di servizio nella tua progetto cloud. La concessione del Il ruolo roles/pubsub.editor è un buon compromesso (facile e non troppo ampio), ma potresti voler utilizzare informazioni Autorizzazioni Pub/Sub.

crea un argomento

Per creare un argomento, devi registrarti con l'API dei rivenditori utilizzando Metodo resellernotify.register. Il metodo resellernotify.register prende l'indirizzo email di un account di servizio come . Solo gli account di servizio autorizzati con questo metodo possono abbonarsi al tuo 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 account di servizio aggiuntivi a utilizzare l'argomento, puoi chiamare resellernotify.register di nuovo.

Revocare l'accesso per un account di servizio

L'API dei rivenditori 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"
}

Sottoscrivere un abbonamento a un argomento

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

  • Sottoscrizione push: devi fornire un callback POST HTTP. Pub/Sub utilizza questo callback per informare l'applicazione di nuovi eventi.
  • Sottoscrizione pull: l'applicazione effettua periodicamente una chiamata HTTP a per recuperare tutte le modifiche in coda.
di Gemini Advanced.

Di seguito è riportato un esempio di richiesta di sottoscrizione 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 che hai usato in precedenza è stato creato.
  • PUSH_NOTIFICATION_ENDPOINT: la tua notifica push dell'endpoint del gestore.

Una risposta corretta 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 di notifica

Di seguito è riportato un esempio di notifica Pub/Sub. I dati dei messaggi sono una stringa JSON codificata in 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 possibili tipi di eventi:

  • NEW_SUBSCRIPTION_CREATED: è stata creata una nuova sottoscrizione.
  • SUBSCRIPTION_TRIAL_ENDED: periodo di prova di un abbonamento terminato.
  • PRICE_PLAN_SWITCHED: il cliente ha effettuato la conversione da un piano flessibile a un piano annuale e il piano d'azione. Questo evento non viene attivato se il cliente effettua una conversione da un tipo di 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 è stato sospeso. Consulta le campo subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: la sospensione è stata revocata per un abbonamento precedentemente sospeso.
  • SUBSCRIPTION_CANCELLED: l'abbonamento è stato annullato. Consulta le campo subscription_cancellation_reason. Può essere utilizzato anche per rilevare trasferimenti.

  • SUBSCRIPTION_CONVERTED: l'abbonamento è stato convertito. Alcuni casi di esempio per questo evento sono i seguenti:

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

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

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

  • LICENSE_ASSIGNMENT_CHANGED: la licenza è stata assegnata o revocata da un utente. Puoi utilizzare questo evento per tenere traccia in modo reattivo delle variazioni del numero di utenze per Abbonamenti flessibili.

Motivi dell'annullamento dell'abbonamento

Il motivo dell'annullamento dell'abbonamento viene compilato quando il valore event_type viene SUBSCRIPTION_CANCELLED. Di seguito sono riportati i possibili motivi dell'annullamento:

  • TRANSFERRED_OUT: il cliente è passato alla fatturazione diretta o a presso un altro rivenditore.
  • PURCHASE_OF_SUBSUMING_SKU: il cliente ha eseguito l'upgrade a uno SKU che sostituisce un'altra. Ad esempio, se un cliente con Google Workspace Business Starter e Google Vault per gli 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 motivi diversi da quelli elencati.

Motivi della sospensione dell'abbonamento

Il motivo della sospensione dell'abbonamento viene compilato quando il valore event_type viene SUBSCRIPTION_SUSPENDED. Di seguito sono riportati i possibili motivi di sospensione:

  • PENDING_TOS_ACCEPTANCE: il cliente non ha eseguito l'accesso e ha accettato i Termini di servizio del rivenditore Google Workspace.
  • RENEWAL_WITH_TYPE_CANCEL: l'impegno del cliente è terminato e i suoi 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 non di prova.
  • OTHER: il cliente è stato sospeso per un motivo interno di Google, ad esempio 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, niente affatto. È consigliabile utilizzare reseller.subscriptions.get su tutte le sottoscrizioni modificate per eseguire il pull del lo stato attuale.