Notifications push

Présentation

L'API Reseller utilise l'API Pub/Sub pour envoyer des notifications push sur 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. Accorder le rôle roles/pubsub.editor est 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 un sujet, vous devez vous enregistrer auprès de l'API Reseller à l'aide de la méthode resellernotify.register. La méthode resellernotify.register utilise 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 à votre sujet nouvellement créé.

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 à nouveau resellernotify.register.

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 sujet

Une fois le sujet Pub/Sub créé, 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 récupérer toutes les modifications mises en file d'attente.

Voici un exemple de requête d'abonnement à un sujet:

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 nouvel abonnement a été créé.
  • SUBSCRIPTION_TRIAL_ENDED: essai terminé pour un abonnement.
  • 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 a été révoquée pour un abonnement précédemment suspendu.
  • SUBSCRIPTION_CANCELLED: l'abonnement a été résilié. Consultez le champ subscription_cancellation_reason. Peut également être utilisé pour détecter les transferts.

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

    • Convertir un abonnement direct en abonnement revendeur
    • Convertir un abonnement payant en offre de délai de grâce
    • Convertir un abonnement en ligne en abonnement hors connexion

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

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

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

Motifs de résiliation des abonnements

Le motif de l'annulation de l'abonnement est renseigné lorsque la valeur de event_type est SUBSCRIPTION_CANCELLED. Voici les raisons possibles d'annulation:

  • TRANSFERRED_OUT: le client a opté pour la facturation directe ou pour un autre revendeur.
  • PURCHASE_OF_SUBSUMING_SKU: Le client a effectué une mise à niveau vers un code SKU qui 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 inclus dans Google Workspace Business Plus.
  • RESELLER_INITIATED: le revendeur a résilié l'abonnement.
  • OTHER: l'abonnement a été résilié pour une autre raison que celle indiquée.

Motifs de suspension d'un abonnement

Le motif de suspension de l'abonnement est renseigné lorsque event_type est SUBSCRIPTION_SUSPENDED. Voici les 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 sans essai.
  • OTHER: le client est suspendu pour une raison interne à Google (par exemple, un abus).

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 récupérer l'état actuel.