Intégrer votre assistance

Cette page décrit le flux de travail d'assistance lorsque vous souhaitez fournir une assistance dans le cadre de votre produit.

Votre système doit être intégré à Google pour que vous puissiez fournir une assistance aux clients qui ont acheté vos produits via Google. L'intégration est basée sur la fourniture des éléments suivants de la part de Google :

  • Une clé qui vous permettra de vérifier l'éligibilité à l'assistance d'un utilisateur dans le cadre du processus d'inscription.

  • Une API (l'API Subscriptions) à laquelle vous pouvez transmettre la clé pour interroger périodiquement l'état d'éligibilité à l'assistance d'un utilisateur.

Obtenir l'ID d'assistance de l'utilisateur

L'intégration de l'assistance s'articule autour d'un ID de compte externe, qui correspond à l'ID d'assistance de vos utilisateurs.

Pour obtenir l'ID d'assistance de vos utilisateurs, vous devez créer un workflow d'assistance et fournir une URL vers l'étape initiale de ce workflow. Google vous envoie ensuite l'ID de compte externe dans l'URL.

Si vous mettez en œuvre le workflow d'assistance, celui-ci doit accepter le numéro de compte externe dans l'URL. L'ID de compte externe peut faire partie du chemin de l'URL ou sous forme de valeur de paramètre de requête, comme dans les exemples ci-dessous:

# External account ID in path
http://example.com/mysupportpage/{external_account_id}?someparameter=yes

# External account ID as a query parameter
http://example.com/mysupportpage?eid={external_account_id}&something_else

Le texte {external_account_id} de l'URL est remplacé par l'ID de compte externe. Si plusieurs produits sont répertoriés dans Google Cloud Marketplace, vous pouvez inclure un paramètre de requête afin d'identifier le produit associé à l'URL.

Utiliser l'API Subscriptions

Après avoir obtenu l'ID de compte externe de l'utilisateur, vous pouvez vérifier à tout moment l'éligibilité à l'assistance de son compte à l'aide de l'API Subscriptions fournie par Google. L'éligibilité est suivie en recherchant les entités appelées "abonnements".

Chaque abonnement possède un identifiant d'abonnement unique et un abonnement unique est créé pour chaque client et pour chaque produit répertorié dans Cloud Marketplace. Vous pouvez donc également interroger un abonnement à l'aide d'un ID d'abonnement pour obtenir des informations supplémentaires sur l'historique d'un client avec votre produit, tel que la date de début de l'abonnement, la date de fin, etc.

Accéder à l'API Subscriptions

L'API Subscriptions étant une API non publique, les développeurs et les projets nécessitant un accès doivent être ajoutés à la liste d'autorisation.

Pour être ajouté à la liste d'autorisation et pouvoir commencer, procédez comme suit :

  1. Envoyez une liste d'adresses e-mail pour les développeurs qui ont besoin d'accéder à la documentation de l'API à votre ingénieur partenaire Google Cloud Marketplace, ou à cloud-partner-onboarding@google.com. Il doit s'agir des adresses e-mail exactes que les développeurs utiliseront pour se connecter à http://console.developers.google.com. Ces développeurs seront ajoutés au groupe qui accorde l'autorisation d'accéder à la documentation de l'API d'abonnements.

  2. Envoyez l'ID de projet de votre produit à votre ingénieur partenaire Google Cloud Marketplace et demandez-lui de l'autoriser à appeler l'API. Vous pouvez ajouter plusieurs projets à la liste d'autorisation si nécessaire.

  3. Activez l'API Cloud Billing en développant le menu dans le coin supérieur gauche de https://console.developers.google.com, en cliquant sur API et services, puis en recherchant et en activant l'API Cloud Billing.

  4. Créez un compte de service OAuth2 associé à votre projet, puis envoyez l'adresse e-mail de ce compte à votre ingénieur partenaire Google Cloud Marketplace. Cet utilisateur sera ajouté à la liste d'autorisation et pourra consulter tous les abonnements pour vous. Cette opération permettra d'autoriser toutes les requêtes, à l'exception de celles qui demandent l'autorisation du client via une boîte de dialogue OAuth.

Comme l'API Subscriptions n'est pas une API publique, elle n'est pas comprise par défaut dans la bibliothèque cliente Python. Si vous envisagez d'utiliser la bibliothèque cliente Python avec cette API, vous devez également contacter votre ingénieur partenaire Google afin d'obtenir de l'aide pour accéder au fichier de découverte.

Dans l'exemple d'initialisation ci-dessous, le nom du fichier de découverte correspond au chemin vers lequel il a été téléchargé.

   # Load the local copy of the discovery document
   f = file(os.path.join(os.path.dirname(__file__),
         "cloudbilling-subscriptions_discovery.json"), "r")
   discovery = f.read()
   f.close()

   # Construct a service from the local documents
   service = build_from_document(discovery,
         base="https://www.googleapis.com/",
         http=http)

La bibliothèque cliente est également compatible avec l'authentification OAuth à l'aide des identifiants client et des comptes de service OAuth2. Pour en savoir plus, consultez la documentation OAuth 2.0 dans la bibliothèque cliente des API Google pour Python.

Interroger l'API Subscriptions

Pour pouvoir accéder aux données d'abonnement, vous devez créer un compte de service OAuth2 et nous indiquer le compte avec lequel vous souhaitez autoriser les requêtes d'API. Google permettra ensuite à ce compte de service de consulter les abonnements de tous vos clients. Pour en savoir plus, reportez-vous à la page Utiliser OAuth 2.0 pour l'authentification serveur à serveur.

L'API est une API RESTful en lecture seule qui renvoie des ressources d'abonnement, qui peuvent être utilisées pour obtenir les informations suivantes :

  • name : identifiant associé à une seule ressource d'abonnement.
  • externalAccountId : identifiant associé à un seul compte de facturation.
  • version : numéro de version mis à jour à chaque modification de l'enregistrement. Cela permet de détecter facilement les modifications depuis la dernière lecture.
  • statut : correspond à l'une des valeurs suivantes :
    • ACTIVE : l'abonnement est actuellement actif et le client devrait pouvoir recevoir une assistance de votre part. Un abonnement est considéré comme actif si le compte a eu une machine virtuelle active au cours des 30 derniers jours.
    • COMPLETE : l'abonnement n'est plus actif, car le client ne dispose d'aucune VM active exécutée avec votre produit et n'a pas effectué de tâche depuis 30 jours.

  • subscribedResources : liste des ressources couvertes par l'abonnement.
  • startDate : date de début de l'abonnement, sous forme de chaîne au format RFC 3339.
  • endDate : date de fin de l'abonnement (si elle est terminée) au format RFC 3339.
  • Étiquette du dernier horodatage de pulsation (avec clé) : la valeur de cette étiquette indique l'horodatage de la dernière pulsation de toute machine virtuelle exécutant le produit. Exemple : cloudmarketplacepartner.googleapis.com/last_heartbeat_us.

Lorsqu'un client clique sur le lien pour accéder à votre site à partir de Google Cloud Console, vous devez vérifier qu'il est autorisé à utiliser le lien en envoyant les requêtes suivantes:

  1. Répertoriez les abonnements associés à l'ID de compte externe
  2. Localisez l'abonnement actif pour le produit
  3. Obtenez les informations d'abonnement grâce à l'ID d'abonnement

Si le client est un utilisateur autorisé, la requête aboutit. Si ce n'est pas le cas, l'appel renvoie un code d'erreur non autorisé (HTTP 403).

Pour effectuer cette démarche, vous devez demander au client l'autorisation de consulter ses données d'abonnement lors du processus d'inscription à l'aide d'un flux de demande OAuth standard.

Les requêtes ultérieures d'actualisation des données d'abonnement utilisent le compte de service créé précédemment.

Flux d'enregistrement du service client

Une fois qu'un client a déployé votre produit via Cloud Marketplace ou via les API Compute Engine, Google Cloud Console affiche un lien vers votre site pour finaliser l'inscription à l'assistance. Le lien inclut l'ID de compte externe associé au compte.

Votre site doit permettre au client de créer un compte et comporter toutes les informations de contact nécessaires. Google ne vous fournit aucune information personnelle concernant le client. Il vous incombe également de maintenir un mappage entre le compte du client et l'ID de compte externe fourni par Google.