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 afin d'être averti lorsque l'état des abonnements 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 sur votre projet Cloud. L'attribution du rôle roles/pubsub.editor est un bon compromis (facile et peu étendue), 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 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 des comptes de service supplémentaires à utiliser votre sujet, vous pouvez appeler à nouveau resellernotify.register.

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

L'API Reseller offre également la possibilité d'annuler l'enregistrement de 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

Après avoir créé le sujet Pub/Sub, vous devez configurer la manière 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 envoie régulièrement un appel HTTP pour obtenir toutes les modifications 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 permettant d'identifier 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.

Les appels réussis renvoient 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 des notifications

Voici un exemple de notification Pub/Sub. Les données du message sont transmises sous la forme d'une 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 a pris fin pour un abonnement.
  • PRICE_PLAN_SWITCHED: le client est passé d'un forfait modulable à un forfait annuel. Cet événement ne se déclenche pas si le client passe d'un forfait avec engagement à un forfait modulable dans le cadre 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é annulée.
  • SUBSCRIPTION_CANCELLED: l'abonnement a été annulé. Consultez le champ subscription_cancellation_reason. Peut également servir à détecter les transferts.

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

    • Convertissez un abonnement direct en abonnement revendeur.
    • Convertissez l'abonnement payant en offre de grâce.
    • Convertir un abonnement en ligne en abonnement hors connexion.

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

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

  • LICENSE_ASSIGNMENT_CHANGED: la 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 le changement du nombre de licences pour les abonnements modulables.

Motifs de résiliation d'abonnement

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

  • TRANSFERRED_OUT: le client a été transféré vers la facturation directe ou vers un autre revendeur.
  • PURCHASE_OF_SUBSUMING_SKU: le client est passé à un 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 utilisé, 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 raison autre que celle indiquée.

Motifs de suspension de l'abonnement

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

  • PENDING_TOS_ACCEPTANCE: le client ne s'est pas connecté et n'a pas accepté les conditions d'utilisation des services indirects Google Workspace.
  • RENEWAL_WITH_TYPE_CANCEL: l'engagement du client a pris fin et son service a été annulé à échéance.
  • RESELLER_INITIATED: le revendeur a suspendu manuellement l'abonnement.
  • TRIAL_ENDED: la période d'essai du client a expiré et le client n'a pas sélectionné de forfait sans essai.
  • OTHER: le compte client est suspendu pour une raison interne à Google, par exemple pour 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 afin d'extraire l'état actuel.