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 de données d'un utilisateur (identifié par une clé utilisateur) à GTAF. Sur cette page, nous décrivons le mécanisme par lequel ces mises à jour peuvent être envoyées à 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'il soit utilisé par un client Google.

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 de solde faible à l'utilisateur.

Identifier les utilisateurs concernés

Le DPA a besoin d'un moyen de déterminer les données utilisateur à envoyer à GTAF. Le GTAF s'attend à recevoir des informations pour les utilisateurs suivants :

CPID actifs : utilisateurs disposant de CPID actifs. Tant que les CPID générés par le point de terminaison CPID ne sont pas valides, le DPA DOIT envoyer des informations sur le forfait de données d'un utilisateur. Si l'en-tête Accept-Language a été défini au moment de la création du CPID, les chaînes lisibles par l'utilisateur dans l'état du forfait de données DOIVENT être dans cette langue.
MSISDN enregistrés : pour diffuser des applications ayant accès au MSISDN, GTAF enregistrera le MSISDN auprès de DPA, comme décrit dans la section Enregistrement du MSISDN de l'API Data Plan Agent. Une fois le MSISDN enregistré, la DPA DOIT envoyer des informations sur le forfait de données de l'utilisateur jusqu'à l'expiration de l'enregistrement.

Description de l'API

Partager l'état du forfait de données

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 Internet de deux manières :

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.
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. Le GTAF renvoie ensuite cet état à l'UE.
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.

Interaction entre GTAF et DPA

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

{
  "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.

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

GTAF continue de prendre en charge 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 a l'intention d'envoyer une notification à l'utilisateur. Le corps de la requête est le même pour le cas d'utilisation par client et le cas d'utilisation client par défaut.

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. Si l'en-tête est inclus, les chaînes lisibles par l'utilisateur dans les mises à jour que le DPA envoie à l'aide de l'API MDP doivent utiliser les paramètres fournis dans la requête CPID.