Notifications push

Cette page explique comment utiliser les notifications push avec l'API Reseller.

Présentation

L'API Reseller utilise l'API Pub/Sub pour envoyer des notifications push concernant les événements d'abonnement Google Workspace . Par exemple, vous pouvez configurer des notifications push pour être averti lorsque l'état d'un abonnement client 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. Nous vous recommandons d'attribuer le rôle roles/pubsub.editor, mais vous pouvez utiliser des autorisations Pub/Sub plus spécifiques.

Créer un sujet

Pour créer un sujet, enregistrez-vous auprès de l'API Reseller à l'aide de la resellernotify.register méthode. Cette méthode 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 à votre sujet.

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

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

Exemple de réponse :

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

Pour autoriser d'autres comptes de service, appelez à nouveau resellernotify.register.

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

L'API Reseller peut annuler l'enregistrement 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

Après avoir créé le sujet Pub/Sub, configurez la manière dont votre application consomme les é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 les modifications mises en file d'attente.

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 positive renvoie un code d'état HTTP 200. 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 une chaîne JSON encodée en base64.

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

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 dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Types d'événement

Types d'événements possibles :

NEW_SUBSCRIPTION_CREATED : un abonnement a été créé.
SUBSCRIPTION_TRIAL_ENDED : l'essai d'un abonnement a pris fin.
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 annuel à 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 subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED : la suspension a été révoquée.
SUBSCRIPTION_CANCELLED : l'abonnement a été annulé. Consultez subscription_cancellation_reason. Peut également détecter les transferts.
SUBSCRIPTION_CONVERTED : l'abonnement a été converti. Exemples de cas d'utilisation :
- Convertir un abonnement direct en abonnement revendeur.
- Convertir un abonnement payant en offre de grâce.
- Convertir un abonnement en ligne en abonnement hors ligne.
SUBSCRIPTION_UPGRADE : le code SKU de l'abonnement a été mis à niveau. Exemple : Google Workspace Business Starter vers Business Standard.
SUBSCRIPTION_DOWNGRADE : le code SKU de l'abonnement a été rétrogradé. Exemple : Google Workspace Business Standard vers Business Starter.
LICENSE_ASSIGNMENT_CHANGED : une licence a été attribuée ou révoquée. Utilisez cette option pour suivre les modifications du nombre de licences pour les abonnements modulables.

Motifs d'annulation des abonnements

Le motif d'annulation est renseigné lorsque event_type est SUBSCRIPTION_CANCELLED. Raisons 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 remplace un autre. Exemple : un client disposant de Google Workspace Business Starter et de Vault passe à Business Plus, qui inclut Vault.
RESELLER_INITIATED : le revendeur a annulé l'abonnement.
OTHER : l'abonnement a été annulé pour une autre raison.

Motifs de suspension des abonnements

Le motif de suspension est renseigné lorsque event_type est SUBSCRIPTION_SUSPENDED. Raisons possibles :

PENDING_TOS_ACCEPTANCE: le client n'a pas accepté les conditions d'utilisation de Google Workspace Resold.
RENEWAL_WITH_TYPE_CANCEL: l'engagement du client a pris fin et le service a été annulé.
RESELLER_INITIATED : le revendeur a suspendu manuellement l'abonnement.
TRIAL_ENDED: l'essai du client a expiré sans qu'il ait sélectionné de forfait non soumis à essai.
OTHER: le client est suspendu pour une raison interne à Google, telle qu'un abus.

Limites de Pub/Sub

L'ordre des notifications push n'est pas toujours séquentiel. Les messages peuvent être transmis plusieurs fois ou pas du tout. Nous vous recommandons d'utiliser reseller.subscriptions.get sur les abonnements modifiés pour extraire l'état actuel.