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 de données d'un utilisateur (identifié par une clé utilisateur) à GTAF. Sur cette page, nous décrivons le mécanisme permettant de transmettre ces mises à jour à GTAF et, par conséquent, aux applications Google. L'API permet actuellement au DPA d'envoyer l'état du forfait de données à GTAF pour qu'un client Google puisse l'utiliser.

Authentification

Toutes les requêtes de l'API Data Plan Sharing adressées à GTAF doivent être authentifiées à l'aide du serveur Google Cloud OAuth2. Les requêtes doivent être authentifiées en tant que compte de service figurant sur la liste d'autorisation du portail FAI pour le numéro ASN que représente le DPA. Consultez Google Cloud OAuth 2.0 pour les comptes de service pour savoir comment utiliser OAuth avec les comptes de service Google Cloud.

Mises à jour du forfait de données

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

  • État du forfait de données : indique l'état actuel du forfait de données d'un utilisateur. Par exemple, si un utilisateur est à court de données, un opérateur peut envoyer une mise à jour de l'état du forfait de données à GTAF, qui peut ensuite l'utiliser pour envoyer une notification à l'utilisateur.

Description de l'API

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

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

  1. L'UE appelle GTAF pour obtenir des informations sur l'état du forfait de données :
    1. Le DPA de l'opérateur utilise l'API Data Plan Sharing pour transmettre l'état du forfait de données d'un utilisateur à GTAF. GTAF stocke l'état du forfait et sa clé utilisateur associée jusqu'à l'heure d'expiration spécifiée par l'opérateur.
    2. L'application Google s'exécutant sur l'UE demande des informations sur l'état du forfait de données à 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, GTAF utilise la clé utilisateur pour rechercher l'état du forfait de données de l'utilisateur. GTAF renvoie ensuite cet état à l'application.
  2. GTAF transmet des informations sur l'état du forfait de données à l'UE :
    1. Lorsque cela est pertinent, l'état du forfait de données reçu de l'opérateur est directement transmis à l'UE. En particulier, l'état du forfait transmis est utilisé pour mettre à jour le cache sur l'appareil du module "Forfait de données mobiles" dans les services Google Play.

Partager l'état du forfait de données

Le DPA utilise une requête HTTPS POST pour créer et mettre à jour une entrée d'état de forfait existante pour un utilisateur, qui sera utilisée par un client. Actuellement, GTAF accepte mobiledataplan et youtube comme identifiants client valides. Voici un exemple de demande pour un opérateur avec l'ASN 12345 et la clé utilisateur abcdef partageant des informations sur le forfait 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, GTAF renvoie le code de réponse HTTP 200 et l'entrée planStatus envoyée avec une entrée de notification, le cas échéant. Si GTAF identifie un problème avec la requête, il renvoie un code d'état HTTP compris entre 400 et 499. Si GTAF ne parvient pas à traiter une requête en raison d'un problème, il renvoie un code HTTP compris entre 500 et 599. Les requêtes qui reçoivent une réponse dans la plage 500 à 599 sont considérées comme pouvant être réessayées, tandis que celles qui reçoivent une réponse dans la plage 400 à 499 ne le sont généralement pas. La section Cas d'erreur explique en détail les réponses d'erreur de GTAF.

Notification de l'état du forfait pour le client par défaut

GTAF accepte l'appel suivant, dans lequel 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 a l'intention d'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

Internationalisation

Pour prendre en charge l'internationalisation, le DPA doit connaître la langue préférée de l'utilisateur, même sans demande directe de 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 des utilisateurs. Si l'en-tête est inclus, les chaînes lisibles par l'homme dans les mises à jour que le DPA envoie à l'aide de l'API MDP doivent utiliser les paramètres fournis dans la demande CPID.

Le DPA peut mettre à jour les préférences linguistiques de l'utilisateur lorsqu'il reçoit une requête de 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 par l'utilisateur à l'aide de languageCode. GTAF l'utilise pour créer le titre et le corps des notifications affichées à l'utilisateur.