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

API Google Mobile Data Plan Sharing

Motivation

L'API Google Mobile Data Plan Sharing permet à un opérateur d'envoyer des informations sur le forfait Internet d'un utilisateur (identifié par une clé utilisateur) au GTAF. Sur cette page, nous vous présentons le mécanisme qui permet de transmettre ces mises à jour au GTAF, et donc aux applications Google. L'API permet actuellement à l'APD d'envoyer l'état du forfait Internet au GTAF pour qu'il soit utilisé par un client Google.

Authentification

Toutes les requêtes de l'API Data Partage à GTAF doivent être authentifiées à l'aide du serveur OAuth2 Google Cloud. Les requêtes doivent être authentifiées en tant que compte de service qui a été ajouté à la liste blanche sur le portail du FAI pour le numéro ASN représenté par l'APD. Pour en savoir plus sur l'utilisation d'OAuth avec les comptes de service Google Cloud, consultez la page Google Cloud OAuth 2.0 pour les comptes de service.

Mises à jour du forfait Internet

Actuellement, l'API Google Mobile Data Plan Sharing permet à un opérateur de partager des mises à jour sur le forfait Internet d'un utilisateur:

Data Plan Status (État du forfait de données) : capture l'état actuel du forfait Internet de l'utilisateur. Par exemple, si un utilisateur manque de données, un opérateur peut envoyer une mise à jour de l'état du forfait à GTAF, qui peut ensuite être utilisée par le GTAF pour lui envoyer une notification d'état du forfait.

Description de l'API

Figure 3. Interaction entre le GTAF et le DPA lorsque le DPA partage l'état du forfait de données avec le GTAF.

Les applications peuvent recevoir des informations sur l'état du forfait de données partagées avec le GTAF de l'une des deux manières suivantes:

L'UE appelle le GTAF pour obtenir des informations sur l'état du forfait de données :
1. L'APD de l'opérateur utilise l'API Data Plan Sharing pour transmettre l'état du forfait d'un utilisateur à la GTAF. Le GTAF stocke l'état du forfait et la clé utilisateur associée jusqu'au délai d'expiration spécifié par l'opérateur.
2. L'application Google exécutée sur l'UE demande des informations sur l'état du forfait à l'aide d'une API interne à Google. L'application inclut la clé utilisateur dans sa requête.
3. Si l'application peut utiliser l'état du forfait de données mis en cache, la GTAF utilise la clé utilisateur pour rechercher l'état du forfait de données de l'utilisateur. GTAF renvoie ensuite cet état à l'application.
Le GTAF transmet les informations d'état du forfait à l'UE :
1. Le cas échéant, l'état du forfait de données envoyé par l'opérateur est directement transféré vers l'UE. En particulier, l'état du forfait transféré permet de mettre à jour le cache du module de données mobiles sur l'appareil dans les services Google Play.

État du forfait de données partagé

L'APD utilise une requête POST HTTPS pour créer et mettre à jour une entrée d'état de forfait existante afin qu'un utilisateur puisse l'utiliser. Actuellement, le GTAF est compatible avec mobiledataplan et youtube en tant qu'identifiants client valides. Voici un exemple de requête pour un opérateur ayant les informations de plan de partage ASN 12345 et clé utilisateur abcdef avec GTAF pour le client youtube:

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus

Le corps de la requête est une instance de PlanStatus.

{
  "plans": [{
    "planName": "ACME1",
    "planId": "1",
    "planCategory": "PREPAID",
    "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
    "planModules": [{
      "moduleName": "Giga Plan", // req.
      "trafficCategories": ["GENERIC"],
      "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
      "overUsagePolicy": "BLOCKED",
      "maxRateKbps": "1500",
      "description": "1GB for a month", // req.
      "coarseBalanceLevel": "HIGH_QUOTA"
    }]
  }],
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 569
      }
    }
  },
  "languageCode": "en-US", // req.
  "expireTime": "2018-06-14T08:41:27-07:00", // req.
  "updateTime": "2018-06-07T07:41:22-07:00", // req.
  "title": "Prepaid Plan"
}

Si la requête aboutit, le GTAF affichera le code de réponse HTTP 200 et l'entrée planStatus, avec une entrée de notification, si une notification a été envoyée à l'utilisateur. Si le GTAF identifie un problème avec la requête, il renvoie un code d'état HTTP compris entre 400 et 499. Si la GTAF ne peut pas traiter une requête en raison d'une erreur GTAF, elle renvoie un code HTTP compris dans la plage 500-599. Les requêtes qui reçoivent une réponse située dans la plage 500-599 sont considérées comme récupérables, et celles qui reçoivent une réponse dans la plage 400-499 ne sont généralement pas nouvelles. La section Cas d'erreur explique en détail les réponses d'erreur de la GTAF.

État du forfait Push pour le client par défaut

GTAF est compatible avec l'appel suivant, où l'état du forfait est transmis par l'opérateur sans spécifier le client pour lequel il peut être utilisé. Dans ce cas, nous supposons que l'état du forfait est destiné au client mobiledataplan et que l'opérateur vise à envoyer une notification à l'utilisateur. Le corps de la requête est une instance de PlanStatus.

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef

Internationalization

Pour permettre l'internationalisation, le DPA doit connaître la langue préférée de l'utilisateur, même sans demande directe du GTAF. Pour résoudre ce problème, la requête envoyée au point de terminaison CPID PEUT inclure un en-tête Accept-Language en fonction de l'accès des clients aux préférences linguistiques de l'utilisateur. Si l'en-tête est inclus, les chaînes lisibles dans les mises à jour envoyées par le DPA à l'aide de l'API MDP doivent utiliser les paramètres fournis dans la requête CPID.

Le DPA PEUT mettre à jour les préférences linguistiques de l'utilisateur lorsqu'il reçoit une requête de la GTAF avec un en-tête Accept-Language et utiliser les préférences utilisateur mises à jour pour déterminer le code de langue dans les futures requêtes adressées à GTAF.

Le DPA DOIT spécifier la langue utilisée pour les chaînes visibles de l'utilisateur à l'aide de languageCode. La GTAF l'utilise pour construire le titre et le corps des notifications présentées à l'utilisateur.