Interfejs API agenta Data Data

Motywacja

Jak wspomnieliśmy w omówieniu, w zależności od przypadków użycia, które operator chce obsługiwać, dostawca usług danych musi wdrożyć kombinację interfejsu Google Mobile Data Plan Sharing API i interfejsu Data Plan Agent API. W tym dokumencie opisujemy interfejs Data Plan Agent API, którego Google będzie używać do identyfikowania abonamentów na mobilną transmisję danych użytkownika, pobierania informacji o tych abonamentach i kupowania pakietów danych.

Uwierzytelnianie

Zanim GTAF będzie mogła zadzwonić, DPA musi ją uwierzytelnić. W ramach procesu wdrażania operatora sprawdzimy ważność certyfikatu SSL DPA. Obecnie WYMAGAMY używania protokołu OAuth2 do wzajemnego uwierzytelniania.

Opis interfejsu API

GTAF używa klucza użytkownika, który identyfikuje subskrybenta operatora, podczas wysyłania zapytań do platformy DPA operatora. Gdy GTAF wysyła zapytanie do DPA w imieniu aplikacji, które mają dostęp do numeru MSISDN, MOŻE używać tego numeru. Na najwyższym poziomie proponowany interfejs Data Plan Agent API składa się z tych komponentów:

  1. Mechanizm sprawdzania stanu pakietu danych użytkownika.
  2. Mechanizm wysyłania do dostawcy danych zapytań o oferty pakietów danych dla użytkownika.
  3. Mechanizm wprowadzania zmian w planie danych użytkownika (np. zakup nowego planu).
  4. Mechanizm weryfikacji, czy użytkownik może kupić określony pakiet danych.
  5. Mechanizm rejestrowania numerów MSISDN w urzędzie ochrony danych przez GTAF.
  6. Mechanizm, który umożliwia GTAF sprawdzenie, czy DPA jest w dobrym stanie.

W pozostałej części tego dokumentu znajdziesz szczegółowe informacje o każdym z tych komponentów interfejsu API. O ile nie zaznaczono inaczej, cała komunikacja MUSI odbywać się przez protokół HTTPS (z prawidłowym certyfikatem SSL DPA). W zależności od obsługiwanych funkcji operator MOŻE wdrożyć wszystkie lub tylko niektóre z tych komponentów interfejsu API.

Sprawdzanie stanu pakietu danych

GTAF-DPA Interaction

GTAF-DPA Interaction

Rysunek 4. Schemat połączenia umożliwiający wysyłanie próśb o informacje o pakiecie danych użytkownika i ich otrzymywanie.

Ilustracja 4 przedstawia przepływ wywołań związany z zapytaniem klienta o stan abonamentu użytkownika i inne informacje o abonamencie. Ten przepływ wywołań jest wspólny dla wywołań interfejsu API wywoływanych przez klienta na urządzeniu UE.

  1. Klient wysyła żądanie dotyczące stanu pakietu danych lub innych informacji, wywołując prywatny interfejs API Google. Klient dołącza do żądania wysyłanego do GTAF klucz użytkownika.
  2. GTAF używa klucza użytkownika i identyfikatora klienta do wysyłania zapytań do platformy DPA operatora. Obsługiwane identyfikatory klientów to mobiledataplan i youtube. Gdy DPA otrzyma wywołanie z jednym z tych identyfikatorów klienta, MUSI odpowiedzieć informacjami o abonamencie, które mogą być używane przez klienta.
  3. GTAF zwraca klientowi żądane informacje, a informacje o planie są buforowane przez GTAF do czasu wygaśnięcia określonego przez DPA.

Kroki 1 i 3 na rysunku 4 to prywatne interfejsy API Google, dlatego nie są one dalej opisywane. Krok 2 to publiczny interfejs API opisany poniżej. Podmiot przetwarzający dane MUSI respektować nagłówek HTTP Cache-Control: no-cache podczas obsługi tych wywołań interfejsu API z GTAF.

Stan planu

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

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 identyfikowany za pomocą parametru CLIENT_ID. W zależności od umowy między klientem Google a operatorem DPA może dostosować odpowiedź na 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 MUSI zawierać nagłówek Accept-Language wskazujący język, w którym mają być wyświetlane ciągi tekstowe zrozumiałe dla człowieka (np. opisy planów).

W przypadku abonamentów z płatnością z dołu expirationTime MUSI być datą odnowienia abonamentu (czyli datą odświeżenia lub ponownego załadowania pakietu danych).

Każdy moduł abonamentu może zawierać wiele kategorii ruchu modułu abonamentu (PMTCs), aby modelować przypadek, w którym moduł abonamentu jest współdzielony przez wiele aplikacji, np. 500 MB (w przypadku gier i muzyki). Wstępnie zdefiniowane są te PMTC: 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ę, które są istotne w przypadku różnych aplikacji Google.

Wysyłanie zapytań dotyczących ofert pakietów

GTAF wysyła to żądanie HTTP, aby uzyskać od operatora oferty abonamentów:

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 identyfikowany za pomocą parametru CLIENT_ID. W zależności od umowy między klientem Google a operatorem DPA może dostosować odpowiedź na GTAF. Opcjonalny parametr kontekstu zawiera kontekst aplikacji, w którym wysłano żądanie. Zwykle jest to ciąg znaków, który aplikacja przekazuje operatorowi za pomocą 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ść abonamentów w tablicy offers MOŻE określać kolejność, w jakiej są one prezentowane użytkownikom. Jeśli aplikacja może wyświetlać tylko x abonamentów z powodu ograniczeń interfejsu lub innych ograniczeń, a odpowiedź zawiera y > x abonamentów, należy wyświetlić tylko pierwsze x abonamentów. GTAF udostępnia tylko do 10 abonamentów, jeśli aplikacja wysyłająca zapytanie o oferty to interfejs pakietu danych mobilnych, który jest częścią Usług Google Play. Ma to na celu zapewnienie użytkownikom Usług Google Play wygody korzystania z nich.

Ciągi znaków w offerInfo mają umożliwić użytkownikowi uzyskanie więcej informacji o ofercie, a także zapewnić możliwość rezygnacji z otrzymywania kolejnych ofert w aplikacjach. Powodem, dla którego te pola są dostępne, jest to, że niektórzy operatorzy nie wymagają zgody użytkownika na zakupy w aplikacji, ale potrzebują mechanizmu, który umożliwi użytkownikom rezygnację. Pamiętaj, że operator MUSI mieć mechanizm realizacji żądania zakupu w przypadku każdej oferty skierowanej do użytkownika. Mechanizm, za pomocą którego użytkownik zostanie obciążony za zakup, można przekazać do GTAF za pomocą opcji formOfPayment w odpowiedzi.

Żądanie MUSI zawierać nagłówek Accept-Language wskazujący język, w którym mają być wyświetlane ciągi tekstowe zrozumiałe dla człowieka (np. opisy planów).

Zakup danych

Interfejs Purchase Plan API określa, w jaki sposób GTAF może kupować pakiety za pomocą DPA. GTAF inicjuje transakcję zakupu jednego pakietu danych dla DPA. Żądanie MUSI zawierać unikalny identyfikator transakcji (transactionId), który umożliwia śledzenie żądań i zapobiega wykonywaniu zduplikowanych transakcji. Organ ochrony danych MUSI odpowiedzieć, wysyłając komunikat o sukcesie lub niepowodzeniu.

Żądanie transakcji

Gdy GTAF otrzyma żądanie od klienta, wysyła żądanie POST do DPA. 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 instancja TransactionRequest, która 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

W przypadku błędu dostawca platformy danych zwraca typowe przyczyny błędów. Dodatkowo te kody błędów oznaczają nieudaną transakcję:

  • DPA zwraca kod błędu 400 BAD REQUEST, który informuje GTAF, że identyfikator zakupionego abonamentu jest nieprawidłowy.
  • DPA zwraca kod błędu 402 PAYMENT REQUIRED, który informuje GTAF, że użytkownik nie ma wystarczających środków na koncie, aby dokonać zakupu.
  • DPA zwraca kod błędu 409 CONFLICT, który informuje GTAF, że plan, który ma zostać kupiony, jest niezgodny z obecnym zestawem produktów użytkownika. Jeśli na przykład zasady dotyczące abonamentu operatora zabraniają łączenia abonamentów z płatnością z góry i z płatnością z dołu, próba zakupu abonamentu z płatnością z góry dla użytkownika abonamentu z płatnością z dołu spowoduje błąd 409 CONFLICT.
  • DPA zwraca kod błędu 403 FORBIDDEN, który informuje GTAF, że bieżąca transakcja jest duplikatem wcześniej wydanej transakcji. W odpowiedzi platforma DPA POWINNA zwrócić te przyczyny błędu:
    • Jeśli poprzednia transakcja zakończyła się niepowodzeniem, podaj przyczynę błędu.
    • Jeśli poprzednia transakcja została zrealizowana, DUPLICATE_TRANSACTION.
    • Jeśli poprzednia transakcja jest nadal w kolejce, REQUEST_QUEUED.

DPA GENERUJE odpowiedź 200-OK TYLKO W PRZYPADKU SKUTECZNIE ZREALIZOWANEJ LUB OCZEKUJĄCEJ NA REALIZACJĘ TRANSAKCJI. W przypadku transakcji w kolejce dostawca platformy danych powinien wypełnić tylko stan transakcji, a pozostałe pola w odpowiedzi pozostawić puste. Po obsłużeniu transakcji w kolejce organ ochrony danych MUSI wywołać zwrotnie interfejs GTAF, aby przekazać odpowiedź. Treść odpowiedzi to instancja TransactionResponse, która 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 parametru planActivationTime, GTAF uzna, że subskrypcja została aktywowana.

GTAF MOŻE wysłać to żądanie, aby przekazać operatorowi preferencje użytkownika dotyczące zgody.

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

gdzie userKey to CPID lub MSISDN. Treść żądania jest instancją elementu SetConsentStatusRequest.

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

Dostępność

GTAF może wysłać to żądanie weryfikacji, aby sprawdzić, czy użytkownik kwalifikuje się do zakupu abonamentu.

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

Pamiętaj, że planId to unikalny identyfikator subskrypcji, który można wykorzystać do zakupu subskrypcji w imieniu użytkownika (patrz Zakup danych). Jeśli parametr planId nie jest określony, dostawca danych musi zwrócić wszystkie plany, które może kupić dany użytkownik.

W przypadku błędu dostawca platformy danych zwraca typowe przyczyny błędów. Dodatkowo DPA ZWRACA błąd w tych przypadkach:

  • Usługa DPA zwraca kod błędu 400 BAD REQUEST, który informuje usługę GTAF, że planId jest nieprawidłowy.
  • Interfejs DPA zwraca kod błędu 409 CONFLICT, który oznacza, że planId jest niezgodny z abonamentem użytkownika.

W przeciwnym razie platforma DPA ZWRACA odpowiedź 200-OK. Format odpowiedzi EligibilityResponse informującej o powodzeniu:

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

Jeśli żądanie zawiera symbol planId, odpowiedź obejmuje tylko ten plan. W przeciwnym razie lista zawiera wszystkie pakiety, które użytkownik może kupić. Jeśli parametr planId jest pusty, a platforma DPA nie obsługuje zwracania listy kwalifikujących się planów, MUSI zwrócić błąd 400 BAD REQUEST.

Punkt końcowy rejestracji MSISDN

Aby wyświetlać aplikacje, które mają dostęp do numeru MSISDN, GTAF zarejestruje ten numer w DPA. GTAF rejestruje numer MSISDN tylko wtedy, gdy istnieją aplikacje obsługiwane przez interfejs Google Mobile Data Plan Sharing API, w którym podmiot przetwarzający dane wysyła informacje do GTAF za pomocą interfejsów API Google. Aby zarejestrować numer MSISDN, GTAF wyśle żądanie POST do DPA:

POST DPA_URL/register

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

{
  "msisdn": "<msisdn_string>"
}

Jeśli rejestracja numeru MSISDN się powiedzie, dostawca usług cyfrowych MUSI zwrócić odpowiedź 200 OK zawierającą element RegistrationResponse. Format pliku JSON jest następujący:

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

Następnie DPA POWINNA wysyłać do GTAF aktualizacje dotyczące pakietu danych użytkownika, dopóki nie upłynie czas expirationTime.

Jeśli wystąpi błąd, należy zwrócić ErrorResponse:

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

Pełną listę możliwych wartości przyczyny i kodów stanu HTTP w przypadku różnych błędów znajdziesz tutaj. W szczególności, jeśli zostanie odebrane żądanie rejestracji numeru MSISDN użytkownika, który jest w roamingu lub nie wyraził zgody na udostępnianie Google informacji o pakiecie danych, dostawca danych MUSI zwrócić kod stanu HTTP 403.

Monitoring API

W niektórych przypadkach GTAF musi monitorować DPA i wykrywać jego awarie. W przypadku tych zastosowań zdefiniowaliśmy interfejs API monitorowania.

Definicja interfejsu API

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

DPA_URL/dpaStatus

Jeśli DPA i wszystkie jego systemy backendowe działają prawidłowo, DPA powinien odpowiedzieć na to zapytanie kodem stanu HTTP 200 i treścią odpowiedzi zawierającą instancję DpaStatus.

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

Jeśli DPA lub którykolwiek z jego backendów nie działa prawidłowo, powinien odpowiedzieć kodem stanu HTTP 500 i treścią odpowiedzi zawierającą instancję DpaStatus.

DPA Behavior

W przypadku wykrycia awarii platforma DPA musi zwracać stan „UNAVAILABLE” w przypadku wszystkich zapytań dpaStatus. Musi też zaprzestać wysyłania informacji o pakietach danych z długimi okresami przechowywania w pamięci podręcznej. Może przestać wysyłać odpowiedzi z długim okresem ważności pamięci podręcznej na 2 sposoby:

  1. Zacznij ustawiać krótkie czasy wygaśnięcia pamięci podręcznej.
  2. całkowicie zaprzestać wysyłania informacji o pakiecie danych;

Zachowanie GTAF

GTAF będzie okresowo sprawdzać stan dpaStatus. Gdy wykryje błąd DPA (na podstawie odpowiedzi „UNAVAILABLE”), wyczyści pamięć podręczną operatora.

Przypadki błędów

W przypadku błędu platforma DPA powinna zwrócić kod stanu HTTP odpowiadający jednemu z tych kodów:

  • Użytkownik jest obecnie w roamingu, a zapytanie DPA jest dla niego wyłączone. Platforma DPA zwraca błąd 403.
  • Platforma DPA zwraca kod błędu 404 NOT_FOUND, który informuje GTAF, że klucz użytkownika jest nieprawidłowy (tzn. nie istnieje klucz użytkownika).
  • Platforma DPA zwraca kod błędu 410 GONE, który informuje GTAF, że klient powinien otrzymać nowy klucz użytkownika, jeśli key_type = CPID, a identyfikator CPID wygasł.
  • DPA zwraca kod błędu 501 NOT_IMPLEMENTED, co oznacza, że nie obsługuje tego wywołania.
  • Usługa tymczasowo niedostępna. Platforma DPA zwraca kod 503 SERVICE UNAVAILABLE z nagłówkiem Retry-After, który wskazuje, kiedy można spróbować wysłać nowe żądanie.
  • W przypadku wszystkich innych nieokreślonych błędów platforma DPA zwraca kod błędu 500 INTERNAL SERVER ERROR.
  • Organ ochrony danych zwraca błąd 429 TOO_MANY_REQUESTS z nagłówkiem Retry-After, który wskazuje, że GTAF wysyła do organu ochrony danych zbyt wiele żądań.
  • DPA zwraca błąd 409 CONFLICT, który wskazuje, że nie można zrealizować żądania z powodu konfliktu z bieżącym stanem DPA.

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

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

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

W przeciwnym razie platforma DPA zwraca kod 200 OK. Zauważ, że te wartości cause są używane we wszystkich odpowiedziach.

Internacjonalizacja

Żądania GTAF wysyłane do DPA zawierają nagłówek Accept-Language wskazujący język, w którym mają być wyświetlane ciągi znaków czytelne dla człowieka (np. opisy planów). Dodatkowo odpowiedzi interfejsu DPA (PlanStatus, PlanOffers) zawierają wymagane pole languageCode, którego wartością jest kod języka BCP-47 (np. „en-US”) odpowiedzi.

Jeśli platforma DPA nie obsługuje języka, o który prosi użytkownik, może użyć języka domyślnego i wskazać go w polu languageCode.