Interfejs API agenta Data Data

Motywacja

Jak wspomnieliśmy w opisie, w zależności od przypadku użycia, który operator chce obsługiwać, organ ochrony danych musi wdrożyć interfejs Google Mobile Data Plan Share API i interfejs Data DataAgent API. W tym dokumencie opisujemy interfejs API Data Data Agent, którego Google używa do identyfikowania planów mobilnej transmisji danych użytkownika oraz pobierania informacji o tych abonamentach i abonamentach.

Uwierzytelnianie

Aby można było wywołać GTAF, organ ochrony danych musi uwierzytelnić GTAF. W ramach procesu rejestracji operatora sprawdzimy poprawność certyfikatu SSL DPA. Obecnie wymagamy używania protokołu OAuth2 do uwierzytelniania wzajemnego.

Opis interfejsu API

GTAF używa klucza użytkownika, który identyfikuje subskrybenta operatora podczas wysyłania zapytania do organu ochrony danych. Gdy GTAF wysyła zapytania do organu ochrony danych w imieniu aplikacji, które mają dostęp do MSISDN, GTAF MAY może używać MSISDN. Ogólnie rzecz biorąc, proponowany interfejs Data Plan Agent API obejmuje te komponenty:

  1. Mechanizm zapytań o stan planu danych użytkowników.
  2. Mechanizm zapytań do organu ochrony danych o ofertach pakietu danych dla użytkownika.
  3. Mechanizm wprowadzania zmian w pakiecie danych użytkownika (np. zakup nowego abonamentu).
  4. Mechanizm sprawdzający, czy użytkownik może kupić dany pakiet danych.
  5. Mechanizm GTAF do rejestrowania MSISDN w organie ochrony danych.
  6. Mechanizm GTAF sprawdzający, czy organ ochrony danych działa prawidłowo.

Reszta dokumentu zawiera szczegółowe informacje o każdym z tych komponentów interfejsu API. O ile nie stwierdzono inaczej, cała komunikacja MUSI być przeprowadzana przez HTTPS (z ważnym certyfikatem SSL DPA). W zależności od obsługiwanych funkcji operator może wdrożyć wszystkie lub niektóre z tych komponentów API.

Sprawdzanie stanu planu danych

Interakcja GTAF-DPA

Interakcja GTAF-DPA

Rysunek 4. Przebieg rozmowy pozwalający uzyskać informacje o abonamencie użytkownika.

Rysunek 4 przedstawia przepływ połączeń powiązany z klientem, który wysyła zapytania o stan abonamentu użytkownika i inne informacje. Ten przepływ wywołań jest udostępniany w przypadku wywołań interfejsu API wywoływanych przez klienta w UE.

  1. Klient żąda stanu abonamentu danych lub innych informacji, wywołując prywatny interfejs API Google. Klient zawiera klucz użytkownika w żądaniu wysłanym do GTAF.
  2. GTAF używa klucza użytkownika i identyfikatora klienta do wysyłania zapytań do operatora. Obsługiwane identyfikatory klienta to mobiledataplan i youtube. Gdy organ ochrony danych odbierze połączenie z jednym z tych identyfikatorów klienta, MUSI odpowiadać na informacje o pakiecie, które może wykorzystać klient.
  3. GTAF zwraca wymagane dane klientowi, a informacje o abonamencie są przechowywane w pamięci podręcznej przez GTAF do czasu wygaśnięcia określonego przez organ ochrony danych.

Kroki 1 i 3 na rysunku 4 są prywatnymi interfejsami API Google, więc nie są szczegółowo opisane. Krok 2 to publiczny interfejs API opisany poniżej. Podczas wyświetlania tych wywołań interfejsu API GTAF DPA MUSI przestrzegać nagłówka HTTP Cache-Control: no-cache.

Stan planu

GTAF wysyła to żądanie HTTP, aby uzyskać stan planu:

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

Klient, w imieniu którego GTAF kontaktuje się z organem ochrony danych, jest rozpoznawany za pomocą CLIENT_ID. W zależności od umowy między klientem Google a operatorem ochrony danych możesz dostosować odpowiedź do GTAF. Format odpowiedzi to obiekt JSON reprezentujący 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"
    }]
  }],
  "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"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

Żądanie SHALL musi zawierać nagłówek Accept-Language wskazujący język, w którym powinny znajdować się ciągi tekstowe zrozumiałe dla człowieka (np. opis planu).

W przypadku abonamentów po wykonaniu usługi expirationTime MUSI być datą powtarzania abonamentu (tj. po odświeżeniu lub ponownym przesłaniu danych).

Każdy moduł planu może zawierać wiele kategorii ruchu modułu planu (PMTCs)aby modelować sytuację, w której moduł jest udostępniany wielu aplikacjom (np. 500 MB na gry i muzykę). Poniższe prognozy dotyczące przejrzystości i zgody na przetwarzanie danych są wstępnie zdefiniowane: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. oczekuje się, że operatorzy skontaktują się z poszczególnymi zespołami Google, aby uzgodnić zestaw kategorii ruchu i ich semantykę odpowiednią dla poszczególnych aplikacji Google.

Zapytania dotyczące planu abonamentowego

GTAF wyświetla następujące żądanie HTTP, aby uzyskać oferty abonamentu od operatora:

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

Klient, w imieniu którego GTAF kontaktuje się z organem ochrony danych, jest rozpoznawany za pomocą CLIENT_ID. W zależności od umowy między klientem Google a operatorem ochrony danych możesz dostosować odpowiedź do GTAF. Opcjonalny parametr kontekstu dostarcza kontekst aplikacji, w której przesyłane jest żądanie. Zwykle jest to ciąg znaków, który aplikacja przekazuje do operatora przez GTAF.

Treść odpowiedzi zawiera instancję PlanOffer.

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850"
      }
    ],
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

Kolejność planów danych w tablicy offers może decydować o kolejności, w jakiej plany danych są wyświetlane użytkownikom. Jeśli aplikacja może wyświetlać tylko plany x ze względu na interfejs lub inne ograniczenia, a odpowiedź zawiera plany y > x, ale widoczne są tylko pierwsze plany x. GTAF udostępnia maksymalnie 10 abonamentów, jeśli zapytanie o oferty to interfejs mobilnego pakietu danych, który jest częścią Usług Google Play. Gwarantuje to wygodę użytkownikom usług Google Play.

Ciągi w offerInfo mają umożliwiać użytkownikowi zapoznanie się z ofertą i rezygnację z otrzymywania kolejnych ofert z aplikacji. Powodem może być fakt, że niektórzy operatorzy nie potrzebują zgody użytkownika na zakup w aplikacji. W celu umożliwienia użytkownikom wycofania zgody wymaga on mechanizmu. Pamiętaj, że operator MUSI mieć mechanizm realizacji żądania zakupu dowolnej oferty rozszerzonej dla użytkownika. Mechanizm, za pomocą którego użytkownik będzie obciążany za dowolny zakup, można przekazać GTAF za pomocą opcji formOfPayment w odpowiedzi.

Żądanie SHALL musi zawierać nagłówek Accept-Language wskazujący język, w którym powinny znajdować się ciągi tekstowe zrozumiałe dla człowieka (np. opis planu).

Zakup danych

Interfejs API planu zakupów określa sposób, w jaki GTAF może kupować plany przez organ ochrony danych. Umowa GTAF inicjuje transakcję zakupu jednego pakietu danych dla organu ochrony danych. Żądanie musi zawierać unikalny identyfikator transakcji (transactionId), aby można było śledzić żądania i uniknąć wykonywania zduplikowanych transakcji. Aneks o przetwarzaniu danych musi reagować na powodzenie lub niepowodzenie.

Żądanie transakcji

Po otrzymaniu żądania od klienta GTAF wysyła żądanie POST do Aneksu o przetwarzaniu danych. Adres URL żądania to:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

gdzie userKey to CPID lub MSISDN. Treść żądania to wystąpienie TransactionRequest, które zawiera te pola:

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

Odpowiedź transakcji

Organ ochrony danych w przypadku błędu zwraca typowe przyczyny błędów. Oprócz tego poniższe kody błędów odpowiadają wynikom nieudanych transakcji:

  • Aneks o przetwarzaniu danych zwraca kod błędu 400 BAD REQUEST, który informuje GTAF, że kupiony identyfikator pakietu jest nieprawidłowy.
  • Aneks o przetwarzaniu danych zwraca kod błędu WYMAGANY PAYMENT 402, który wskazuje, że użytkownik nie ma wystarczających środków, by dokończyć zakup.
  • Organ ochrony danych zwraca kod błędu 4F (409), który wskazuje, że abonament jest niezgodny z obecnym zestawem usług użytkownika. Jeśli na przykład zasady abonamentu danych nie zezwalają na łączenie abonamentów przedpłaconych i przedpłaconych, próba zakupu abonamentu przedpłaconego dla użytkownika abonamentowego spowoduje błąd 409 CONFLICT.
  • Organ ochrony danych zwraca kod błędu 403 FORBIDDEN wskazujący, że bieżąca transakcja jest duplikatem wcześniej zrealizowanej transakcji. Organ ochrony danych powinien zwrócić w odpowiedzi te przyczyny błędów:
    • Jeśli poprzednia transakcja się nie powiodła, wystąpił błąd, który wskazuje przyczynę niepowodzenia.
    • Jeśli poprzednia transakcja zakończyła się powodzeniem, DUPLICATE_TRANSACTION.
    • Jeśli wcześniejsza transakcja jest nadal w kolejce, REQUEST_QUEUED.

Aneks DPA SHALL generuje odpowiedź 200-OK tylko w przypadku udanej transakcji lub transakcji w kolejce. W przypadku transakcji w kolejce Aneks o przetwarzaniu danych wypełni tylko stan transakcji i pozostawi pozostałe pola odpowiedzi. Organ ochrony danych musi zwrócić GTAF z odpowiedzią, gdy transakcja zostanie przetworzona. Treść odpowiedzi to wystąpienie parametru TransactionResponse, które zawiera te informacje:

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

Jeśli brakuje planActivationTime, GTAF SHALL zakłada, że abonament został aktywowany.

GTAF może wysłać poniższe żądanie, aby przekazać operatorowi preferencje dotyczące zgody użytkownika.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

gdzie userKey to CPID lub MSISDN. Treść żądania to wystąpienie SetConsentStatusRequest.

Jeśli operacja się uda, treść odpowiedzi powinna być pusta.

Dostępność

GTAF MOŻE wysłać następujące żądanie, aby sprawdzić, czy użytkownik może kupić abonament.

GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}

Pamiętaj, że planId to unikalny identyfikator planu, którego możesz użyć do zakupu abonamentu w imieniu użytkownika (zobacz Zakup danych). Jeśli planId nie został określony, podmiot DPA MUSI zwrócić wszystkie plany, które może kupić ten użytkownik.

Organ ochrony danych w przypadku błędu zwraca typowe przyczyny błędów. Organ ochrony danych w takiej sytuacji zwraca błąd w tych przypadkach:

  • Organ ochrony danych zwraca kod błędu 400 BAD REQUEST, który informuje GTAF, że planId jest nieprawidłowy.
  • Organ ochrony danych zwraca kod błędu 4F (409), który wskazuje, że parametr planId jest niezgodny z abonamentem użytkownika.

W przeciwnym razie podmiot DPA powinien zwrócić odpowiedź 200-OK. Udało się Warunki odpowiedzi odnoszą się do:

{
  "eligiblePlans":
  [
   {
    "planId": string,   // Plan identifier. Can be used to
                        // refer to the plan during
                        // offers, etc. (req.)
   }
  ]
}

Jeśli żądanie zawiera zmienną planId, odpowiedź zawiera tylko ten plan. W przeciwnym razie lista zawiera wszystkie abonamenty, które użytkownik może kupić. Jeśli żądanie planId jest puste, a organ ochrony danych nie zwraca listy kwalifikujących się planów, MUSI zwrócić błąd 400 BAD REQUEST.

Punkt końcowy rejestracji MSISDN

Aby obsługiwać aplikacje mające dostęp do MSISDN, GTAF zarejestruje MSISDN w Aneksie o przetwarzaniu danych. GTAF rejestruje numer MSISDN tylko wtedy, gdy istnieją aplikacje udostępniane przez interfejs Google Mobile Data Plan Sharing API, w którym Aneks o przetwarzaniu danych wysyła informacje do GTAF za pomocą interfejsów API Google. Aby zarejestrować numer MSISDN, GTAF wyśle żądanie POST do Aneksu o przetwarzaniu danych:

POST DPA_URL/zarejestruj

Treść żądania będzie instancją instancji RegistrationRequest.

{
  "msisdn": "<msisdn_string>"
}

Jeśli rejestracja numeru MSISDN zakończy się powodzeniem, organ DPA MUSI zwrócić odpowiedź 200 OK wraz z rejestracją. Format JSON to:

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

Organ ochrony danych powinien następnie wysyłać do GTAF aktualizacje dotyczące danych użytkownika do czasu, gdy upłynie expirationTime.

W przypadku wystąpienia błędu powinien być zwracany komunikat ErrorResponse:

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

Pełną listę możliwych wartości przyczyn i kodów stanu HTTP dotyczących różnych warunków błędu znajdziesz tutaj. W szczególności, jeśli przesłano prośbę o rejestrację MSISDN w przypadku użytkownika, który działa w roli administratora lub nie chce udostępniać Google danych pakietu danych, podmiot DPA MUSI zwrócić kod stanu HTTP 403.

Monitoring API

W niektórych przypadkach GTAF wymaga monitorowania i wykrycia Aneksu o przetwarzaniu danych. W takich przypadkach określono interfejs Monitoring API.

Definicja interfejsu API

Interfejs Monitoring API powinien być dostępny za pomocą żądania HTTP GET pod tym adresem URL:

DPA_URL/dpaStatus

Jeśli organ ochrony danych i wszystkie jego backendy działają prawidłowo, powinien on podać w odpowiedzi to zapytanie z kodem stanu HTTP 200 i treścią odpowiedzi zgodną z instancją DpaStatus.

{
    "status": enum(DpaStatusEnum),
    "message": "<optional human-readable status description>"
}

Jeśli DPA lub jakikolwiek jej backend nie działają prawidłowo, w odpowiedzi powinien wyświetlić się kod stanu HTTP 500 i treść odpowiedzi zawierająca wystąpienie DpaStatus.

Zachowanie ochrony danych

Po wykryciu błędu organ ochrony danych musi zwrócić stan „"UNavailable"” dla wszystkich zapytań dpaStatus. Musi też zaprzestać wysyłania informacji o abonamentach z długimi okresami przechowywania w pamięci podręcznej. Może to przestać wysyłać odpowiedzi z długimi okresami przechowywania w pamięci podręcznej na jeden z dwóch sposobów:

  1. Zacznij ustawiać krótkie czasy wygaśnięcia pamięci podręcznej.
  2. Zaprzestać wysyłania informacji o abonamencie.

Działanie GTAF

GTAF będzie co jakiś czas sondować stan dpaStatus. Po wykryciu błędu Aneksu o przetwarzaniu danych (na podstawie odpowiedzi „UNOFT;UNavailable"”) wyczyść on pamięć podręczną operatora.

Przypadki błędów

W przypadku błędu organ ochrony danych powinien zwrócić kod stanu HTTP odpowiadający jednemu z tych warunków:

  • Użytkownik korzysta obecnie z roamingu, a zapytania o ochronę danych są dla niego wyłączone. Organ ochrony danych zwraca błąd 403.
  • Aneks o przetwarzaniu danych zwraca kod błędu 404 NOT_FOUND informujący, że GTAF jest nieprawidłowy klucz użytkownika (np. nieistniejący klucz użytkownika).
  • Aneks o przetwarzaniu danych zwraca kod błędu GONEF 410, który wskazuje, że klient powinien otrzymać nowy klucz użytkownika, jeśli key_type = CPID i CPID wygasł.
  • Aneks o przetwarzaniu danych zwraca kod błędu 501 NOT_IMPLEMENTED, który wskazuje, że nie obsługuje tego wywołania.
  • Usługa tymczasowo niedostępna. Organ ochrony danych zwraca błąd 503 SERVICE NIEDOSTĘPNY z nagłówkiem Spróbuj ponownie po tym, jak można spróbować wysłać nowe żądanie.
  • Organ ochrony danych zwraca kod błędu 500 WEWNĘTRZNEGO BŁĘDU SERWERA w przypadku wszystkich nieokreślonych błędów.
  • Aneks o przetwarzaniu danych zwraca błąd 429 TOO_MANY_REQUESTS z nagłówkiem „Spróbuj ponownie”, który wskazuje, że GTAF wysyła zbyt wiele żądań do tego organu.
  • Organ ochrony danych zwraca błąd 409 (CONFLICT), który wskazuje, że nie można zrealizować żądania z powodu konfliktu z jego obecnym stanem.

We wszystkich przypadkach błędu treść odpowiedzi HTTP MUSI zawierać obiekt JSON z dodatkowymi informacjami o błędzie. Treść odpowiedzi na błąd musi zawierać instancję ErrorResponse.

{
  "error": string,
  "cause": enum(ErrorCause)
}

Obecnie zdefiniowane wartości cause są wymienione w dokumentacji API ErrorError.

Jeśli tego nie zrobisz, organ ochrony danych zwróci wartość 200. Zwróć uwagę, że te wartości cause są używane w przypadku wszystkich odpowiedzi.

Internacjonalizacja

Żądania GTAF do Aneksu o przetwarzaniu danych obejmują nagłówek Accept-Language określający język, w którym powinny znajdować się ciągi zrozumiałe dla człowieka (np. opis planu). Odpowiedzi DPA (PlanStatus, PlanOffers) zawierają wymagane pole languageCode, którego wartość to kod języka BCP-47 (np. "en-US") odpowiedzi.

Jeśli Aneks o przetwarzaniu danych nie obsługuje języka, o który prosi użytkownik, może wybrać język domyślny i wybrać odpowiedni język w polu languageCode.