Motivazione
L'API Google Mobile Data Plan Sharing consente a un operatore di inviare informazioni sul piano dati di un utente (identificato dalla chiave utente) a GTAF. In questa pagina viene descritto il meccanismo che consente l'invio di questi aggiornamenti a GTAF e, di conseguenza, alle applicazioni Google. Attualmente l'API consente alla DPA di inviare lo stato del piano dati a GTAF, che potrà essere utilizzato da un client Google.
Autenticazione
Tutte le richieste API Data Plan Sharing a GTAF devono essere autenticate utilizzando il server OAuth2 di Google Cloud. Le richieste devono essere autenticate come account di servizio autorizzati nel portale ISP per l'ASN rappresentato dall'ETD. Per la documentazione su come utilizzare OAuth con gli account di servizio Google Cloud, consulta Google Cloud OAuth 2.0 per gli account di servizio.
Aggiornamenti del piano dati
Attualmente, l'API di condivisione del piano dati mobili di Google consente a un operatore di condividere gli aggiornamenti sul piano dati di un utente:
- Stato piano dati: acquisisce lo stato attuale del piano dati di un utente. Ad esempio, se un utente sta per esaurire i dati, un operatore può effettuare il push di un aggiornamento dello stato del piano dati a GTAF, che potrà essere utilizzato da GTAF per inviare una notifica con saldo basso all'utente.
Identificare gli utenti pertinenti
L'ETD ha bisogno di un modo per determinare quali utenti possano inviare dati a GTAF. GTAF prevede di ricevere aggiornamenti per i seguenti utenti:
- CPID attivi: utenti con CPID attivi. Finché i CPID generati dall'endpoint CPID non sono validi, l'ETD DEVE inviare aggiornamenti sul piano dati di un utente. Se l'intestazione
Accept-Languageè stata impostata al momento della creazione del CPID, le stringhe leggibili umane nello stato del piano dati DEVONO essere in quella lingua. - MSSDN registrati: per pubblicare applicazioni che hanno accesso al MSISDN, GTAF registra l'MSIDN con DPA come descritto nella sezione msisdn registrazione dell'API Data Plan Agent. Una volta registrato il file MSISDN, DPA DEVE inviare aggiornamenti sul piano dati dell'utente fino alla scadenza della registrazione.
Descrizione API
Condivisione dello stato del piano dati
Figura 3. Interazione GTAF-DPA quando DPA condivide lo stato del piano dati con GTAF.
Le applicazioni possono ricevere informazioni sullo stato dei piani dati in due modi:
- UE chiama GTAF per informazioni sullo stato del piano dati:
- L'ETD dell'operatore utilizza l'API di condivisione del piano dati per trasferire lo stato del piano dati dell'utente a GTAF. GTAF archivia lo stato del piano e la chiave utente associata.
- L'applicazione Google in esecuzione su 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 quindi questo stato alla UE.
- GTAF trasferisce le informazioni sullo stato del piano dati all'UE:
- Se pertinente, lo stato del piano dati ricevuto dall'operatore viene inviato direttamente all'UE.
Interazione GTAF-DPA
La DPA utilizza un POST HTTPS per creare e aggiornare una voce di stato del piano esistente per consentire a un utente di utilizzare un client. Attualmente GTAF supporta mobiledataplan e youtube come identificatori client validi. Ecco una richiesta di esempio per un operatore con asn 12345 e le informazioni del piano di condivisione della chiave utente abcdef 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 ha esito positivo, GTAF restituirà il codice di risposta HTTP 200 e la voce planStatus inviata 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 GTAF, GTAF restituirà un codice HTTP nell'intervallo 500-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 stato piano per client predefinito
GTAF continua a supportare la seguente chiamata, in cui lo stato del piano viene effettuato dall'operatore senza specificare il client per il quale può essere utilizzato. In questo caso, supponiamo che lo stato del piano sia destinato al client mobiledataplan e che l'operatore abbia intenzione di inviare una notifica all'utente. Il corpo della richiesta è lo stesso per il caso d'uso per cliente e per il caso d'uso client predefinito.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Internazionalizzazione
Per supportare l'internazionalizzazione, l'ETD deve conoscere la lingua preferita dell'utente anche senza una richiesta diretta di GTAF. Per risolvere il problema, la richiesta all'endpoint CPID POTREBBE includere un'intestazione Accept-Language. Se l'intestazione è inclusa, le stringhe leggibili leggibili dagli aggiornamenti inviate dall'ETD mediante l'API MDP devono usare le impostazioni fornite nella richiesta CPID.