Cette page a été traduite par l'API Cloud Translation.
Switch to English

Intégrer le backend de votre application

Cette section décrit la procédure à suivre pour intégrer le backend de votre application à Google Cloud Marketplace. Cette intégration vous permet de gérer les comptes et les droits des utilisateurs, qui indiquent qu'ils ont acheté votre produit sur Google Cloud Marketplace. Si vous avez choisi un modèle de tarification basé sur l'utilisation, l'intégration du backend permet également de signaler l'utilisation à Google.

Pour un exemple d'intégration d'une application de base avec Google Cloud Marketplace et une procédure pas à pas de l'exemple de code, consultez l'atelier de programmation pour intégrer un service géré.

Pour obtenir l'exemple de code utilisé dans l'atelier de programmation, consultez le dépôt GitHub.

Avant de commencer

  • Configurez l'accès à l'API Partner Procurement de Cloud Commerce comme décrit à la page Intégrer votre application : configuration.
  • Si vous avez choisi un modèle de tarification basé sur l'utilisation, vérifiez si votre ingénieur partenaire a créé un service sur lequel vous pouvez rendre compte de l'utilisation. Ce service s'affiche dans le champ Domaine de service de la section Intégration de la facturation de Producer Portal.

Créer un compte de service

Pour intégrer votre solution à Google Cloud, vous devez créer un compte de service dans le projet que vous utilisez pour votre solution. Votre application utilise ce compte de service pour interagir avec les API partenaires de Google Cloud Marketplace et obtenir des informations sur les achats des utilisateurs.

Nous vous recommandons d'utiliser Producer Portal pour créer et associer vos comptes de service.

Si vous utilisez le portail Partners, votre ingénieur partenaire attribue le rôle d'abonné Pub/Sub à ce compte de service. Pour connaître la procédure détaillée permettant de créer un compte de service, consultez la page Créer et gérer des comptes de service.

Intégrer le backend de votre application à l'aide de Producer Portal

Pour accéder à toutes les informations dont vous avez besoin pour intégrer le backend de votre application à Google Cloud Marketplace à partir d'un seul emplacement, telles que vos comptes de service et vos identifiants du niveau du forfait, utilisez l'INTÉGRATION DE LA FACTURATION de Producer Portal.

Le lien direct vers Producer Portal est le suivant :

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Pour accéder à la section INTÉGRATION DE LA FACTURATION, procédez comme suit :

  1. Dans la liste des solutions, cliquez sur le nom de votre solution.

  2. Sur la page Présentation de votre solution, accédez à la section Intégration technique et cliquez sur INTÉGRATION DE LA FACTURATION.

Créer et associer des comptes de service dans Producer Portal

Utilisez la section INTÉGRATION DE LA FACTURATION de Producer Portal pour créer et associer les comptes de service que vous utilisez pour interagir avec les API partenaires et obtenir des informations sur les achats des utilisateurs.

Le lien direct vers Producer Portal est le suivant :

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Dans les étapes suivantes, vous pouvez utiliser des comptes de service existants ou en créer de nouveaux. Si vous créez un nouveau compte de service, spécifiez le nom du compte de service dans le champ Nom du compte de service et l'ID du compte de service dans le champ ID du compte de service, puis cliquez sur CRÉER ET ASSOCIER.

Pour associer vos comptes de service, procédez comme suit :

  1. Dans la liste des solutions, cliquez sur le nom de votre solution.

  2. Sur la page Présentation de votre solution, accédez à la section Intégration technique et cliquez sur INTÉGRATION DE LA FACTURATION.

  3. Pour procéder à l'intégration à l'API Partner Procurement, sous Associer un compte de service pour appeler l'API Procurement, cliquez sur AJOUTER UN COMPTE DE SERVICE. Vous pouvez saisir un compte de service existant dans le champ ou créer un nouveau compte de service.

  4. Pour procéder à l'intégration à Pub/Sub, sous Associer un compte de service pour s'abonner à un sujet Pub/Sub, cliquez sur AJOUTER UN COMPTE DE service. Vous pouvez saisir un compte de service existant dans le champ ou créer un nouveau compte de service.

  5. Pour intégrer l'API Service Control, sous Ajouter roles/servicemanagement.serviceController à un compte de service, cliquez sur AJOUTER UN COMPTE DE SERVICE. Vous pouvez saisir un compte de service existant dans le champ ou créer un nouveau compte de service.

Tâches de compte utilisateur

En règle générale, votre application doit gérer le scénario suivant :

  1. Un utilisateur effectue une requête ou une modification dans Google Cloud Marketplace, par exemple en souscrivant à votre solution.

  2. Google Cloud Marketplace envoie à votre application une notification via Pub/Sub contenant des informations sur la requête dans le champ eventType. Par exemple, si un utilisateur change son droit, le champ eventType est défini sur ENTITLEMENT_PLAN_CHANGED.

    Consultez la liste complète des eventTypes possibles.

  3. Pour approuver la requête, votre application envoie une requête HTTP POST à l'API Partner Procurement.

Les sections suivantes décrivent les types de requêtes que les utilisateurs peuvent effectuer et ce que votre application doit faire pour gérer ces requêtes.

Pour les appels d'API décrits dans cette section, utilisez ce point de terminaison :

https://cloudcommerceprocurement.googleapis.com/

Créer un compte pour un nouvel utilisateur

Lorsqu'un utilisateur achète votre solution pour la première fois, Google Cloud Marketplace crée une ressource de compte qui suit la relation de l'utilisateur avec vous. Lorsque la ressource de compte est créée, vous recevez une notification via le sujet Pub/Sub qui a été créé pour vous. Le message Pub/Sub est au format suivant :

{
  "eventId": "...",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

USER_ACCOUNT_ID est l'ID de compte créé par Google Cloud Marketplace.

Simultanément, l'utilisateur est dirigé vers votre page d'inscription, où il crée un compte dans votre système. Pour en savoir plus sur la création de la page d'inscription, consultez la page Intégrer l'interface de votre application.

Une fois l'utilisateur inscrit, votre application doit appeler l'API Partner Procurement et indiquer que le compte a été approuvé. Les comptes sont créés dans l'état ACCOUNT_ACTIVE, mais une entrée PENDING est présente dans le champ approvals nommé signup, ce qui indique que l'utilisateur ne s'est pas encore inscrit. Pour approuver le compte après l'inscription de l'utilisateur, utilisez la requête HTTP POST suivante :

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

YOUR_PARTNER_ID est un ID qui vous est attribué lorsque l'ingénieur partenaire permet l'accès à l'API Partner Procurement.

Pour vérifier l'état d'un compte associé, utilisez la demande HTTP GET suivante :

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

La réponse est au format suivant :

{
  "name": "providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID",
  "provider": "acme-services",
  "state": "ACCOUNT_ACTIVE",
  "approvals": [{
    "name": "signup",
    "state": "APPROVED",
    "updateTime": "...",
  }],
  "updateTime": "...",
  "createTime": "..."
}

Pour obtenir la liste des états de compte possibles, consultez la référence API providers.accounts.

Gérer les droits

Lorsque les clients choisissent un forfait pour votre logiciel, Google crée un droit, qui indique que le client a acheté votre solution sur Google Cloud Marketplace. Cette section explique comment créer et gérer les droits de vos clients à l'aide de l'API Partner Procurement.

Pour en savoir plus sur la gestion des droits, consultez la documentation de référence.

Approuver ou refuser un droit

Lorsqu'un client choisit un forfait, Google Cloud Marketplace crée un droit et envoie le message Pub/Sub suivant à votre application :

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

ENTITLEMENT_ID est un ID créé par Google Cloud Marketplace.

Dans votre système, mettez à jour le compte de l'utilisateur pour indiquer qu'il a souscrit un forfait. Pour approuver le droit, envoyez une requête HTTP POST à l'API Partner Procurement et envoyez l'ID ENTITLEMENT_ID que vous approuvez :

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

Pour refuser un droit, utilisez plutôt la méthode reject dans votre requête HTTP POST :

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject

Modifier un forfait de droit

En fonction de la configuration de vos forfaits, vos clients pourront peut-être modifier le leur. Si un client sélectionne un nouveau forfait, vous recevez un message Pub/Sub, au format suivant :

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
  },
}

Pour approuver la modification du forfait, adressez la requête HTTP POST suivante à l'API Partner Procurement :

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

L'organisme demandeur doit avoir le plan en cours d'approbation :

{
  "pendingPlanName": PLAN_NAME
}

Une fois la modification approuvée, vous recevez un autre message Pub/Sub lorsque la modification prend effet. Dans le message, le champ eventType devient ENTITLEMENT_PLAN_CHANGED. Pour vérifier l'état d'un plan, envoyez la requête HTTP GET suivante à l'API Partner Procurement.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

La réponse est semblable à la suivante, le champ state indiquant si le nouveau forfait est actif ou si la modification du forfait est toujours en attente :

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

Envoyer un message d'état aux utilisateurs

Si le délai entre le choix d'un forfait par l'utilisateur et l'approbation d'un droit d'accès par votre backend est de plusieurs heures, il est recommandé d'envoyer un message d'état aux utilisateurs. Dans ce message, indiquez l'état d'avancement de l'approbation et, le cas échéant, à quel moment vous prévoyez l'approbation définitive.

Pour fournir un message d'état, faites la demande HTTP POST suivante à l'API Procurement :

POST v1/providers/your-partner-id/entitlements/entitlement_id:updateUserMessage

Dans le corps de la requête, indiquez le texte du message, de la même manière que dans l'exemple suivant :

{
  "message": "Approval expected in 2 days"
}

Annuler des droits d'accès

Si un utilisateur décide d'annuler son droit d'accès, vous recevez une notification Pub/Sub. Tout comme la modification d'un forfait, l'annulation peut prendre effet à la fin du cycle de facturation en cours.

La notification est au format suivant :

{
  "eventId": "...",
  // If the entitlement is canceled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "cancellationDate": "...",
    "updateTime": "..."
  },
}

Supprimer un droit

Si un utilisateur effectue une requête directe ou quitte la plate-forme Google, ses droits d'accès sont annulés et supprimés, ainsi que son compte. Pour protéger la vie privée de l'utilisateur, vous devez supprimer ses données de vos serveurs dès que vous en êtes informé.

Une fois les droits d'accès et le compte supprimés, vous recevez des notifications semblables à celles-ci :

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

Liste des types d'événements pour les tâches de compte

Voici une liste des eventType que votre application peut recevoir dans les messages Pub/Sub :

eventTypeDescription
ACCOUNT_CREATION_REQUESTEDObsolète
ACCOUNT_ACTIVEIndique que le compte du client a été créé.
ACCOUNT_DELETEDIndique que le compte du client a été supprimé des systèmes Google Cloud.
ENTITLEMENT_CREATION_REQUESTEDIndique qu'un client a sélectionné l'un de vos forfaits. Cela déclenche également un nouvel événement ENTITLEMENT_CREATION_REQUESTED toutes les 24 heures jusqu'à ce que vous preniez les mesures nécessaires.
ENTITLEMENT_ACTIVEIndique que le forfait choisi par un client est maintenant actif.
ENTITLEMENT_PLAN_CHANGE_REQUESTEDIndique qu'un client a choisi un nouveau forfait. Cela déclenche également un nouvel événement ENTITLEMENT_PLAN_CHANGE_REQUESTED toutes les 24 heures jusqu'à ce que vous preniez les mesures appropriées.
ENTITLEMENT_PLAN_CHANGEDIndique que la modification du forfait d'un client est approuvée et que les modifications sont entrées en vigueur.
ENTITLEMENT_PLAN_CHANGE_CANCELLEDIndique que le changement de forfait d'un client a été annulé, soit parce qu'il n'a pas été approuvé, soit parce le client est revenu à son ancien forfait.
ENTITLEMENT_PENDING_CANCELLATIONIndique qu'un client a annulé son forfait et que l'annulation est en attente jusqu'à la fin du cycle de facturation.
ENTITLEMENT_CANCELLATION_REVERTEDIndique que l'annulation en attente d'un client a été annulée. Notez que les annulations ne peuvent pas être annulées une fois qu'elles sont définitives.
ENTITLEMENT_CANCELLEDIndique que le forfait d'un client a été annulé.
ENTITLEMENT_CANCELLINGIndique que le forfait d'un client est en cours d'annulation.
ENERMENT_RENOUVEIndique que le droit d'un client a été renouvelé pour une autre période. Aucune action de votre part n'est requise pour procéder au renouvellement.
ENTITLEMENT_OFFER_ENDEDIndique que l'offre privée d'un client est terminée. Si le droit du client a été annulé, un événement ENTITLEMENT_CANCELLED distinct est déclenché. Si les droits du client sont toujours actifs, la tarification est alors déduite.
ENTITLEMENT_DELETEDIndique que les informations sur le forfait d'un client ont été supprimées de Google Cloud Marketplace.

Signaler l'utilisation à Google (pour la tarification basée sur l'utilisation)

Si vous choisissez une tarification basée sur l'utilisation pour votre solution, vous devez signaler l'utilisation de votre application à l'API Service Control.

Votre ingénieur partenaire crée un service correspondant à votre solution et permet à votre compte de service d'en signaler l'utilisation.

Pour obtenir une présentation de Service Control, consultez le Guide de démarrage.

Lorsqu'un droit est créé, vous devez appeler l'API Partner Procurement pour récupérer un usageReportingId, à l'aide de la demande HTTP GET suivante :

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

La réponse qui contient des informations sur le droit est au format suivant :

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

Pour signaler l'utilisation, vous devez d'abord effectuer un appel d'API services.check afin de vérifier la configuration du service. Dans la réponse, si l'objet checkErrors[] est vide, effectuez un appel d'API services.report pour envoyer le rapport d'utilisation.

Le rapport d'utilisation est un fichier Operation qui contient un élément MetricValueSet pour vos métriques de tarification. Operation inclut également un champ consumerId qui est défini sur l'ID USAGE_REPORTING_ID du droit.

Voici un exemple de rapport d'utilisation pour example-messaging-service qui envoie des informations sur le stockage utilisé par le client :

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report
{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }]
  }]
}

Vous devez signaler l'utilisation de votre application toutes les heures. Vérifiez que startTime et endTime sont corrects. Si le service de l'utilisateur a été désactivé avant l'heure startTime, l'API services.check envoie une erreur dans l'objet checkErrors[] et la période n'est pas facturée au client.

Si l'API services.check renvoie une ou plusieurs des erreurs suivantes, nous vous recommandons de cesser de fournir votre service au client jusqu'à ce que l'erreur soit résolue :

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED