Motivazione
L'API Google Mobile Data Plan Sharing consente a un operatore di inviare a GTAF informazioni sul piano dati di un utente (identificato dalla chiave utente). In questa pagina viene descritto il meccanismo tramite il quale questi aggiornamenti possono essere inviati a GTAF e quindi alle applicazioni Google. L'API attualmente consente al DPA di inviare lo stato del piano dati a GTAF per essere utilizzato da un client Google.
Autenticazione
Tutte le richieste dell'API Data Plan Sharing a GTAF devono essere autenticate utilizzando il server Google Cloud OAuth2. Le richieste devono essere autenticate come un account di servizio inserito nella lista consentita nel portale ISP per l'ASN rappresentato dal DPA. Consulta OAuth 2.0 per gli account di servizio di Google Cloud per la documentazione su come utilizzare OAuth con gli account di servizio Google Cloud.
Aggiornamenti dei piani dati
Al momento, l'API Google Mobile Data Plan Sharing consente a un operatore di condividere aggiornamenti sul piano dati di un utente:
- Stato del piano dati:acquisisce lo stato attuale del piano dati di un utente. Ad esempio, se un utente sta esaurendo i dati, un operatore può inviare un aggiornamento dello stato del piano dati a GTAF, che a sua volta può utilizzarlo per inviare una notifica di saldo insufficiente all'utente.
Identificare gli utenti pertinenti
Il DPA ha bisogno di un modo per determinare i dati degli utenti da inviare a GTAF. GTAF prevede di ricevere aggiornamenti per i seguenti utenti:
- ID cliente attivi: utenti con ID cliente attivi. Finché i CPID generati dall'endpoint CPID non sono validi, il DPA DOVREBBE inviare aggiornamenti sul piano dati di un utente. Se l'intestazione
Accept-Languageè stata impostata al momento della creazione dell'ID CP, le stringhe leggibili dagli utenti nello stato del piano dati DEVONO essere in quella lingua. - MSISDN registrati: per pubblicare applicazioni che hanno accesso all'MSISDN, GTAF registrerà l'MSISDN con il DPA come descritto nella sezione Registrazione MSISDN dell'API Data Plan Agent. Una volta registrato l'MSISDN, DPA DOVREBBE inviare aggiornamenti sul piano dati dell'utente fino alla scadenza della registrazione.
Descrizione API
Stato del piano dati condiviso
Figura 3. Interazione GTAF-DPA quando DPA condivide lo stato del piano dati con GTAF.
Le applicazioni possono ricevere informazioni sullo stato del piano dati in due modi:
- L'UE chiama GTAF per informazioni sullo stato del piano dati:
- Il DPA dell'operatore utilizza l'API Data Plan Sharing per inviare lo stato del piano dati di un utente a GTAF. GTAF memorizza lo stato del piano e la relativa chiave utente.
- L'applicazione Google in esecuzione sull'UE richiede le informazioni sullo stato del piano dati utilizzando un'API interna di Google. L'applicazione include la chiave utente nella richiesta.
- Se l'applicazione può utilizzare lo stato del piano dati memorizzato nella cache, GTAF utilizza la chiave utente per cercare lo stato del piano dati dell'utente. GTAF restituisce questo stato all'UE.
- GTAF invia all'UE informazioni sullo stato del piano dati:
- Se pertinente, lo stato del piano dati ricevuto dall'operatore viene inviato direttamente all'UE.
Interazione GTAF-DPA
Il DPA utilizza un POST HTTPS per creare e aggiornare una voce di stato del piano esistente per un utente da utilizzare da un client. Al momento GTAF supporta mobiledataplan e youtube come identificatori client validi. Di seguito è riportata una richiesta di esempio per un operatore con ASN 12345 e chiave utente abcdef che condivide le informazioni sul piano con GTAF per il client 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"
}
Se la richiesta riesce, GTAF restituisce il codice di risposta HTTP 200 e la voce planStatus push con una voce di notifica, se è stata inviata una notifica all'utente. Se GTAF identifica un problema con la richiesta, restituirà un codice di stato HTTP compreso tra 400 e 499. Se GTAF non è in grado di completare una richiesta a causa di un errore di GTAF, GTAF restituirà un codice HTTP compreso tra 500 e 599. Le richieste che ricevono una risposta nell'intervallo 500-599 sono considerate riprovabili e le richieste che ricevono una risposta nell'intervallo 400-499 in genere non sono riprovabili.
Push dello stato del piano per il client predefinito
GTAF continua a supportare la seguente chiamata in cui lo stato del piano viene inviato dall'operatore senza specificare il client per cui può essere utilizzato. In questo caso, presupponiamo che lo stato del piano sia destinato al client mobiledataplan e l'operatore intende inviare una notifica all'utente. Il corpo della richiesta è lo stesso per il caso d'uso per client e per il caso d'uso client predefinito.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Internazionalizzazione
Per supportare l'internazionalizzazione, il DPA deve conoscere la lingua preferita dell'utente anche senza una richiesta diretta da parte di GTAF. Per risolvere il problema, la richiesta all'endpoint CPID PUÒ includere un'intestazione Accept-Language. Se l'intestazione è inclusa, le stringhe leggibili dagli utenti negli aggiornamenti inviati dal DPA utilizzando l'API MDP devono utilizzare le impostazioni fornite nella richiesta CPID.