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 tramite il quale questi aggiornamenti possono essere inviati a GTAF e quindi alle applicazioni Google. L'API consente attualmente alla DPA di inviare lo stato del piano dati a GTAF affinché venga 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 di stato del piano all'utente.
Descrizione API
Figura 3. Interazione GTAF-DPA quando DPA condivide lo stato del piano dati con GTAF.
Le applicazioni possono ricevere le informazioni sullo stato del piano dati condivise con GTAF 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 fino alla scadenza specificata dall'operatore.
- 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 quindi restituisce questo stato all'applicazione.
- 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. In particolare, lo stato del piano di push viene utilizzato per aggiornare la cache sul dispositivo del modulo Piano dati mobili in Google Play Services.
Condivisione dello stato del piano dati
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
Il corpo della richiesta è un'istanza di 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. Casi di errore spiega in dettaglio le risposte di errore di GTAF.
Push stato piano per client predefinito
GTAF supporta la chiamata seguente 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 intenda inviare una notifica all'utente. Il corpo della richiesta è un'istanza di PlanStatus
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 questo problema, la richiesta all'endpoint CPID POTREBBE includere un'intestazione Accept-Language a seconda dell'accesso dei client alle preferenze della lingua dell'utente. Se l'intestazione è inclusa, le stringhe leggibili da umani inviate negli aggiornamenti che la DPA invia utilizzando l'API MDP devono utilizzare le impostazioni fornite nella richiesta CPID.
L'DPA MAY aggiorna le preferenze della lingua dell'utente quando riceve una richiesta da GTAF con un'intestazione Accept-Language e utilizza le preferenze utente aggiornate per determinare il codice lingua nelle richieste future a GTAF.
L'DPA DEVE specificare la lingua utilizzata per le stringhe visibili all'utente tramite languageCode. GTAF utilizza questo modello per creare il titolo e il corpo delle notifiche mostrate all'utente.