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

Мотивация

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

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

Все запросы API Data Plan Sharing к GTAF должны быть аутентифицированы на сервере Google Cloud OAuth2. Запросы должны быть аутентифицированы с использованием учётной записи службы, внесённой в белый список на портале интернет-провайдера для номера ASN, который представляет DPA. Инструкции по использованию OAuth с учётными записями служб Google Cloud см. в разделе «Google Cloud OAuth 2.0 для учётных записей служб».

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

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

• Статус тарифного плана: отслеживает текущий статус тарифного плана пользователя. Например, если у пользователя заканчивается трафик, оператор может отправить обновление статуса тарифного плана в 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://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"
}

Примечание: Полный формат запросов API Google Mobile Data Plan Sharing описан в справочном разделе .

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

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

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

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

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

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