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 trasferiti a GTAF e quindi alle applicazioni Google. L'API attualmente consente all'operatore 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ò essere utilizzato 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 informazioni sullo stato del piano dati condivise con GTAF in uno dei due modi seguenti:
- 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 fino al momento della scadenza specificato dall'operatore.
- 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'applicazione.
- 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. In particolare, lo stato del piano push viene utilizzato per aggiornare la cache sul dispositivo del modulo del piano dati mobili in Google Play Services.
Stato del piano dati condiviso
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
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 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. Error Cases spiega in dettaglio le risposte di errore di GTAF.
Push dello stato del piano per il client predefinito
GTAF supporta 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 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, 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 a seconda dell'accesso dei client alle preferenze della lingua dell'utente. Se l'intestazione è inclusa, le stringhe leggibili negli aggiornamenti che il DPA invia utilizzando l'API MDP devono utilizzare le impostazioni fornite nella richiesta CPID.
Il DPA PUÒ aggiornare le preferenze di lingua dell'utente quando riceve una richiesta da GTAF con un'intestazione Accept-Language e utilizzare le preferenze dell'utente aggiornate per determinare il codice lingua nelle richieste future a GTAF.
Il DPA DEVE specificare la lingua utilizzata per le stringhe visibili all'utente utilizzando languageCode. GTAF lo utilizza per creare il titolo e il corpo delle notifiche mostrate all'utente.