Notifications push

Présentation

L'API Reseller utilise l'API Pub/Sub pour envoyer des notifications push concernant différents événements d'abonnement Google Workspace. Par exemple, vous pouvez configurer des notifications push pour être averti lorsque l'état de l'abonnement de vos clients change.

Prérequis

  • Activez l'API Pub/Sub pour votre projet Google Cloud.
  • Attribuez des rôles IAM Pub/Sub à votre compte de service dans votre projet Cloud. L'attribution du rôle roles/pubsub.editor constitue un bon compromis (facile et pas trop large), mais vous pouvez utiliser des autorisations Pub/Sub plus spécifiques.

Créer un sujet

Pour créer une rubrique, vous devez vous enregistrer auprès de l'API Reseller à l'aide de la méthode resellernotify.register. La méthode resellernotify.register prend une adresse e-mail de compte de service comme paramètre. Seuls les comptes de service autorisés par cette méthode peuvent s'abonner au sujet que vous venez de créer.

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

Une réponse réussie renvoie un code d'état HTTP 200 et une réponse JSON contenant le nom de votre sujet Pub/Sub.

Voici un exemple de réponse :

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

Pour autoriser d'autres comptes de service à utiliser votre sujet, vous pouvez appeler resellernotify.register à nouveau.

Révoquer l'accès d'un compte de service

L'API Reseller permet également de désenregistrer des comptes de service à l'aide du point de terminaison resellernotify.unregister :

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

S'abonner à un thème

Après avoir créé le sujet Pub/Sub, vous devez configurer la façon dont votre application consomme vos événements de modification. Choisissez l'une des options suivantes :

  • Abonnement push : vous fournissez un rappel HTTP POST. Pub/Sub utilise ce rappel pour informer votre application des nouveaux événements.
  • Abonnement pull : votre application effectue régulièrement un appel HTTP pour obtenir toutes les modifications mises en file d'attente.

Voici un exemple de requête pour s'abonner à un thème :

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Remplacez les éléments suivants :

  • PROJECT : votre projet Google Cloud.
  • SUBSCRIPTION_NAME : nom d'identification de votre abonnement.
  • TOPIC_NAME : sujet Pub/Sub que vous avez créé précédemment.
  • PUSH_NOTIFICATION_ENDPOINT : point de terminaison de votre gestionnaire de notifications push.

Une réponse réussie renvoie un code d'état HTTP 200. Voici un exemple de réponse : 

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Formats de notification

Vous trouverez ci-dessous un exemple de notification Pub/Sub. Les données du message sont transmises sous forme de chaîne JSON encodée en base64.

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

Voici l'exemple d'objet message.data après décodage :

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

Types d'événement

La liste suivante contient tous les types d'événements possibles :

  • NEW_SUBSCRIPTION_CREATED : un abonnement a été créé.
  • SUBSCRIPTION_TRIAL_ENDED : l'essai d'un abonnement est terminé.
  • PRICE_PLAN_SWITCHED : le client est passé d'un forfait modulable à un forfait annuel. Cet événement n'est pas déclenché si le client passe d'un forfait avec engagement à un forfait modulable lors d'un renouvellement.
  • COMMITMENT_CHANGED : l'engagement annuel a été augmenté ou diminué.
  • SUBSCRIPTION_RENEWED : un abonnement annuel a été renouvelé.
  • SUBSCRIPTION_SUSPENDED : l'abonnement est suspendu. Consultez le champ subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED : la suspension d'un abonnement précédemment suspendu a été révoquée.
  • SUBSCRIPTION_CANCELLED : l'abonnement a été résilié. Consultez le champ subscription_cancellation_reason. Vous pouvez aussi l'utiliser pour détecter les transferts.

  • SUBSCRIPTION_CONVERTED : l'abonnement a été converti. Voici quelques exemples de cas pour cet événement :

    • Convertissez un abonnement direct en abonnement revendeur.
    • Convertir un abonnement payant en offre de report de paiement
    • Convertissez un abonnement en ligne en abonnement hors connexion.

  • SUBSCRIPTION_UPGRADE : Le code SKU de l'abonnement a été mis à niveau. Par exemple, l'abonnement est passé de Google Workspace Business Starter à Business Standard.

  • SUBSCRIPTION_DOWNGRADE : le code SKU de l'abonnement a été rétrogradé. Par exemple, l'abonnement est passé de Google Workspace Business Standard à Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED : une licence a été attribuée à un utilisateur ou lui a été retirée. Vous pouvez utiliser cet événement pour suivre de manière réactive les modifications du nombre de sièges pour les abonnements flexibles.

Motifs d'annulation des abonnements

Le motif d'annulation de l'abonnement est renseigné lorsque event_type est défini sur SUBSCRIPTION_CANCELLED. Voici les motifs d'annulation possibles :

  • TRANSFERRED_OUT : le client est passé à la facturation directe ou à un autre revendeur.
  • PURCHASE_OF_SUBSUMING_SKU : Le client est passé à un code SKU qui en remplace un autre. Par exemple, si un client disposant de Google Workspace Business Starter et de Google Vault passe à Google Workspace Business Plus, l'abonnement Vault est inclus, car il est compris dans Google Workspace Business Plus.
  • RESELLER_INITIATED : le revendeur a résilié l'abonnement.
  • OTHER : l'abonnement a été résilié pour une raison autre que celles listées.

Motifs de suspension des abonnements

Le motif de suspension de l'abonnement est renseigné lorsque event_type est défini sur SUBSCRIPTION_SUSPENDED. Voici quelques raisons possibles de suspension :

  • PENDING_TOS_ACCEPTANCE : le client ne s'est pas connecté et n'a pas accepté les conditions d'utilisation de Google Workspace revendu.
  • RENEWAL_WITH_TYPE_CANCEL : l'engagement du client a pris fin et son service a été résilié à la fin de la période.
  • RESELLER_INITIATED : le revendeur a suspendu manuellement l'abonnement.
  • TRIAL_ENDED : l'essai du client a expiré et il n'a pas sélectionné de forfait non soumis à essai.
  • OTHER : le compte du client est suspendu pour une raison interne à Google (par exemple, utilisation abusive).

Limites de Pub/Sub

L'ordre des notifications push n'est pas garanti. Les messages peuvent être distribués plusieurs fois et, dans des situations extrêmes, pas du tout. Nous vous recommandons d'utiliser reseller.subscriptions.get sur tous les abonnements modifiés pour extraire l'état actuel.