Motywacja
Interfejs Google Mobile Data Plan Sharing API umożliwia operatorowi przesyłanie do GTAF informacji o abonamencie na mobilną transmisję danych użytkownika (identyfikowanego za pomocą klucza użytkownika). Na tej stronie opisujemy mechanizm, za pomocą którego te aktualizacje mogą być przesyłane do GTAF, a tym samym do aplikacji Google. Interfejs API umożliwia obecnie dostawcy danych o abonamentach przesyłanie stanu abonamentu do GTAF, aby był on dostępny dla klienta Google.
Uwierzytelnianie
Wszystkie żądania wysyłane do GTAF w ramach interfejsu Data Plan Sharing API muszą być uwierzytelniane za pomocą serwera Google Cloud OAuth2. Żądania muszą być uwierzytelniane jako konto usługi, które zostało dodane do białej listy w Portalu dostawcy usług internetowych w przypadku numeru ASN, który reprezentuje DPA. Dokumentację na temat używania OAuth z kontami usługi Google Cloud znajdziesz w artykule OAuth 2.0 w Google Cloud na potrzeby kont usługi.
Aktualizacje pakietów danych
Obecnie interfejs API udostępniania mobilnej transmisji danych Google umożliwia operatorowi udostępnianie aktualizacji dotyczących abonamentu użytkownika na mobilną transmisję danych:
- Stan pakietu danych: pokazuje aktualny stan pakietu danych użytkownika. Jeśli na przykład użytkownikowi kończy się pakiet danych, operator może przesłać do GTAF aktualizację stanu pakietu danych, która może być następnie wykorzystana przez GTAF do wysłania do użytkownika powiadomienia o stanie pakietu.
Opis interfejsu API
Rysunek 3. Interakcja GTAF-DPA, gdy DPA udostępnia GTAF stan abonamentu na transmisję danych.
Aplikacje mogą otrzymywać informacje o stanie pakietu danych udostępniane GTAF na 2 sposoby:
- UE wywołuje GTAF w celu uzyskania informacji o stanie abonamentu:
- Umowa DPA operatora korzysta z interfejsu Data Plan Sharing API, aby przekazywać stan pakietu danych użytkownika do GTAF. GTAF przechowuje stan abonamentu i powiązany z nim klucz użytkownika do czasu wygaśnięcia określonego przez operatora.
- Aplikacja Google działająca na urządzeniu UE wysyła żądanie informacji o stanie pakietu danych za pomocą wewnętrznego interfejsu API Google. Aplikacja zawiera w żądaniu klucz użytkownika.
- Jeśli aplikacja może używać stanu pakietu danych z pamięci podręcznej, GTAF używa klucza użytkownika, aby wyszukać stan pakietu danych użytkownika. GTAF zwraca ten stan do aplikacji.
- GTAF przesyła do UE informacje o stanie abonamentu na dane:
- W odpowiednich przypadkach stan pakietu danych otrzymany od operatora jest bezpośrednio przesyłany do urządzenia. W szczególności wypchnięty stan abonamentu jest używany do aktualizowania pamięci podręcznej modułu abonamentu na dane mobilne w Usługach Google Play na urządzeniu.
Stan udostępniania pakietu danych
DPA używa żądania HTTPS POST do tworzenia i aktualizowania istniejącego wpisu stanu planu użytkownika, który będzie używany przez klienta. Obecnie GTAF obsługuje mobiledataplan i youtube jako prawidłowe identyfikatory klienta. Oto przykładowe żądanie dotyczące operatora z numerem ASN 12345 i kluczem użytkownika abcdef, który udostępnia informacje o planie GTAF dla klienta youtube:
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus
Treść żądania jest instancją elementu 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"
}
Jeśli żądanie się powiedzie, GTAF zwróci kod odpowiedzi HTTP 200 i wypchnięty wpis planStatus wraz z wpisem powiadomień, jeśli jakiekolwiek powiadomienie zostało wysłane do użytkownika. Jeśli GTAF wykryje problem z żądaniem, zwróci kod stanu HTTP z zakresu 400–499. Jeśli GTAF nie może zrealizować żądania z powodu błędu, zwraca kod HTTP z zakresu 500–599. Żądania, które otrzymują odpowiedź z zakresu 500–599, są uznawane za możliwe do ponowienia, a żądania, które otrzymują odpowiedź z zakresu 400–499, zwykle nie są możliwe do ponowienia. W sekcji Error Cases (Przypadki błędów) znajdziesz szczegółowe wyjaśnienie odpowiedzi o błędach z GTAF.
Wypychanie stanu planu do domyślnego klienta
GTAF obsługuje to wywołanie, w którym operator przesyła stan abonamentu bez określania klienta, dla którego można go używać. W takim przypadku zakładamy, że stan planu jest przeznaczony dla klienta mobiledataplan, a operator zamierza wysłać powiadomienie do użytkownika. Treść żądania jest instancją elementu PlanStatus.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Internacjonalizacja
Aby obsługiwać internacjonalizację, dostawca platformy danych musi znać preferowany język użytkownika nawet bez bezpośredniego żądania ze strony GTAF. Aby rozwiązać ten problem, żądanie do punktu końcowego CPID MOŻE zawierać nagłówek Accept-Language w zależności od dostępu klientów do preferencji językowych użytkownika. Jeśli nagłówek jest uwzględniony, ciągi znaków czytelne dla człowieka w aktualizacjach wysyłanych przez dostawcę platformy danych za pomocą interfejsu MDP API muszą korzystać z ustawień podanych w żądaniu CPID.
DPA MOŻE aktualizować preferencje językowe użytkownika, gdy otrzyma żądanie od GTAF z nagłówkiem Accept-Language, i używać zaktualizowanych preferencji użytkownika do określania kodu języka w przyszłych żądaniach do GTAF.
Platforma DPA MUSI określać język używany w ciągach widocznych dla użytkownika za pomocą parametru languageCode. GTAF używa tych informacji do tworzenia tytułu i treści powiadomień wyświetlanych użytkownikowi.