API Data Plan Agent

Motivazione

Come indicato nella panoramica, a seconda dei casi d'uso che l'operatore vuole supportare, il DPA deve implementare una combinazione dell'API Google Mobile Data Plan Sharing e dell'API Data Plan Agent. Questo documento descrive l'API Data Plan Agent che Google utilizzerà per identificare i piani tariffari per i dati mobili dell'utente, recuperare informazioni su questi piani e acquistare piani tariffari per i dati.

Autenticazione

Prima che GTAF possa chiamare, il DPA deve autenticare GTAF. Nell'ambito della procedura di onboarding dell'operatore, verificheremo la validità del certificato SSL DPA. Al momento RICHIEDIAMO l'utilizzo di OAuth2 per l'autenticazione reciproca.

Descrizione API

GTAF utilizza la chiave utente, che identifica un abbonato all'operatore, quando interroga il DPA dell'operatore. Quando GTAF esegue query sul DPA per conto di applicazioni che hanno accesso all'MSISDN, GTAF PUÒ utilizzare l'MSISDN. A livello generale, l'API Data Plan Agent proposta comprende i seguenti componenti:

1. Meccanismo per eseguire query sullo stato del piano dati utente.
2. Meccanismo per eseguire query sul DPA per le offerte di piani dati per l'utente.
3. Meccanismo per apportare modifiche al piano dati dell'utente (ad es. acquisto di un nuovo piano).
4. Meccanismo per verificare se un utente è idoneo all'acquisto di un determinato piano dati.
5. Meccanismo per GTAF per registrare gli MSISDN presso l'autorità per la protezione dei dati.
6. Meccanismo per GTAF per verificare se il DPA è in stato integro.

Il resto di questo documento descrive in dettaglio ciascuno di questi componenti dell'API. Se non indicato esplicitamente, tutte le comunicazioni DEVONO avvenire tramite HTTPS (con un certificato SSL DPA valido). A seconda delle funzionalità effettive supportate, un operatore PUÒ scegliere di implementare tutti o un sottoinsieme di questi componenti API.

Esecuzione di query sullo stato del piano dati

Interazione GTAF-DPA

Figura 4. Flusso di chiamata per richiedere e ricevere informazioni sul piano dati dell'utente.

La figura 4 illustra il flusso di chiamate associato a un client che esegue una query sullo stato del piano dati dell'utente e su altre informazioni del piano dati. Questo flusso di chiamate è condiviso per le chiamate API attivate dal client sull'UE.

1. Il client richiede lo stato del piano dati e/o altre informazioni chiamando un'API Google privata. Il client include la chiave utente nella richiesta a GTAF.
2. GTAF utilizza la chiave utente e un identificatore client per eseguire query sul DPA dell'operatore. Gli identificatori client supportati sono mobiledataplan e youtube. Quando il DPA riceve una chiamata con uno di questi identificatori client, DEVE rispondere con le informazioni sul piano che possono essere utilizzate dal client.
3. GTAF restituisce le informazioni richieste al client e le informazioni sul piano vengono memorizzate nella cache di GTAF fino alla scadenza specificata dal DPA.

I passaggi 1 e 3 della Figura 4 sono API Google private e pertanto non vengono descritti ulteriormente. Il passaggio 2 è un'API pubblica descritta di seguito. Il DPA DEVE rispettare l'intestazione HTTP Cache-Control: no-cache quando pubblica queste chiamate API da GTAF.

Stato piano

GTAF invia la seguente richiesta HTTP per ottenere lo stato del piano:

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

Il cliente per conto del quale GTAF contatta l'autorità per la protezione dei dati viene identificato utilizzando CLIENT_ID. A seconda dell'accordo tra il client Google e l'operatore, il DPA può personalizzare la risposta a GTAF. Il formato della risposta è un oggetto JSON che rappresenta un 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
      }
    }
  }
}

La richiesta DEVE includere un'intestazione Accept-Language che indica la lingua in cui devono essere le stringhe leggibili (ad es. le descrizioni dei piani).

Per i piani postpagati, expirationTime DEVE essere la data di ricorrenza del piano (ovvero quando il saldo dei dati viene aggiornato/ricaricato).

Ogni modulo del piano può contenere più categorie di traffico del modulo del piano (PMTCs)to per modellare il caso in cui un modulo del piano è condiviso tra più app (ad es. 500 MB per giochi e musica). I seguenti PMTC sono predefiniti: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Gli operatori contatteranno i singoli team di Google per concordare l'insieme di categorie di traffico e la relativa semantica pertinenti per le diverse applicazioni Google.

Esecuzione di query sulle offerte di piani

GTAF invia la seguente richiesta HTTP per ottenere le offerte dei piani dall'operatore:

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

Il cliente per conto del quale GTAF contatta l'autorità per la protezione dei dati viene identificato utilizzando CLIENT_ID. A seconda dell'accordo tra il client Google e l'operatore, il DPA può personalizzare la risposta a GTAF. Il parametro di contesto facoltativo fornisce il contesto dell'applicazione in cui viene effettuata la richiesta. Di solito si tratta di una stringa che l'applicazione passa all'operatore tramite GTAF.

Il corpo della risposta contiene un'istanza di 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.
}

L'ordine dei piani tariffari nell'array offers POTREBBE determinare l'ordine in cui vengono presentati agli utenti. Inoltre, se l'applicazione può presentare solo x piani a causa di limitazioni dell'interfaccia utente o di altro tipo e la risposta contiene y > x piani, verranno presentati SOLO i primi x piani. GTAF condivide solo fino a 10 piani se l'applicazione che esegue query per le offerte è l'interfaccia utente del piano dati mobili, che fa parte di Google Play Services. per garantire una buona esperienza utente per gli utenti di Google Play Services.

Le stringhe in offerInfo hanno lo scopo di consentire all'utente di leggere ulteriori informazioni sull'offerta e includono anche un modo per disattivare la ricezione di altre offerte all'interno delle applicazioni. Il motivo per cui sono presenti questi campi è che alcuni operatori non hanno bisogno del consenso dell'utente finale per consentire gli acquisti in-app, ma richiedono un meccanismo per consentire agli utenti di disattivare i servizi. Tieni presente che l'operatore DEVE disporre di un meccanismo per soddisfare una richiesta di acquisto per qualsiasi offerta estesa all'utente. Il meccanismo tramite il quale all'utente verrà addebitato l'importo di qualsiasi acquisto può essere comunicato a GTAF utilizzando l'opzione formOfPayment nella risposta.

La richiesta DEVE includere un'intestazione Accept-Language che indica la lingua in cui devono essere le stringhe leggibili (ad es. le descrizioni dei piani).

Acquisto di dati

L'API per i piani di acquisto definisce in che modo GTAF può acquistare piani tramite il DPA. Il GTAF avvia la transazione per acquistare un piano dati per il DPA. La richiesta DEVE includere un identificatore di transazione univoco (transactionId) per tracciare le richieste ed evitare l'esecuzione di transazioni duplicate. La DPA DEVE rispondere con una risposta di esito positivo/negativo.

Transaction Request

Una volta ricevuta una richiesta da un client, GTAF invia una richiesta POST al DPA. L'URL della richiesta è:

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

dove userKey è CPID o MSISDN. Il corpo della richiesta è un'istanza di TransactionRequest che include i seguenti campi:

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

Risposta della transazione

In caso di errore, il DPA restituisce le cause comuni dell'errore. Inoltre, i seguenti codici di errore rappresentano i risultati delle transazioni non riuscite:

• Il DPA restituisce un codice di errore HTTP 400 BAD REQUEST che indica a GTAF che l'ID piano acquistato non è valido.
• L'accordo per il trattamento dei dati restituisce un codice di errore 402 PAYMENT REQUIRED che indica a GTAF che l'utente non dispone di un saldo sufficiente per completare l'acquisto.
• Il DPA restituisce un codice di errore 409 CONFLICT che indica a GTAF che il piano da acquistare non è compatibile con la combinazione di prodotti attuale dell'utente. Ad esempio, se i criteri del piano dati dell'operatore non consentono di combinare piani postpagati e prepagati, il tentativo di acquistare un piano prepagato per un utente postpagato genererà un errore 409 CONFLICT.
• Il DPA restituisce un codice di errore 403 FORBIDDEN che indica a GTAF che la transazione corrente è un duplicato di una transazione emessa in precedenza. Il DPA DOVREBBE restituire le seguenti cause di errore nella risposta:
  • Se la transazione precedente non è andata a buon fine, la causa dell'errore indica il motivo del mancato esito positivo.
  • Se la transazione precedente è andata a buon fine, DUPLICATE_TRANSACTION.
  • Se la transazione precedente è ancora in coda, REQUEST_QUEUED.

Il DPA deve generare una risposta 200 OK solo per una transazione eseguita correttamente o una transazione in coda. In caso di transazione in coda, il DPA deve compilare solo lo stato della transazione e lasciare vuoti gli altri campi della risposta. Il DPA DEVE richiamare GTAF con una risposta una volta gestita una transazione in coda. Il corpo della risposta è un'istanza di TransactionResponse che include i seguenti dettagli:

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

Se planActivationTime non è presente, GTAF PRESUME che il piano sia stato attivato.

Consenso

GTAF MAY issue the following request to pass the user consent preference to the carrier.

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

dove userKey è CPID o MSISDN. Il corpo della richiesta è un'istanza di SetConsentStatusRequest.

In caso di esito positivo, il corpo della risposta deve essere vuoto.

Idoneità

GTAF MAY potrebbe inviare la seguente richiesta di idoneità per verificare se un utente è idoneo all'acquisto di un piano.

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

Tieni presente che planId è l'identificatore univoco del piano che può essere utilizzato per acquistarlo per conto dell'utente (vedi Acquisto di dati). Se planId non è specificato, il DPA DEVE restituire tutti i piani acquistabili dall'utente.

In caso di errore, il DPA restituisce le cause comuni dell'errore. Inoltre, il DPA RESTITUISCE un errore nei seguenti casi:

• La DPA restituisce un codice di errore HTTP 400 BAD REQUEST che indica a GTAF che planId non è valido.
• Il DPA restituisce un codice di errore 409 CONFLICT che indica che planId è incompatibile con il piano dati dell'utente.

In caso contrario, il DPA RESTITUISCE una risposta 200-OK. Il formato di una EligibilityResponse corretta è:

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

Quando la richiesta include un planId, la risposta include solo quel piano. In caso contrario, l'elenco include tutti i piani che l'utente può acquistare. Nel caso in cui planId sia vuoto e il DPA non supporti la restituzione dell'elenco dei piani idonei, DEVE restituire un errore 400 BAD REQUEST.

Endpoint di registrazione MSISDN

Per pubblicare applicazioni che hanno accesso all'MSISDN, GTAF registrerà l'MSISDN con il DPA. GTAF registra l'MSISDN solo quando sono presenti applicazioni pubblicate dall'API Google Mobile Data Plan Sharing, in cui il DPA invia informazioni a GTAF utilizzando le API Google. Per registrare l'MSISDN, GTAF invierà una richiesta POST al DPA:

POST DPA_URL/register

Il corpo della richiesta sarà un'istanza di RegistrationRequest.

{
  "msisdn": "<msisdn_string>"
}

Se la registrazione dell'MSISDN va a buon fine, il DPA DEVE restituire una risposta 200 OK, inclusa RegistrationResponse. Il formato del JSON è:

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

Il DPA DOVREBBE quindi inviare aggiornamenti sul piano dati dell'utente a GTAF fino a quando non sarà trascorso il valore di expirationTime.

Se si verifica un errore, deve essere restituita una ErrorResponse:

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

L'elenco completo dei possibili valori di causa e dei codici di stato HTTP per le diverse condizioni di errore è disponibile qui. In particolare, se viene ricevuta una richiesta di registrazione MSISDN per un utente in roaming o che non ha acconsentito alla condivisione dei dati del piano dati con Google, il DPA DEVE restituire il codice di stato HTTP 403.

API Monitoring

Alcuni casi d'uso richiedono a GTAF di monitorare il DPA e rilevare gli errori DPA. Per questi casi d'uso, abbiamo definito un'API di monitoraggio.

Definizione API

L'API di monitoraggio deve essere disponibile tramite richiesta HTTP GET al seguente URL:

DPA_URL/dpaStatus

Se il DPA e tutti i relativi backend funzionano correttamente, il DPA deve rispondere a questa query con il codice di stato HTTP 200 e un corpo della risposta che contiene un' istanza di DpaStatus.

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

Se il DPA o uno dei suoi backend non funziona correttamente, deve rispondere con il codice di stato HTTP 500 e un corpo della risposta che contiene un'istanza di DpaStatus.

Comportamento DPA

Quando viene rilevato un errore, il DPA deve restituire lo stato "UNAVAILABLE" per tutte le query dpaStatus. Inoltre, deve interrompere l'invio di informazioni sul piano dati con periodi di memorizzazione nella cache lunghi. Potrebbe interrompere l'invio di risposte con periodi di cache lunghi in uno dei due modi seguenti:

1. Inizia a impostare tempi di scadenza della cache brevi.
2. Interrompere completamente l'invio di informazioni sul piano dati.

Comportamento GTAF

GTAF eseguirà il polling di dpaStatus periodicamente. Quando rileva un errore DPA (in base alla risposta "UNAVAILABLE"), svuota la cache per l'operatore.

Casi di errore

In caso di errore, il DPA deve restituire un codice di stato HTTP corrispondente a uno dei seguenti:

• L'utente è attualmente in roaming e la query DPA è disattivata per questo utente. La DPA restituisce un errore 403.
• Il DPA restituisce un codice di errore 404 NOT_FOUND che indica a GTAF che la chiave utente non è valida (ovvero, la chiave utente non esiste).
• Il DPA restituisce un codice di errore 410 GONE che indica a GTAF che il client deve ottenere una nuova chiave utente se key_type = CPID e il CPID è scaduto.
• Il DPA restituisce un codice di errore 501 NOT_IMPLEMENTED che indica che non supporta questa chiamata.
• Servizio temporaneamente non disponibile. Il DPA restituisce un errore 503 SERVICE UNAVAILABLE con l'intestazione Retry-After che indica quando è possibile tentare una nuova richiesta.
• Il DPA restituisce un codice di errore 500 INTERNAL SERVER ERROR per tutti gli altri errori non specificati.
• Il DPA restituisce un errore 429 TOO_MANY_REQUESTS con l'intestazione Retry-After che indica che GTAF sta inviando troppe richieste al DPA.
• La DPA restituisce un errore 409 CONFLICT che indica che la richiesta non può essere completata a causa di un conflitto con lo stato attuale della DPA.

In tutti i casi di errore, il corpo della risposta HTTP DEVE includere un oggetto JSON con maggiori informazioni sull'errore. Il corpo della risposta di errore DEVE contenere un'istanza di ErrorResponse.

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

I valori cause attualmente definiti sono elencati nella documentazione di riferimento dell'API ErrorCause.

In caso contrario, la DPA restituisce un codice 200 OK. Notiamo che questi valori cause vengono utilizzati per tutte le risposte.

Internazionalizzazione

Le richieste GTAF al DPA includono un'intestazione Accept-Language che indica la lingua in cui devono essere le stringhe leggibili (ad es. le descrizioni dei piani). Inoltre, le risposte DPA (PlanStatus, PlanOffers) includono un campo languageCode obbligatorio il cui valore è il codice lingua BCP-47 (ad es. "en-US") della risposta.

Se il DPA non supporta la lingua richiesta dall'utente, può utilizzare una lingua predefinita e utilizzare il campo languageCode per indicare la sua scelta.