API обмена тарифными планами Google для мобильных устройств

Мотивация

Google Mobile Data Plan Sharing API позволяет оператору отправлять информацию о тарифном плане пользователя (идентифицируемом по ключу пользователя ) в GTAF. На этой странице мы описываем механизм, с помощью которого эти обновления могут передаваться в GTAF и, таким образом, в приложения Google. В настоящее время API позволяет DPA отправлять статус плана данных в GTAF для использования клиентом Google.

Аутентификация

Все запросы API обмена данными к GTAF должны быть аутентифицированы с использованием сервера Google Cloud OAuth2. Запросы должны быть аутентифицированы как учетная запись службы, внесенная в белый список на портале ISP для ASN, который представляет DPA. См. Google Cloud OAuth 2.0 для учетных записей служб для получения документации о том, как использовать OAuth с учетными записями служб Google Cloud.

Обновления тарифного плана

В настоящее время Google Mobile Data Plan Sharing API позволяет оператору делиться обновлениями о тарифном плане пользователя:

  • Статус плана данных: фиксирует текущий статус плана данных пользователя. Например, если у пользователя заканчиваются данные, оператор может отправить обновление статуса плана данных в GTAF, которое затем может быть использовано GTAF для отправки пользователю уведомления о низком балансе.

Идентификация релевантных пользователей

DPA нужен способ определить, какие данные пользователей отправлять в GTAF. GTAF ожидает получать обновления для следующих пользователей:

  1. Активные CPID : пользователи с активными CPID. До тех пор, пока CPID, сгенерированные конечной точкой CPID, не станут действительными, DPA СЛЕДУЕТ отправлять обновления о плане данных пользователя. Если заголовок Accept-Language был установлен во время создания CPID, то читаемые человеком строки в статусе плана данных ДОЛЖНЫ быть на этом языке.
  2. Зарегистрированные MSISDN : для обслуживания приложений, имеющих доступ к MSISDN, GTAF зарегистрирует MSISDN с помощью DPA, как описано в разделе регистрации msisdn API агента плана данных. После регистрации MSISDN DPA СЛЕДУЕТ отправлять обновления о плане данных пользователя до истечения срока регистрации.

Описание API

Совместное использование статуса тарифного плана

Рис. 3. Взаимодействие GTAF и DPA, когда DPA делится статусом плана данных с GTAF.

Приложения могут получать информацию о состоянии тарифного плана двумя способами:

  1. UE вызывает GTAF для получения информации о статусе тарифного плана:
    1. DPA оператора использует API обмена данными для передачи данных о статусе плана данных пользователя в GTAF. В GTAF хранится статус плана и связанный с ним пользовательский ключ .
    2. Приложение Google, работающее в UE, запрашивает информацию о статусе тарифного плана с помощью внутреннего API Google. Приложение включает пользовательский ключ в свой запрос.
    3. Если приложение может использовать кэшированный статус плана данных, то GTAF использует пользовательский ключ для поиска статуса пользовательского плана данных. Затем GTAF возвращает этот статус в UE.
  2. GTAF отправляет информацию о статусе плана данных в UE:
    1. При необходимости статус плана данных, полученный от оператора, передается непосредственно на UE.

Взаимодействие GTAF-DPA

DPA использует HTTPS POST для создания и обновления существующей записи состояния плана для пользователя, который будет использоваться клиентом. В настоящее время GTAF поддерживает mobiledataplan и youtube в качестве действительных идентификаторов клиентов. Вот пример запроса для оператора с asn 12345 и ключом пользователя abcdef для обмена информацией о плане с GTAF для клиента youtube :

POST https://mobileddataplansharing.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"
}

Если запрос выполнен успешно, GTAF вернет код HTTP-ответа 200 и отправленную запись planStatus с записью уведомлений, если какое-либо уведомление было отправлено пользователю. Если GTAF обнаружит проблему с запросом, он вернет код состояния HTTP в диапазоне 400–499. Если GTAF не может выполнить запрос из-за ошибки GTAF, GTAF вернет код HTTP в диапазоне 500–599. Запросы, которые получают ответ в диапазоне 500–599, считаются допускающими повторную попытку, а запросы, получающие ответ в диапазоне 400–499, как правило, не подлежат повторной попытке.

Планирование статуса Push для клиента по умолчанию

GTAF продолжает поддерживать следующий вызов, когда статус плана передается оператором без указания клиента, для которого он может использоваться. В данном случае мы предполагаем, что статус плана предназначен для клиента мобильного тарифа и оператор намерен отправить уведомление пользователю. Текст запроса одинаков для варианта использования для каждого клиента и варианта использования клиента по умолчанию.

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

Интернационализация

Для поддержки интернационализации DPA должен знать предпочтительный язык пользователя даже без прямого запроса от GTAF. Чтобы решить эту проблему, запрос к конечной точке CPID МОЖЕТ включать заголовок Accept-Language. Если заголовок включен, то удобочитаемые строки в обновлениях, которые DPA отправляет с помощью API MDP, должны использовать параметры, указанные в запросе CPID.