API de uso compartido de planes de datos de Google para celulares

Motivación

La API de Google Mobile Data Plan Sharing permite que un operador envíe información sobre el plan de datos de un usuario (identificado por la clave del usuario) a la GTAF. En esta página, se describe el mecanismo a través del cual estas actualizaciones se pueden enviar a la GTAF y, por lo tanto, a las aplicaciones de Google. Actualmente, la API permite que el DPA envíe el estado del plan de datos al GTAF para que lo consuma un cliente de Google.

Autenticación

Todas las solicitudes a la API de Data Plan Sharing de GTAF deben autenticarse con el servidor de OAuth2 de Google Cloud. Las solicitudes deben autenticarse como una cuenta de servicio que se haya incluido en la lista blanca del ISP Portal para el ASN que representa la DPA. Consulta OAuth 2.0 de Google Cloud para cuentas de servicio para obtener documentación sobre cómo usar OAuth con cuentas de servicio de Google Cloud.

Actualizaciones del plan de datos

Actualmente, la API de Google Mobile Data Plan Sharing permite que un operador comparta actualizaciones sobre el plan de datos de un usuario:

  • Estado del plan de datos: Captura el estado actual del plan de datos de un usuario. Por ejemplo, si a un usuario se le están acabando los datos, un operador puede enviar una actualización del estado del plan de datos al GTAF, que luego podría usar el GTAF para enviar una notificación de saldo bajo al usuario.

Identifica a los usuarios pertinentes

La DPA necesita una forma de determinar qué datos de los usuarios se enviarán a la GTAF. GTAF espera recibir actualizaciones para los siguientes usuarios:

  1. CPIDs activos: Usuarios con CPIDs activos. Hasta que los CPID que generó el extremo de CPID sean válidos, el DPA DEBE enviar actualizaciones sobre el plan de datos de un usuario. Si el encabezado Accept-Language se configuró en el momento de la creación del CPID, las cadenas legibles por humanos en el estado del plan de datos DEBEN estar en ese idioma.
  2. MSISDN registrados: Para publicar aplicaciones que tienen acceso al MSISDN, GTAF registrará el MSISDN con la DPA como se describe en la sección registro de MSISDN de la API del agente del plan de datos. Una vez que se registra el MSISDN, la DPA DEBE enviar actualizaciones sobre el plan de datos del usuario hasta que venza el registro.

Descripción de la API

Estado del plan de uso compartido de datos

Figura 3: Interacción entre GTAF y DPA cuando el DPA comparte el estado del plan de datos con GTAF.

Las aplicaciones pueden recibir información sobre el estado del plan de datos de dos maneras:

  1. El UE llama a GTAF para obtener información sobre el estado del plan de datos:
    1. La DPA del operador usa la API de Data Plan Sharing para enviar el estado del plan de datos de un usuario al GTAF. GTAF almacena el estado del plan y su clave de usuario asociada.
    2. La aplicación de Google que se ejecuta en el UE solicita la información del estado del plan de datos a través de una API interna de Google. La aplicación incluye la clave de usuario en su solicitud.
    3. Si la aplicación puede usar el estado del plan de datos almacenado en caché, GTAF usa la clave del usuario para buscar el estado del plan de datos del usuario. Luego, GTAF devuelve este estado a la UE.
  2. La GTAF envía información sobre el estado del plan de datos al UE:
    1. Cuando es pertinente, el estado del plan de datos que se recibe del operador se envía directamente al UE.

Interacción entre GTAF y DPA

El DPA usa un POST de HTTPS para crear y actualizar una entrada de estado de plan existente para que un cliente la use. Actualmente, GTAF admite mobiledataplan y youtube como identificadores de cliente válidos. A continuación, se muestra un ejemplo de solicitud para un operador con el ASN 12345 y la clave de usuario abcdef que comparte información del plan con GTAF para el cliente 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 solicitud se completa correctamente, GTAF devolverá el código de respuesta HTTP 200 y la entrada planStatus enviada con una entrada de notificaciones si se envió alguna notificación al usuario. Si GTAF identifica un problema con la solicitud, devolverá un código de estado HTTP en el rango de 400 a 499. Si GTAF no puede completar una solicitud debido a una falla, devolverá un código HTTP en el rango de 500 a 599. Las solicitudes que reciben una respuesta en el rango de 500 a 599 se consideran reintentables, y las solicitudes que reciben una respuesta en el rango de 400 a 499 generalmente no son reintentables.

Envío de estado del plan para el cliente predeterminado

GTAF sigue admitiendo la siguiente llamada en la que el operador envía el estado del plan sin especificar el cliente para el que se puede usar. En este caso, suponemos que el estado del plan está destinado al cliente mobiledataplan y que el operador tiene la intención de enviar una notificación al usuario. El cuerpo de la solicitud es el mismo para el caso de uso por cliente y el caso de uso del cliente predeterminado.

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

Internacionalización

Para admitir la internacionalización, el DPA debe conocer el idioma preferido del usuario, incluso sin una solicitud directa del GTAF. Para resolver este problema, la solicitud al extremo del CPID PUEDE incluir un encabezado Accept-Language. Si se incluye el encabezado, las cadenas legibles para las personas en las actualizaciones que el DPA envía con la API de MDP deben usar la configuración proporcionada en la solicitud de CPID.