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 użytkowniku (nazywanym kluczem użytkownika). Na tej stronie opisujemy mechanizm, za pomocą którego można przekazywać te aktualizacje do GTAF, a tym samym aplikacji Google. Obecnie interfejs API zezwala Aneksowi o przetwarzaniu danych na przesyłanie danych do GTAF przez klienta Google.

Uwierzytelnianie

Wszystkie żądania do interfejsu GTAF interfejsu API udostępniania danych muszą być autoryzowane za pomocą serwera Google Cloud OAuth2. Żądania muszą być uwierzytelnione jako konto usługi na białej liście w portalu dostawcy usług internetowych dla ASN reprezentowanego przez organ ochrony danych. Informacje o tym, jak używać protokołu OAuth z kontami usług Google Cloud, znajdziesz w artykule Google Cloud OAuth 2.0 dla kont usługi.

Aktualizacje pakietu danych

Obecnie interfejs API udostępniania mobilnej transmisji danych Google umożliwia operatorowi udostępnianie informacji o pakiecie danych użytkownika:

  • Stan abonamentu: rejestruje bieżący stan abonamentu na dane użytkownika. Jeśli na przykład użytkownikowi zabraknie danych, operator może przekazać do GTAF aktualizację stanu planu danych, która może zostać użyta przez GTAF do wysłania powiadomienia o stanie planu.

Opis interfejsu API

Rysunek 3. Interakcja GTAF-DPA, gdy Aneks o przetwarzaniu danych udostępnia GTAF.

Aplikacje mogą otrzymywać informacje o stanie pakietu danych udostępniane GTAF na 2 sposoby:

  1. UE wywołuje GTAF w celu uzyskania informacji o stanie abonamentu:
    1. Aneks o przetwarzaniu danych korzysta z interfejsu API udostępniania danych do przekazywania stanu planu danych użytkownika do GTAF. GTAF przechowuje stan planu i powiązany z nim klucz użytkownika do czasu wygaśnięcia określonego przez operatora.
    2. Aplikacja Google działająca w UE żąda informacji o stanie abonamentu danych za pomocą wewnętrznego interfejsu API Google. Aplikacja zawiera klucz użytkownika.
    3. Jeśli aplikacja może korzystać ze stanu abonamentu danych z pamięci podręcznej, GTAF używa klucza użytkownika, aby sprawdzić stan abonamentu na dane użytkownika. GTAF zwraca ten stan aplikacji.
  2. GTAF przekazuje informacje o stanie planu danych do UE:
    1. W stosownych przypadkach stan abonamentu danych otrzymany od operatora jest przekazywany bezpośrednio do UE. W szczególności stan abonamentu push jest używany do aktualizowania pamięci podręcznej modułu mobilnej transmisji danych na urządzeniu w Usługach Google Play.

Udostępnianie stanu abonamentu danych

Aneks o przetwarzaniu danych wykorzystuje metodę POST do HTTPS, aby utworzyć i zaktualizować istniejącą pozycję stanu abonamentu, która będzie używana przez klienta. Obecnie GTAF obsługuje prawidłowe identyfikatory klientów: mobiledataplan i youtube. Oto przykładowe żądanie operatora korzystającego z klienta youtube obejmującego klucz asn 12345 i udostępniający plan użytkownikowi abcdef:

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus

Treść żądania jest instancją 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 z wpisem powiadomienia, jeśli użytkownik otrzymał powiadomienie. 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 GTAF, GTAF zwróci kod HTTP z zakresu 500–599. Żądania, które otrzymają odpowiedź z zakresu 500–599, są uznawane za ponawiane w zakresie, a żądania, które otrzymały odpowiedź w zakresie 400–499, zwykle nie są ponawiane. Szczegółowe informacje o odpowiedziach na błędy z GTAF znajdziesz w sekcji Case Cases (Przypadki błędów).

Przekazywanie stanu planu na potrzeby domyślnego klienta

GTAF obsługuje to wywołanie, w przypadku którego operator przekazuje stan planu bez określenia klienta, którego może użyć. W tym przypadku zakładamy, że stan planu jest przeznaczony dla klienta mobiledataplan, a operator ma wysłać powiadomienie do użytkownika. Treść żądania jest instancją PlanStatus

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

Internacjonalizacja

Aby można było obsługiwać dane na rzecz internacjonalizacji, organ ochrony danych musi znać preferowany przez użytkownika język, nawet jeśli nie podlega bezpośredniemu żądaniu GTAF. Aby rozwiązać ten problem, żądanie może wysyłać żądanie punktu końcowego CPID, o ile powinien mieć dostęp do preferencji językowych użytkownika. Jeśli nagłówek zawiera nagłówek, wtedy zrozumiałe dla człowieka ciągi aktualizacji, które organ ochrony danych przesyła przy użyciu interfejsu MDP API, muszą używać ustawień podanych w żądaniu CPID.

DPA MAY aktualizuje ustawienia języka użytkownika, gdy otrzyma żądanie od GTAF, używając nagłówka Accept-Language, a następnie na podstawie zmienionych preferencji użytkowników określi kod języka w kolejnych żądaniach GTAF.

Aneks DPA MUSI wskazywać język używany w ciągach znaków widocznych dla użytkowników za pomocą parametru languageCode. GTAF używa go do utworzenia tytułu i treści powiadomień wyświetlanych użytkownikowi.