Motivasyon
Genel bakışta belirtildiği gibi, operatörün desteklemek istediği kullanım alanlarına bağlı olarak DPA, Google Mobil Veri Planı Paylaşım API'si ile Veri Planı Aracı API'sinin bir kombinasyonunu uygulamalıdır. Bu dokümanda, Google'ın kullanıcının mobil veri planlarını tanımlamak, bu planlarla ilgili bilgileri almak ve veri planlarını satın almak için kullanacağı Data Plan Agent API'si açıklanmaktadır.
Kimlik doğrulama
GTAF'nin arama yapabilmesi için DPA'nın GTAF'nın kimliğini doğrulaması gerekir. Operatör ilk katılım süreci kapsamında DPA SSL sertifikasının geçerliliğini kontrol edeceğiz. Şu anda karşılıklı kimlik doğrulama için OAuth2 kullanımı GEREKİYOR.
API Açıklaması
GTAF, operatör DPA'sını sorgularken operatörün abonesini tanımlayan kullanıcı anahtarını kullanır. GTAF, MSISDN'ye erişimi olan uygulamalar adına DPA'yı sorgularken GTAF, MSISDN'yi kullanabilir. Genel olarak, önerilen Data Plan Agent API'si aşağıdaki bileşenleri içerir:
- Kullanıcı veri planı durumunu sorgulama mekanizması.
- Veri planı teklifleri için DPA'yı sorgulama mekanizması.
- Kullanıcının veri planında değişiklik yapma mekanizması (ör. yeni bir plan satın alma).
- Bir kullanıcının belirli bir veri planını satın almaya uygun olup olmadığını doğrulama mekanizması.
- MSISDN'leri DPA'ya kaydetme mekanizması.
- DPA'nın sağlıklı bir durumda olup olmadığını doğrulamaya yarayan GTAF mekanizması.
Bu dokümanın geri kalanında, bu API bileşenlerinin her biri ayrıntılı olarak açıklanmaktadır. Açıkça belirtilmediği sürece tüm iletişimlerin HTTPS üzerinden (geçerli bir DPA SSL sertifikasıyla) gerçekleşmesi ZORUNLUDUR. Desteklenen gerçek özelliklere bağlı olarak, bir operatör bu API bileşenlerinin tamamını veya bir alt kümesini uygulamayı SEÇEBİLİR.
Veri Planı Durumunu Sorgulama
GTAF-DPA Etkileşimi
4. Şekil. Kullanıcı veri planı bilgilerini istemek ve almak için arama akışı.
4. şekilde, kullanıcının veri planı durumu ve diğer veri planı bilgileriyle ilgili sorgu yapan bir istemciyle ilişkilendirilen çağrı akışı gösterilmektedir. Bu çağrı akışı, istemcinin UE'de tetiklediği API çağrıları için paylaşılır.
- İstemci, özel bir Google API'yi çağırarak veri planı durumunu ve/veya diğer bilgileri ister. İstemci, GTAF isteğine kullanıcı anahtarını ekler.
- GTAF, operatör DPA'sını sorgulamak için kullanıcı anahtarını ve istemci tanımlayıcısını kullanır. Desteklenen istemci tanımlayıcıları mobiledataplan ve youtube'dur. DPA, bu istemci tanımlayıcılarından biriyle arama aldığında istemci tarafından kullanılabilecek plan bilgilerine yanıt vermelidir.
- GTAF, istenen bilgileri istemciye döndürür ve plan bilgileri, DPA tarafından belirlenen geçerlilik bitiş zamanına kadar GTAF tarafından önbelleğe alınır.
Şekil 4'teki 1. ve 3. adım, özel Google API'leridir ve bu nedenle daha ayrıntılı olarak açıklanmamıştır. 2. adım, aşağıda açıklandığı şekilde herkese açık bir API'dir. DPA, GTAF'den bu API çağrılarını yayınlarken Cache-Control: no-cache HTTP üst bilgisine uymalıdır.
Plan Durumu
GTAF, plan durumunu almak için aşağıdaki HTTP isteğini yayınlar:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
GTAF'nın DPA ile iletişim kurduğu müşteri, CLIENT_ID kullanılarak tanımlanır. DPA, Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak GTAF'ya verilen yanıtı özelleştirebilir. Yanıtın biçimi, PlanStat'u temsil eden bir JSON nesnesidir.
{
"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"
}]
}],
"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"
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 256
}
}
}
}
İstek, okunabilir dizelerin (ör. plan açıklamaları) yer alması gereken dili belirten bir Accept-Language üst bilgisi içermelidir.
Faturalı ödemeler için expirationTime, planın yinelenme tarihi (ZORUNLU veri bakiyesinin yenilendiği/yeniden yüklendiği) olmalıdır.
Her plan modülünde birden fazla Plan Modülü Trafik Kategorisi (PMTCs)bir plan modülünün birden fazla uygulama (ör. oyun ve müzik için 500 MB). Aşağıdaki PMTC'ler önceden tanımlanmıştır: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Operatörlerin, farklı Google uygulamaları ile ilgili trafik kategorileri ve anlamları konusunda anlaşmak üzere her bir Google ekibiyle iletişime geçmesi beklenir.
Plan Tekliflerini Sorgulama
GTAF, operatörden plan teklifleri almak için aşağıdaki HTTP isteğini yayınlar:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
GTAF'nın DPA ile iletişim kurduğu müşteri, CLIENT_ID kullanılarak tanımlanır. DPA, Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak GTAF'ya verilen yanıtı özelleştirebilir. İsteğe bağlı bağlam parametresi, isteğin yapıldığı uygulama bağlamını sağlar. Genellikle bu, uygulamanın GTAF üzerinden operatöre aktardığı bir dizedir.
Yanıt gövdesinde bir PlanOffer örneği bulunur.
{
"offers": [
{
"planName": "ACME Red", // req.
"planId": "turbulent1", // req.
"planDescription": "Unlimited Videos for 30 days.", // req.
"promoMessage": "Binge watch videos.",
"languageCode": "en_US", // req.
"overusagePolicy": "BLOCKED",
"cost": { // req.
"currencyCode": "INR",
"units": "300",
"nanos": 0
},
"duration": "2592000s",
"offerContext": "YouTube",
"trafficCategories": ["VIDEO"],
"quotaBytes": "9223372036850"
}
],
"expireTime": "2019-03-04T00:06:07Z" // req.
}
offers dizisindeki veri planlarının sırası, veri planlarının kullanıcılara sunulma sırasını BELİRTİR. Ayrıca, uygulama kullanıcı arayüzü veya diğer sınırlamalar nedeniyle yalnızca x planlarını sergileyebiliyorsa ve yanıtta y > x planları yer alıyorsa yalnızca ilk x planları sunulur. GTAF, teklif sorgulaması için Google Play Hizmetleri'nin bir parçası olan Mobil Veri Planı kullanıcı arayüzünü kullandığında en fazla 10 plan paylaşır. Bunun amacı, Google Play Hizmetleri kullanıcılarına iyi bir kullanıcı deneyimi sunmaktır.
offerInfo içindeki dizeler, kullanıcının teklif hakkında daha fazla bilgi edinmesini sağlamak için kullanılır ve ayrıca uygulamaların içinden daha fazla teklif almamayı seçmek için bir yöntem içerir. Bu alanlara sahip olmanın nedeni, bazı operatörlerin uygulama içi satın alma işlemlerine izin vermek için son kullanıcı rızasını değil, kullanıcıların kapsam dışında kalmayı seçmesini gerektiren bir mekanizmaya sahip olmasıdır. Operatörün, kullanıcıya sunulan tüm fırsatlar için bir satın alma isteğini yerine getirecek mekanizmaya sahip olması ZORUNLUDUR. Kullanıcıdan herhangi bir satın alma işlemi için ödeme alınacak mekanizma, yanıttaki formOfPayment seçeneği kullanılarak GTAF ile iletişim kurabilir.
İstek, okunabilir dizelerin (ör. plan açıklamaları) yer alması gereken dili belirten bir Accept-Language üst bilgisi içermelidir.
Veri Satın Alma
Satın alma planı API'si, GTAF'nın DPA aracılığıyla planları nasıl satın alabileceğini tanımlar. GTAF, DPA'ya bir veri planı satın alma işlemini başlatır. İstek, istekleri izlemek ve yinelenen işlem yürütmeyi önlemek için benzersiz bir işlem tanımlayıcısı (transactionId) içermelidir. DPA'nın başarılı/başarısız bir yanıtla yanıt vermesi ZORUNLUDUR.
İşlem İsteği
GTAF, istemciden istek aldıktan sonra DPA'ya bir POST isteği gönderir. İsteğin URL'si:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
burada userKey, CPID veya MSISDN'dir. İsteğin gövdesi, aşağıdaki alanları içeren bir TransactionRequest örneğidir:
{
"planId": string, // Id of plan to be purchased. Copied from
// offers.planId field returned from a
// Upsell Offer request,
// if available. (req.).
"transactionId": string, // Unique request identifier (req.)
"offerContext": string, // Copied from from the
// offers.offerContext, if available.
// (opt.)
"callbackUrl": string // URL that the DPA can call back with response once
// it has handled the request.
}
İşlem Yanıtı
DPA, hata durumunda sık karşılaşılan hata nedenlerini DEĞİLDİR. Ayrıca, aşağıdaki hata kodları başarısız işlem sonuçlarını gösterir:
- DPA, GTAF'ya satın alınan plan kimliğinin geçersiz olduğunu gösteren bir 400 BAD REQUEST hata kodu döndürür.
- DPA, GTAF'ye kullanıcının satın alma işlemini tamamlamak için yeterli bakiyeye sahip olmadığını gösteren 402 ÖDEME GEREKLİ bir hata kodu döndürür.
- DPA, GTAF'ye satın alınan planın kullanıcının mevcut ürün karışımıyla uyumlu olmadığını belirten bir 409 CONFLICT hata kodu döndürür. Örneğin, operatör veri planı politikası faturalı ve ön ödemeli planların karıştırılmasına izin vermiyorsa faturalı bir kullanıcı için ön ödemeli plan satın almaya çalışmak 409 CONFLICT hatasına neden olur.
- DPA, GTAF'ye mevcut işlemin önceden yapılmış bir işlemin kopyası olduğunu belirten 403 YASAK hata kodunu döndürür. Veri İşlenmesine İlişkin Değişiklik'in yanıt olarak aşağıdaki hata nedenlerini döndürmesi gerekir:
- Önceki işlem bir hataysa sorunun nedenini gösteren hata nedeni.
- Önceki işlem başarılı olduysa DUPLICATE_TRANSACTION.
- Önceki işlem hâlâ sıradaysa REQUEST_QUEUED.
DPA, yalnızca başarıyla gerçekleştirilen bir işlem veya sıraya alınmış bir işlem için 200 OK yanıtını üretir. Sıraya alınmış bir işlem söz konusuysa DPA yalnızca işlem durumunu doldurur ve yanıttaki diğer alanları boş bırakır. Sıraya alınmış bir işlem gerçekleştirildiğinde DPA'nın GTAF'yı geri çağırması GEREKİR. Yanıt gövdesi, aşağıdaki ayrıntıları içeren bir TransactionResponse örneğidir:
{
"transactionStatus": "SUCCESS",
"purchase": {
"planId": string, // copied from request. (req.)
"transactionId": string, // copied from request. (req.)
"transactionMessage": string, // status message. (opt.)
"confirmationCode": string, // DPA-generated confirmation code
// for successful transaction. (opt.)
"planActivationTime" : string, // Time when plan will be activated,
// in timestamp format. (opt.)
},
// walletInfo is populated with the balance left in the user's account.
"walletBalance": {
"currencyCode": string, // 3-letter currency code defined in ISO 4217.
"units": string, // Whole units of the currency amount.
"nanos": number // Number of nano units of the amount.
}
}
planActivationTime eksikse GTAF, planın etkinleştirildiğini varsayar.
İzin
GTAF, kullanıcı rızası tercihini operatöre iletmek için aşağıdaki isteği verebilir.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
burada userKey, CPID veya MSISDN'dir. İsteğin gövdesi, SetConsentStatusRequest öğesinin bir örneğidir.
Başarılıysa yanıt gövdesi boş olmalıdır.
Uygunluk
GTAF, bir kullanıcının plan satın almaya uygun olup olmadığını kontrol etmek için aşağıdaki uygunluk isteğini gönderebilir.
GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}
planId, planın kullanıcı adına plan satın almak için kullanılabilecek benzersiz tanımlayıcısıdır (Veri Satın Alma'ya bakın).
planId belirtilmezse DPA'nın bu kullanıcı tarafından satın alınabilir tüm planları döndürmesi ZORUNLUDUR.
DPA, hata durumunda sık karşılaşılan hata nedenlerini DEĞİLDİR. Ayrıca DPA aşağıdaki hata durumlarında bir hata YAZIR:
- DPA, GTAF'ya
planIdöğesinin geçersiz olduğunu gösteren bir 400 BAD REQUEST hata kodu döndürür. - DPA,
planIdürününün kullanıcının veri planıyla uyumlu olmadığını belirten bir 409 CONFLICT hata kodu döndürür.
Aksi takdirde, DPA 200 OK yanıtı verir. Başarılı bir uygunlukResponse biçimi şu şekildedir:
{
"eligiblePlans":
[
{
"planId": string, // Plan identifier. Can be used to
// refer to the plan during
// offers, etc. (req.)
}
]
}
İstek bir planId içeriyorsa yanıt yalnızca bu planı içerir. Aksi takdirde liste, kullanıcının satın almaya uygun olduğu tüm planları içerir. planId öğesinin boş olduğu ve DPA'nın uygun planların listesinin döndürülmesini desteklemediği durumlarda 400 BAD REQUEST hatası döndürmesi gerekir.
MSISDN kayıt uç noktası
MSISDN'ye erişimi olan uygulamaları sunmak için GTAF, MSISDN'yi DPA'ya kaydeder. GTAF, MSISDN'yi yalnızca Google Mobil Veri Planı Paylaşım API'si tarafından sunulan uygulamalar olduğunda kaydeder. Bu durumda DPA, Google API'lerini kullanarak bilgileri GTAF'ye gönderir. GTAF, MSISDN'yi kaydetmek için DPA'ya bir POST isteği gönderir:
POST DPA_URL/kayıt
İsteğin gövdesi EnrollmentRequest örneğidir.
{
"msisdn": "<msisdn_string>"
}
MSISDN kaydı başarılı olursa DPA, EnrollmentResponse dahil olmak üzere 200 OK yanıtı döndürmelidir. JSON biçimi şu şekildedir:
{
// msisdn that was registered.
"msisdn": "<msisdn_string>",
// time after which DPA will not send updates to GTAF.
"expirationTime": string
}
DPA, expirationTime tarihine kadar kullanıcının veri planıyla ilgili güncellemeleri GTAF'ya GÖNDERMELİDİR.
Bir hata oluşursa bir ErrorResponse döndürülmelidir:
{
"error": "<error message>",
"cause": enum(ErrorCause)
}
Farklı hata koşullarıyla ilgili olası neden değerlerinin ve HTTP durum kodlarının tam listesini burada bulabilirsiniz. Özellikle, dolaşan veya veri planı bilgilerini Google ile paylaşmayı seçmemiş bir kullanıcı için MSISDN kayıt isteği alınırsa DPA, HTTP durum kodu 403'ü döndürmelidir.
Monitoring API
Bazı kullanım alanları, GTAF'nin DPA'yı izlemesini ve DPA hatalarını tespit etmesini gerektirir. Bu kullanım alanları için bir izleme API'si tanımladık.
API Tanımı
İzleme API'si aşağıdaki URL'de bulunan HTTP GET isteği aracılığıyla kullanılabilir:
DPA_URL/dpaStatus
DPA ve tüm arka uçları doğru şekilde çalışıyorsa DPA, bu sorguya HTTP durum kodu 200 ve DpaStatus örneğini içeren bir yanıt gövdesiyle yanıt vermelidir.
{
"status": enum(DpaStatusEnum),
"message": "<optional human-readable status description>"
}
DPA veya arka uçlarından biri doğru şekilde çalışmıyorsa HTTP durum kodu 500 ve DpaStatus örneğini içeren bir yanıt gövdesiyle yanıt vermelidir.
DPA Davranışı
Bir hata tespit edildiğinde DPA, tüm dpaStatus sorguları için "UNAVAILABLE" durumunu döndürmelidir. Ayrıca, uzun önbellek dönemleri içeren veri planı bilgilerini göndermeyi de bırakmalıdır. Uzun önbellek dönemleri içeren yanıtları göndermeyi iki şekilde sonlandırabilir:
- Kısa önbellek geçerlilik sürelerini ayarlamaya başlayın.
- Veri planı bilgilerinin gönderilmesini tamamen durdurun.
GTAF Davranışı
GTAF, dpaStatus verilerini düzenli olarak ankete ekleyecektir. Bir DPA hatası algıladığında ("Kullanılamıyor" yanıtına dayanarak) operatör önbelleğini temizler.
Hata Durumları
Bir hata olması halinde DPA'nın aşağıdakilerden birine karşılık gelen bir HTTP durum kodu döndürmesi beklenir:
- Kullanıcı şu anda dolaşım gerçekleştiriyor ve bu kullanıcı için DPA sorgusu devre dışı bırakıldı. DPA, 403 hatası döndürür.
- DPA, GTAF'ye kullanıcı anahtarının geçersiz olduğunu (yani, mevcut olmayan kullanıcı anahtarı) belirten bir 404 NOT_FOUND hata kodu döndürür.
- DPA, Gkeyf'e key_type = CPID değerine sahip istemcinin yeni bir kullanıcı anahtarı alması gerektiğini ve CPID'nin süresi dolmuş olduğunu belirten 410 GONE hata kodu döndürür.
- DPA, bu çağrıyı desteklemediğini belirten 501 NOT_IMPLEMENTED hata kodu döndürür.
- Hizmet geçici olarak kullanılamıyor. DPA, yeni bir isteğin ne zaman denenebileceğini gösteren bir Yeniden Deneme-Başlığı başlığını içeren 503 HİZMETİNİ KULLANILAMIYOR.
- DPA, belirtilmemiş tüm diğer hatalar için 500 DAHİLİ SUNUCU hata kodu döndürür.
- DPA, GTAF'ın DPA'ya çok fazla istekte bulunduğunu belirten Yeniden dene-sonra başlığıyla birlikte bir 429 TOO_MANY_REQUESTS hatası döndürür.
- DPA, DPA'nın mevcut durumuyla bir çakışma nedeniyle isteğin tamamlanamadığını belirten 409 CONFLICT hatası döndürür.
Tüm hata örneklerinde HTTP yanıtının gövdesi, hata hakkında daha fazla bilgi içeren bir JSON nesnesi içermelidir. Hata yanıtı gövdesinin bir ErrorResponse örneği içermesi ZORUNLUDUR.
{
"error": string,
"cause": enum(ErrorCause)
}
Şu anda tanımlanmış olan cause değerleri, ErrorCause API referansının bir parçası olarak listelenir.
Aksi takdirde, DPA 200 OK döndürür. Bu cause değerlerinin tüm yanıtlar için kullanıldığını unutmayın.
Uluslararası hale getirme
DPA'ya gönderilen GTAF istekleri, insanların okuyabileceği dizelerin (ör. plan açıklamaları) olması gereken dili belirten bir Accept-Language üstbilgisi içerir. Ayrıca DPA yanıtları (PlanStatus, PlanOffers) değeri BCP-47 dil kodu (ör. yanıt verin.
DPA, kullanıcının istediği dili desteklemiyorsa varsayılan bir dil kullanıp seçimini belirtmek için LanguageCode alanını kullanabilir.