Мотивация
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 для отправки пользователю уведомления о статусе тарифного плана.
Описание API
Рисунок 3. Взаимодействие GTAF-DPA, когда DPA делится статусом тарифного плана с GTAF.
Приложения могут получать информацию о статусе тарифного плана, передаваемую в GTAF, одним из двух способов:
- UE обращается в GTAF за информацией о статусе тарифного плана:
- Оператор DPA использует API обмена данными для передачи статуса тарифного плана пользователя в GTAF. GTAF хранит статус тарифного плана и связанный с ним ключ пользователя до истечения срока действия, указанного оператором.
- Приложение Google, работающее на UE, запрашивает информацию о состоянии тарифного плана, используя внутренний API Google. В запросе приложение указывает ключ пользователя .
- Если приложение может использовать кэшированный статус тарифного плана, GTAF использует ключ пользователя для поиска статуса тарифного плана. Затем GTAF возвращает этот статус приложению.
- GTAF передает информацию о статусе тарифного плана в UE:
- При необходимости статус тарифного плана, полученный от оператора, напрямую передается в пользовательское устройство. В частности, переданный статус тарифного плана используется для обновления кэша модуля «Мобильный тарифный план» в сервисах Google Play.
Статус тарифного плана обмена данными
DPA использует HTTPS-запрос POST для создания и обновления существующей записи о статусе тарифного плана, который будет использоваться клиентом. В настоящее время GTAF поддерживает mobiledataplan и youtube в качестве допустимых идентификаторов клиента. Ниже приведен пример запроса для оператора с ASN 12345 и ключом пользователя abcdef, предоставляющего информацию о тарифном плане клиенту GTAF для YouTube :
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus
Тело запроса является экземпляром 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, как правило, не подлежат повторению. В разделе «Случаи ошибок» подробно описаны сообщения об ошибках от GTAF.
Отправка статуса плана для клиента по умолчанию
GTAF поддерживает следующий вызов, в котором оператор отправляет статус тарифного плана без указания клиента, для которого он может быть использован. В этом случае мы предполагаем, что статус тарифного плана предназначен для клиента mobiledataplan , и оператор намерен отправить уведомление пользователю. Тело запроса представляет собой экземпляр PlanStatus.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Интернационализация
Для поддержки интернационализации DPA должен знать предпочитаемый язык пользователя даже без прямого запроса от GTAF. Для решения этой проблемы запрос к конечной точке CPID МОЖЕТ включать заголовок Accept-Language в зависимости от доступа клиента к языковым настройкам пользователя. Если заголовок включен, то человекочитаемые строки в обновлениях, отправляемых DPA через API MDP, должны использовать настройки, указанные в запросе CPID.
DPA МОЖЕТ обновлять языковые настройки пользователя при получении запроса от GTAF с заголовком Accept-Language и использовать обновленные пользовательские настройки для определения языкового кода в будущих запросах к GTAF.
DPA ДОЛЖЕН указывать язык, используемый для видимых пользователю строк, с помощью languageCode . GTAF использует его для формирования заголовка и текста уведомлений, отображаемых пользователю.