Veri Planı Aracı API'sı

Motivasyon

Genel bakış bölümünde belirtildiği gibi, operatörün desteklemek istediği kullanım alanlarına bağlı olarak DPA'nın Google Mobil Veri Planı Paylaşımı API'si ile Veri Planı Aracı API'sinin bir kombinasyonunu uygulaması gerekir. Bu belgede, Google'ın kullanıcının mobil veri planlarını belirlemek, bu planlarla ilgili bilgileri almak ve veri planları satın almak için kullanacağı Data Plan Agent API açıklanmaktadır.

Kimlik doğrulama

GTAF arama yapmadan önce DPA, GTAF'yi doğrulamalıdır. Operatörün ilk katılım süreci kapsamında, DPA SSL sertifikasının geçerliliği kontrol edilir. Şu anda karşılıklı kimlik doğrulama için OAuth2 KULLANIMI ZORUNLUDUR.

API Açıklaması

GTAF, operatörün DPA'sını sorgularken operatöre abone olan bir kullanıcıyı tanımlayan kullanıcı anahtarını kullanır. GTAF, MSISDN'ye erişimi olan uygulamalar adına DPA'ya sorgu gönderirken MSISDN'yi KULLANABİLİR. Özet olarak, önerilen Veri Planı Aracısı API'si aşağıdaki bileşenlerden oluşur:

  1. Kullanıcı verileri planı durumunu sorgulama mekanizması.
  2. Kullanıcıya yönelik veri planı teklifleri için DPA'yı sorgulama mekanizması.
  3. Kullanıcının veri planında değişiklik yapma mekanizması (ör. yeni bir plan satın alma).
  4. Kullanıcının belirli bir veri planını satın almaya uygun olup olmadığını doğrulama mekanizması.
  5. GTAF'nin MSISDN'leri DPA'ya kaydetme mekanizması.
  6. GTAF'nin, DPA'nın sağlıklı durumda olup olmadığını doğrulama mekanizması.

Bu belgenin kalanında, söz konusu API bileşenlerinin her biri ayrıntılı olarak açıklanmaktadır. Aksi açıkça belirtilmediği sürece tüm iletişimler HTTPS üzerinden (geçerli bir DPA SSL sertifikasıyla) yapılmalıdır. Desteklenen özelliklere bağlı olarak bir operatör, bu API bileşenlerinin tümünü veya bir alt kümesini uygulamayı SEÇEBİLİR.

Veri Planı Durumunu Sorgulama

GTAF-DPA Etkileşimi

GTAF-DPA Etkileşimi

Şekil 4. Kullanıcı verileri planı bilgilerini isteme ve alma için çağrı akışı.

Şekil 4, kullanıcının veri planı durumu ve diğer veri planı bilgileri hakkında sorgu gönderdiği sırada gerçekleşen arama akışını gösterir. Bu çağrı akışı, UE'de istemci tarafından tetiklenen API çağrıları için paylaşılır.

  1. İstemci, özel bir Google API'sini çağırarak veri planı durumu ve/veya diğer bilgileri ister. İstemci, GTAF'ye gönderdiği isteğe kullanıcı anahtarını ekler.
  2. GTAF, operatörün DPA'sını sorgulamak için kullanıcı anahtarını ve bir 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 birini içeren bir arama aldığında istemcinin kullanabileceği plan bilgileriyle yanıt VERMELİDİR.
  3. GTAF, istenen bilgileri istemciye döndürür ve plan bilgileri, DPA tarafından belirtilen son kullanma süresine kadar GTAF tarafından önbelleğe alınır.

Şekil 4'teki 1. ve 3. adımlar özel Google API'leridir ve bu nedenle daha ayrıntılı açıklanmamıştır. 2. adım, aşağıda açıklanan herkese açık bir API'dir. DPA, GTAF'den gelen bu API çağrılarını sunarken Cache-Control: no-cache HTTP üst bilgisine UYMALIDIR.

Plan Durumu

GTAF, plan durumunu almak için aşağıdaki HTTP isteğini gönderir:

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

GTAF'nin DPA ile iletişime geçtiği müşteri, CLIENT_ID kullanılarak tanımlanır. Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak, DPA, GTAF'ye verilen yanıtı özelleştirebilir. Yanıtın biçimi, PlanStatus'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ı) hangi dilde olması gerektiğini belirten bir Accept-Language başlığı içermelidir.

Faturalı planlarda expirationTime, planın yinelenme tarihi OLMALIDIR (ör. veri bakiyesinin yenilendiği/yeniden yüklendiği zaman).

Her plan modülü birden fazla Plan Modülü Trafik Kategorisi (PMTCs)) içerebilir.Bu, bir plan modülünün birden fazla uygulama arasında paylaşıldığı durumu modellemek için kullanılır (ör. 500 MB (oyun ve müzik için). 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ı için geçerli olan trafik kategorileri ve bunların semantiği konusunda anlaşmak üzere Google'ın ilgili ekipleriyle iletişime geçmesi beklenir.

Plan tekliflerini sorgulama

GTAF, operatörden plan teklifleri almak için aşağıdaki HTTP isteğini gönderir:

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

GTAF'nin DPA ile iletişime geçtiği müşteri, CLIENT_ID kullanılarak tanımlanır. Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak, DPA, GTAF'ye verilen yanıtı özelleştirebilir. İsteğe bağlı bağlam parametresi, isteğin yapıldığı uygulama bağlamını sağlar. Bu genellikle uygulamanın GTAF aracılığıyla operatöre ilettiği bir dizedir.

Yanıt metni, PlanOffer öğesinin bir örneğini içerir.

{
    "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ı, kullanıcılara sunulacak veri planlarının sırasını belirleyebilir. Ayrıca, uygulama kullanıcı arayüzü veya diğer sınırlamalar nedeniyle yalnızca x plan sunabiliyorsa ve yanıtta yalnızca y > x plan varsa yalnızca ilk x plan sunulmalıdır. GTAF, teklifleri sorgulayan uygulama Google Play Hizmetleri'nin bir parçası olan Mobil Veri Planı kullanıcı arayüzü ise yalnızca 10 plana kadar paylaşım yapar. Bu, Google Play Hizmetleri kullanıcılarına iyi bir kullanıcı deneyimi sunmak için gereklidir.

offerInfo içindeki dizeler, kullanıcının teklif hakkında daha fazla bilgi edinmesini sağlamak için tasarlanmıştır. Ayrıca, uygulamalardan daha fazla teklif almayı devre dışı bırakma seçeneği de içerir. Bu alanların bulunmasının nedeni, bazı operatörlerin uygulama içi satın alma işlemlerine izin vermek için son kullanıcı izni alması gerekmemesi ancak kullanıcıların devre dışı bırakma seçeneğini kullanabilmesi için bir mekanizma gerektirmesidir. Operatörün, kullanıcıya sunulan tekliflerin satın alma isteğini karşılayacak bir mekanizmaya sahip olması gerektiğini unutmayın. Kullanıcının herhangi bir satın alma işlemi için ücretlendirileceği mekanizma, yanıttaki formOfPayment seçeneği kullanılarak GTAF ile paylaşılabilir.

İstek, okunabilir dizelerin (ör. plan açıklamaları) hangi dilde olması gerektiğini belirten bir Accept-Language başlığı içermelidir.

Veri Satın Alma

Satın alma planı API'si, GTAF'nin DPA aracılığıyla planları nasıl satın alabileceğini tanımlar. GTAF, DPA'dan bir veri planı satın alma işlemini başlatır. İstek, istekleri izlemek ve yinelenen işlem yürütülmesini önlemek için benzersiz bir işlem tanımlayıcısı (transactionId) İÇERMELİDİR. DPA, başarı/başarısızlık yanıtı VERMELİDİR.

İşlem İsteği

GTAF, bir istemciden istek aldığında 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ı

Veri işleme sözleşmesi, hata durumunda yaygın hata nedenlerini döndÜRMELİDİR. Ayrıca, aşağıdaki hata kodları başarısız işlem sonuçlarını gösterir:

  • Sözleşme, satın alınan plan kimliğinin geçersiz olduğunu GTAF'ye bildiren 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ı belirten bir 402 PAYMENT REQUIRED hata kodu döndürür.
  • Sözleşme, satın alınacak planın kullanıcının mevcut ürün karışımıyla uyumlu olmadığını GTAF'ye bildiren bir 409 CONFLICT hata kodu döndürür. Örneğin, operatörün veri planı politikası, faturalı ve ön ödemeli planların birlikte kullanılmasını yasaklıyorsa faturalı bir kullanıcı için ön ödemeli plan satın almaya çalışmak 409 CONFLICT hatasına neden olur.
  • Sözleşme, GTAF'ye mevcut işlemin daha önce yayınlanmış bir işlemin kopyası olduğunu belirten bir 403 FORBIDDEN hata kodu döndürür. KGP, yanıtta aşağıdaki hata nedenlerini döndürmelidir:
    • Önceki işlem başarısız olduysa hatanın nedenini belirten hata nedeni.
    • Önceki işlem başarılıysa DUPLICATE_TRANSACTION.
    • Önceki işlem hâlâ sırada bekliyorsa REQUEST_QUEUED.

DPA, yalnızca başarıyla yürütülen bir işlem veya sıraya alınmış bir işlem için 200-OK yanıtı ÜRETİR. Sıraya alınmış bir işlem söz konusu olduğunda, DPA yalnızca işlem durumunu dolduracak ve yanıttaki diğer alanları boş bırakacaktır. Bir sıraya alınmış işlem işlendikten sonra DPA, GTAF'yi yanıtla birlikte geri aramalıdır. Yanıtın 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.

GTAF, kullanıcı rızası tercihini operatöre iletmek için aşağıdaki isteği gönderebilir.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

burada userKey, CPID veya MSISDN'dir. İsteğin gövdesi, SetConsentStatusRequest örneğidir.

Başarılı olursa yanıt metni boş olmalıdır.

Uygunluk

GTAF, 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ı kullanıcı adına satın almak için kullanılabilecek planın benzersiz tanımlayıcısıdır (bkz. Veri Satın Alma). planId belirtilmezse DPA, kullanıcı tarafından satın alınabilecek tüm planları döndürmelidir.

Veri işleme sözleşmesi, hata durumunda yaygın hata nedenlerini döndÜRMELİDİR. Ayrıca, DPA aşağıdaki hata durumlarında hata döndÜRÜR:

  • DPA, GTAF'ye planId öğesinin geçersiz olduğunu belirten bir 400 BAD REQUEST hata kodu döndürür.
  • DPA, planId'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ı DÖNDÜRMELİDİR. Başarılı bir EligibilityResponse'un biçimi şöyledir:

{
  "eligiblePlans":
  [
   {
    "planId": string,   // Plan identifier. Can be used to
                        // refer to the plan during
                        // offers, etc. (req.)
   }
  ]
}

İstek planId içerdiğinde yanıtta yalnızca bu plan yer alır. Aksi takdirde, listede kullanıcının satın almaya uygun olduğu tüm planlar yer alır. planId boş olduğunda ve DPA, uygun planların listesini döndürmeyi desteklemediğinde 400 BAD REQUEST hatası döndürmelidir.

MSISDN kayıt uç noktası

GTAF, MSISDN'ye erişimi olan uygulamalara hizmet vermek için 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 GTAF'ye bilgi gönderir. GTAF, MSISDN'yi kaydetmek için DPA'ya bir POST isteği gönderir:

POST DPA_URL/register

İsteğin gövdesi, RegistrationRequest öğesinin bir örneği olacaktır.

{
  "msisdn": "<msisdn_string>"
}

MSISDN kaydı başarılı olursa DPA, RegistrationResponse dahil olmak üzere 200 OK yanıtı DÖNDÜRMELİDİR. JSON'un biçimi şöyledir:

{
  // msisdn that was registered.
  "msisdn": "<msisdn_string>",
  // time after which DPA will not send updates to GTAF.
  "expirationTime": string
}

DPA, expirationTime geçene kadar kullanıcının veri planıyla ilgili güncellemeleri GTAF'ye göndermelidir.

Bir hata oluşursa ErrorResponse döndürülmelidir:

{
    "error": "<error message>",
    "cause": enum(ErrorCause)
}

Farklı hata koşulları için olası neden değerlerinin ve HTTP durum kodlarının tam listesini burada bulabilirsiniz. Özellikle, dolaşımda olan veya veri planı bilgilerini Google ile paylaşmayı tercih etmemiş bir kullanıcı için MSISDN kaydı isteği alınırsa DPA, 403 HTTP durum kodunu DÖNDÜRMELİDİR.

Monitoring API

Bazı kullanım alanlarında, GTAF'nin DPA'yı izlemesi ve DPA hatalarını tespit etmesi gerekir. Bu kullanım alanları için bir izleme API'si tanımladık.

API Tanımı

İzleme API'si, aşağıdaki URL'de HTTP GET isteği aracılığıyla kullanılabilir olmalıdır:

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ği 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 herhangi biri düzgün çalışmıyorsa 500 HTTP durum kodu ve DpaStatus örneği 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önemleriyle veri planı bilgilerini göndermeyi durdurmalıdır. İki şekilde uzun önbellek dönemlerine sahip yanıtlar göndermeyi durdurabilir:

  1. Kısa önbellek geçerlilik süreleri ayarlamaya başlayın.
  2. Veri planı bilgilerini tamamen göndermeyi durdurun.

GTAF Davranışı

GTAF, dpaStatus'u düzenli olarak yoklar. Bir DPA hatası tespit ettiğinde ("UNAVAILABLE" yanıtına göre) operatör için önbelleğini temizler.

Hata örnekleri

Hata durumunda, DPA'nın aşağıdakilerden birine karşılık gelen bir HTTP durum kodu döndürmesi beklenir:

  • Kullanıcı şu anda dolaşımdayken bu kullanıcı için DPA sorgusu devre dışı bırakılmıştır. DPA, 403 hatası döndürüyor.
  • DPA, GTAF'ye userkey'in geçersiz olduğunu (ör. mevcut olmayan user key) belirten bir 404 NOT_FOUND hata kodu döndürür.
  • DPA, GTAF'ye key_type = CPID ise ve CPID'nin süresi dolmuşsa istemcinin yeni bir kullanıcı anahtarı alması gerektiğini belirten bir 410 GONE hata kodu döndürür.
  • DPA, bu çağrıyı desteklemediğini belirten 501 NOT_IMPLEMENTED hata kodunu döndürür.
  • Hizmet geçici olarak kullanılamıyor. DPA, yeni bir isteğin ne zaman denenebileceğini belirten Retry-After başlığıyla birlikte 503 SERVICE UNAVAILABLE döndürür.
  • DPA, belirtilmeyen diğer tüm hatalar için 500 INTERNAL SERVER ERROR hata kodunu döndürür.
  • DPA, GTAF'nin DPA'ya çok fazla istek gönderdiğini belirten Retry-After üstbilgisiyle birlikte 429 TOO_MANY_REQUESTS hatasını döndürüyor.
  • DPA, isteğin DPA'nın mevcut durumuyla çakışması nedeniyle tamamlanamadığını belirten bir 409 CONFLICT hatası döndürür.

Tüm hata durumlarında, HTTP yanıtının gövdesi, hata hakkında daha fazla bilgi içeren bir JSON nesnesi içermelidir. Hata yanıtı gövdesi, ErrorResponse örneğini İÇERMELİDİR.

{
  "error": string,
  "cause": enum(ErrorCause)
}

Şu anda tanımlanmış olan cause değerleri, ErrorCause API referansında listelenmiştir.

Aksi takdirde, DPA 200 OK döndürür. Bu cause değerlerinin tüm yanıtlarda kullanıldığını belirtmek isteriz.

Uluslararası hale getirme

DPA'ya yapılan GTAF istekleri, okunabilir dizelerin (ör. plan açıklamaları) hangi dilde olması gerektiğini belirten bir Accept-Language başlığı içerir. Ayrıca, DPA yanıtları (PlanStatus, PlanOffers), değeri BCP-47 dil kodu olan (ör. "en-US") of the response.

DPA, kullanıcının istediği dili desteklemiyorsa varsayılan bir dil kullanabilir ve LanguageCode alanını kullanarak seçimini belirtebilir.