Interfejs API udostępniania mobilnej transmisji danych Google

Motywacja

Interfejs Google Mobile Data Plan Sharing API umożliwia operatorowi wysyłanie do GTAF informacji o abonamencie 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 do GTAF stanu abonamentu na dane, który jest wykorzystywany przez 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ńczą się dane, operator może przesłać do GTAF aktualizację stanu pakietu danych, która może być następnie wykorzystana przez GTAF do wysłania użytkownikowi powiadomienia o niskim saldzie.

Identyfikowanie odpowiednich użytkowników

Dostawca platformy danych musi mieć możliwość określenia, dane których użytkowników należy wysłać do GTAF. GTAF oczekuje aktualizacji dotyczących tych użytkowników:

  1. Aktywne identyfikatory CPID: użytkownicy z aktywnymi identyfikatorami CPID. Dopóki identyfikatory CPID wygenerowane przez punkt końcowy CPID są ważne, dostawca danych powinien wysyłać aktualizacje dotyczące pakietu danych użytkownika. Jeśli Accept-Language nagłówek został ustawiony w momencie tworzenia identyfikatora CPID, ciągi znaków czytelne dla człowieka w stanie planu danych MUSZĄ być w tym języku.
  2. Zarejestrowane numery MSISDN: aby obsługiwać aplikacje, które mają dostęp do numeru MSISDN, GTAF zarejestruje numer MSISDN w DPA zgodnie z opisem w sekcji rejestracja numeru MSISDN w interfejsie Data Plan Agent API. Po zarejestrowaniu numeru MSISDN platforma DPA POWINNA wysyłać aktualizacje dotyczące pakietu danych użytkownika do momentu wygaśnięcia rejestracji.

Opis interfejsu API

Stan udostępniania pakietu danych

Rysunek 3. Interakcja GTAF-DPA, gdy DPA udostępnia GTAF stan abonamentu na transmisję danych.

Aplikacje mogą otrzymywać informacje o stanie abonamentu na 2 sposoby:

  1. UE wywołuje GTAF w celu uzyskania informacji o stanie abonamentu:
    1. Umowa DPA operatora korzysta z interfejsu Data Plan Sharing API, aby przekazywać stan pakietu danych użytkownika do GTAF. GTAF przechowuje stan planu i powiązany z nim klucz użytkownika.
    2. 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.
    3. 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 UE.
  2. GTAF przesyła do UE informacje o stanie abonamentu na dane:
    1. W odpowiednich przypadkach stan pakietu danych otrzymany od operatora jest bezpośrednio przesyłany do urządzenia.

GTAF-DPA Interaction

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

{
  "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.

Wypychanie stanu planu do domyślnego klienta

GTAF nadal obsługuje to wywołanie, w którym stan planu jest przesyłany przez operatora bez określania klienta, dla którego można go używać. W tym przypadku zakładamy, że stan planu jest przeznaczony dla klienta mobiledataplan, a operator zamierza wysłać powiadomienie do użytkownika. Treść żądania jest taka sama w przypadku klienta i domyślnego przypadku użycia klienta.

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 wysyłane do punktu końcowego CPID MOŻE zawierać nagłówek Accept-Language. Jeśli nagłówek jest uwzględniony, ciągi znaków czytelne dla człowieka w aktualizacjach wysyłanych przez platformę ochrony danych za pomocą interfejsu MDP API muszą korzystać z ustawień podanych w żądaniu CPID.