Motivation
Mit der Google Mobile Data Plan Sharing API kann ein Mobilfunkanbieter Informationen zum Datentarif eines Nutzers (identifiziert durch den Nutzer-Schlüssel) an GTAF senden. Auf dieser Seite wird der Mechanismus beschrieben, über den diese Updates an GTAF und damit an Google-Anwendungen weitergeleitet werden können. Über die API kann der DPA derzeit den Status des Datenvolumens an GTAF senden, damit er von einem Google-Client verwendet werden kann.
Authentifizierung
Alle Anfragen an die Data Plan Sharing API an GTAF müssen mit dem Google Cloud OAuth2-Server authentifiziert werden. Die Anfragen müssen als Dienstkonto authentifiziert werden, das im ISP-Portal für die ASN, die das DPA repräsentiert, auf die Whitelist gesetzt wurde. Google Cloud OAuth 2.0 für Dienstkonten enthält eine Dokumentation zur Verwendung von OAuth mit Google Cloud-Dienstkonten.
Änderungen am Datentarif
Derzeit ermöglicht die Google Mobile Data Plan Sharing API einem Mobilfunkanbieter, Updates zum Datentarif eines Nutzers zu teilen:
- Status des Datentarifs:Erfasst den aktuellen Status des Datentarifs eines Nutzers. Wenn einem Nutzer beispielsweise die Daten ausgehen, kann ein Mobilfunkanbieter ein Update des Datenvolumenstatus an GTAF senden, das dann von GTAF verwendet werden kann, um dem Nutzer eine Benachrichtigung über ein niedriges Guthaben zu senden.
Relevante Nutzer identifizieren
Die DPA muss wissen, welche Nutzerdaten an GTAF gesendet werden sollen. GTAF erwartet Updates für die folgenden Nutzer:
- Aktive CPIDs: Nutzer mit aktiven CPIDs. Bis die vom CPID-Endpunkt generierten CPIDs gültig sind, SOLLTE die DPA Updates zum Datentarif eines Nutzers senden. Wenn der
Accept-Language-Header zum Zeitpunkt der CPID-Erstellung festgelegt wurde, MÜSSEN die für Menschen lesbaren Strings im Datenplanstatus in dieser Sprache sein. - Registrierte MSISDNs: Für die Bereitstellung von Anwendungen, die Zugriff auf die MSISDN haben, registriert GTAF die MSISDN bei DPA, wie im Abschnitt msisdn registration (MSISDN-Registrierung) der Data Plan Agent API beschrieben. Sobald die MSISDN registriert ist, SOLLTE die DPA bis zum Ablauf der Registrierung Updates zum Datentarif des Nutzers senden.
API-Beschreibung
Status des Datenfreigabeplans
Abbildung 3. GTAF-DPA-Interaktion, wenn DPA den Datenplanstatus mit GTAF teilt.
Anwendungen können auf zwei Arten Informationen zum Datentarifstatus erhalten:
- Das UE ruft GTAF für Informationen zum Datentarifstatus auf:
- Der Betreiber verwendet die Data Plan Sharing API, um den Datenvolumenstatus eines Nutzers an GTAF zu senden. GTAF speichert den Planstatus und den zugehörigen Nutzer-Key.
- Eine auf dem UE ausgeführte Google-Anwendung fordert den Status des Datentarifs über eine interne Google-API an. Die Anwendung enthält den Nutzer-Key in ihrer Anfrage.
- Wenn die Anwendung den Status des zwischengespeicherten Datenvolumens verwenden kann, verwendet GTAF den Nutzerschlüssel, um den Status des Datenvolumens des Nutzers zu ermitteln. GTAF gibt diesen Status dann an das UE zurück.
- GTAF überträgt Informationen zum Status des Datentarifs an das UE:
- Der vom Mobilfunkanbieter empfangene Datenvolumenstatus wird direkt an das UE gesendet.
GTAF-DPA-Interaktion
Die DPA verwendet einen HTTPS-POST, um einen vorhandenen Planeintrag für den Status eines Nutzers zu erstellen und zu aktualisieren, der von einem Client verwendet werden soll. Derzeit unterstützt GTAF mobiledataplan und youtube als gültige Client-IDs. Hier ist ein Beispiel für eine Anfrage für einen Betreiber mit der ASN 12345 und dem Nutzerschlüssel abcdef, der Tarifinformationen für den YouTube-Client mit GTAF teilt:
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"
}
Bei einer erfolgreichen Anfrage gibt GTAF den HTTP-Antwortcode 200 und den übertragenen planStatus-Eintrag mit einem Benachrichtigungseintrag zurück, falls eine Benachrichtigung an den Nutzer gesendet wurde. Wenn GTAF ein Problem mit der Anfrage erkennt, wird ein HTTP-Statuscode im Bereich von 400 bis 499 zurückgegeben. Wenn GTAF eine Anfrage aufgrund eines GTAF-Fehlers nicht abschließen kann, gibt GTAF einen HTTP-Code im Bereich 500–599 zurück. Anfragen, die eine Antwort im Bereich von 500 bis 599 erhalten, gelten als wiederholbar. Anfragen, die eine Antwort im Bereich von 400 bis 499 erhalten, sind in der Regel nicht wiederholbar.
Planstatus-Push für Standardclient
GTAF unterstützt weiterhin den folgenden Aufruf, bei dem der Tarifstatus vom Mobilfunkanbieter übertragen wird, ohne den Client anzugeben, für den er verwendet werden kann. In diesem Fall gehen wir davon aus, dass der Planstatus für den mobiledataplan-Client vorgesehen ist und der Mobilfunkanbieter eine Benachrichtigung an den Nutzer senden möchte. Der Anfragetext ist für den Anwendungsfall „Pro Client“ und den Standardanwendungsfall „Client“ identisch.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Internationalisierung
Zur Unterstützung der Internationalisierung muss die DPA die bevorzugte Sprache des Nutzers kennen, auch ohne direkte Anfrage von GTAF. Um dieses Problem zu beheben, KANN die Anfrage an den CPID-Endpunkt einen Accept-Language-Header enthalten. Wenn der Header enthalten ist, müssen für menschenlesbare Strings in Updates, die der DPA über die MDP API sendet, die Einstellungen verwendet werden, die in der CPID-Anfrage angegeben sind.