डेटा प्लान एजेंट API

वजह

खास जानकारी में बताया गया है कि ऑपरेटर को इस्तेमाल के जिन उदाहरणों के लिए सहायता देनी है उनके आधार पर, डीपीए को Google Mobile Data Plan Sharing API और Data Plan Agent API, दोनों को लागू करना होगा. इस दस्तावेज़ में, Data Plan Agent API के बारे में बताया गया है. Google इस एपीआई का इस्तेमाल, उपयोगकर्ता के मोबाइल डेटा प्लान की पहचान करने, इन प्लान के बारे में जानकारी पाने, और डेटा प्लान खरीदने के लिए करेगा.

पुष्टि करना

GTAF को कॉल करने से पहले, DPA को GTAF की पुष्टि करनी होगी. ऑपरेटर को शामिल करने की प्रोसेस के तहत, हम डीपीए एसएसएल सर्टिफ़िकेट की वैधता की जांच करेंगे. फ़िलहाल, हम दोनों पक्षों की पुष्टि करने के लिए OAuth2 का इस्तेमाल करना ज़रूरी मानते हैं. GTAF, DPA के साथ अपनी पुष्टि कैसे करता है, इस बारे में जानने के लिए, कृपया डेटा प्लान एजेंट की पुष्टि करना लेख पढ़ें.

इंटरनैशनलाइजेशन

GTAF, डीपीए से अनुरोध करते समय Accept-Language हेडर शामिल करता है. इससे यह पता चलता है कि आसानी से पढ़ी जा सकने वाली स्ट्रिंग (जैसे, प्लान के ब्यौरे) किस भाषा में होनी चाहिए. इसके अलावा, DPA के जवाबों (PlanStatus, PlanOffers) में, भाषा कोड वाला ज़रूरी फ़ील्ड शामिल होता है.इसकी वैल्यू, BCP-47 भाषा कोड होती है. उदाहरण के लिए, "en-US") के हिसाब से जवाब दें.

अगर डीपीए, उपयोगकर्ता की चुनी गई भाषा के साथ काम नहीं करता है, तो वह डिफ़ॉल्ट भाषा का इस्तेमाल कर सकता है. साथ ही, भाषा चुनने के लिए languageCode फ़ील्ड का इस्तेमाल कर सकता है.

एपीआई के बारे में जानकारी

GTAF, ऑपरेटर के DPA से क्वेरी करते समय उपयोगकर्ता के पासकोड का इस्तेमाल करता है. इससे ऑपरेटर के लिए, सदस्य की पहचान की जाती है. जब GTAF, MSISDN ऐक्सेस करने वाले ऐप्लिकेशन की ओर से DPA से क्वेरी कर रहा हो, तो GTAF, MSISDN का इस्तेमाल कर सकता है. बड़े लेवल पर, डेटा प्लान एजेंट एपीआई में ये कॉम्पोनेंट शामिल हैं:

1. उपयोगकर्ता के डेटा प्लान की स्थिति के बारे में क्वेरी करने का तरीका.
2. उपयोगकर्ता के लिए डेटा प्लान के ऑफ़र के बारे में जानने के लिए, DPA से क्वेरी करने का तरीका.
3. उपयोगकर्ता के डेटा प्लान में बदलाव करने का तरीका (जैसे, नया प्लान खरीदना).
4. सीपीआईडी शेयर करने का तरीका, ताकि उपयोगकर्ताओं को सूचनाएं भेजी जा सकें.
5. यह कुकी, उपयोगकर्ता की पसंद के हिसाब से यह तय करती है कि उसे हमारी सेवा के लिए साइन अप करना है या नहीं.

इस दस्तावेज़ के बाकी हिस्से में, एपीआई के इन कॉम्पोनेंट के बारे में ज़्यादा जानकारी दी गई है. जब तक साफ़ तौर पर न बताया जाए, तब तक सभी कम्यूनिकेशन एचटीटीपीएस पर होने चाहिए. साथ ही, इनके लिए मान्य डीपीए एसएसएल सर्टिफ़िकेट होना चाहिए. जिन सुविधाओं के लिए सहायता उपलब्ध है उनके आधार पर, ऑपरेटर इन एपीआई कॉम्पोनेंट के सभी या कुछ कॉम्पोनेंट को लागू कर सकता है.

GTAF-DPA इंटरैक्शन

चौथी इमेज. उपयोगकर्ता के डेटा प्लान की जानकारी का अनुरोध करने और उसे पाने के लिए कॉल फ़्लो.

चौथे फ़िगर में, कॉल फ़्लो दिखाया गया है. इसमें क्लाइंट, उपयोगकर्ता के डेटा प्लान की स्थिति और अन्य डेटा प्लान की जानकारी के बारे में क्वेरी करता है. यह कॉल फ़्लो, यूई पर क्लाइंट की ओर से ट्रिगर किए गए एपीआई कॉल के लिए शेयर किया जाता है.

1. क्लाइंट, Google के निजी एपीआई को कॉल करके, डेटा प्लान की स्थिति और/या अन्य जानकारी का अनुरोध करता है. क्लाइंट, GTAF को किए गए अनुरोध में उपयोगकर्ता कुंजी शामिल करता है.
2. GTAF, ऑपरेटर के DPA से क्वेरी करने के लिए उपयोगकर्ता कुंजी और क्लाइंट आइडेंटिफ़ायर का इस्तेमाल करता है. mobiledataplan और youtube, क्लाइंट आइडेंटिफ़ायर के तौर पर इस्तेमाल किए जा सकते हैं. जब डीपीए को इनमें से किसी क्लाइंट आइडेंटिफ़ायर के साथ कॉल मिलता है, तो उसे प्लान की ऐसी जानकारी देनी होगी जिसका इस्तेमाल क्लाइंट कर सके.
3. GTAF, क्लाइंट को मांगी गई जानकारी देता है. साथ ही, प्लान की जानकारी को GTAF तब तक कैश मेमोरी में सेव रखता है, जब तक DPA की ओर से तय की गई समयसीमा खत्म नहीं हो जाती.

आंकड़े 4 में दिए गए पहले और तीसरे चरण में, Google के निजी एपीआई का इस्तेमाल किया जाता है. इसलिए, इनके बारे में ज़्यादा जानकारी नहीं दी गई है. दूसरा चरण, एक सार्वजनिक एपीआई है. इसके बारे में यहां बताया गया है. GTAF से इन एपीआई कॉल को पूरा करते समय, डीपीए को Cache-Control: no-cache एचटीटीपी हेडर का पालन करना होगा.

डेटा प्लान की स्थिति के बारे में क्वेरी करना

GTAF, प्लान की स्थिति पाने के लिए यह एचटीटीपी अनुरोध करता है:

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

जिस क्लाइंट की ओर से GTAF, DPA से संपर्क कर रहा है उसकी पहचान CLIENT_ID का इस्तेमाल करके की जाती है. Google क्लाइंट और ऑपरेटर के बीच हुए समझौते के आधार पर, डीपीए, GTAF को जवाब देने के तरीके को पसंद के मुताबिक बना सकता है. अनुरोध पूरा होने पर, डीपीए को PlanStatus को दिखाने वाले जवाब के मुख्य हिस्से के साथ, HTTP 200 OK स्टेटस कोड दिखाना होगा. गड़बड़ियों के मामले में, अनुमानित जवाब देखने के लिए कृपया गड़बड़ी के मामले देखें.

{
  "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
      }
    }
  }
}

पोस्ट-पेड प्लान के लिए, expirationTime प्लान के रिन्यूअल की तारीख होनी चाहिए. जैसे, डेटा बैलेंस कब रीफ़्रेश/रीलोड होता है.

हर प्लान मॉड्यूल में, प्लान मॉड्यूल की कई ट्रैफ़िक कैटगरी हो सकती हैं (PMTCs).इससे यह मॉडल तैयार किया जा सकता है कि प्लान मॉड्यूल को कई ऐप्लिकेशन के साथ शेयर किया गया है. उदाहरण के लिए, गेम और संगीत के लिए 500 एमबी). यहां दिए गए पीएमटीसी पहले से तय किए गए हैं: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. यह उम्मीद की जाती है कि ऑपरेटर, Google की अलग-अलग टीमों से संपर्क करेंगे, ताकि वे ट्रैफ़िक कैटगरी और उनके सिमैंटिक के उस सेट पर सहमत हो सकें जो Google के अलग-अलग ऐप्लिकेशन के लिए काम का है.

प्लान के ऑफ़र के बारे में क्वेरी करना

GTAF, ऑपरेटर से प्लान के ऑफ़र पाने के लिए यह एचटीटीपी अनुरोध भेजता है:

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

जिस क्लाइंट की ओर से GTAF, DPA से संपर्क कर रहा है उसकी पहचान CLIENT_ID का इस्तेमाल करके की जाती है. Google क्लाइंट और ऑपरेटर के बीच हुए समझौते के आधार पर, डीपीए, GTAF को जवाब देने के तरीके को पसंद के मुताबिक बना सकता है. कॉन्टेक्स्ट पैरामीटर (ज़रूरी नहीं) से, ऐप्लिकेशन के उस कॉन्टेक्स्ट के बारे में जानकारी मिलती है जिसमें अनुरोध किया गया है. आम तौर पर, यह एक ऐसी स्ट्रिंग होती है जिसे ऐप्लिकेशन, GTAF के ज़रिए ऑपरेटर को पास करता है.

अगर अनुरोध पूरा हो जाता है, तो डीपीए को एचटीटीपी 200 OK स्टेटस कोड के साथ जवाब देना होगा. साथ ही, जवाब के मुख्य हिस्से में PlanOffer ऑब्जेक्ट शामिल करना होगा. गड़बड़ियों के मामले में, अनुमानित जवाब के लिए कृपया गड़बड़ी के मामले देखें.

{
    "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",
        "filterTags": ["repurchase", "all"]
      }
    ],
    "filters" : [
      {
        "tag": "repurchase",
        "displayText": "REPURCHASE PLANS"
      },
      {
        "tag": "all",
        "displayText": "ALL PLANS"
      }
    ]
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

offers ऐरे में मौजूद डेटा प्लान का क्रम, उपयोगकर्ताओं को दिखाए जाने वाले डेटा प्लान के क्रम को तय कर सकता है. इसके अलावा, अगर यूज़र इंटरफ़ेस (यूआई) या अन्य सीमाओं की वजह से ऐप्लिकेशन सिर्फ़ x प्लान दिखा सकता है और जवाब में y > x प्लान शामिल हैं, तो सिर्फ़ पहले x प्लान दिखाए जाएंगे. अगर ऑफ़र के लिए क्वेरी करने वाला ऐप्लिकेशन, मोबाइल डेटा प्लान मॉड्यूल है, तो GTAF सिर्फ़ 50 प्लान शेयर करता है. यह मॉड्यूल, Google Play services का हिस्सा है. इससे Google Play Services इस्तेमाल करने वाले लोगों को बेहतर अनुभव मिलता है.

अपसेल ऑफ़र में filterTags को एक वैकल्पिक पैरामीटर के तौर पर इस्तेमाल किया जाता है. यह हर प्लान से जुड़े टैग का एक कलेक्शन होता है. ये सभी filterTags, उस टैग से मैच होने चाहिए जो फ़िल्टर के अंदर मौजूद एक ऑब्जेक्ट है. Filter एक पहले लेवल का ऑब्जेक्ट है, जिसमें टपल<tag, displaytext=""> होता है. Filter, फ़िल्टर की एक ऐसी सूची है जिसे यूज़र इंटरफ़ेस (यूआई) पर रेंडर किया जाएगा. उपयोगकर्ता, DisplayText पर क्लिक करके फ़िल्टर कर सकता है. displayText से जुड़े टैग का इस्तेमाल, ऑफ़र फ़िल्टर करने के लिए किया जाता है.</tag,>

ध्यान दें कि ऑपरेटर के पास, उपयोगकर्ता को दिए गए किसी भी ऑफ़र के लिए खरीदारी का अनुरोध पूरा करने का तरीका होना चाहिए. उपयोगकर्ता से खरीदारी के लिए शुल्क लेने के तरीके के बारे में, GTAF को बताया जा सकता है. इसके लिए, जवाब में formOfPayment विकल्प का इस्तेमाल करें.

डेटा प्लान खरीदना

खरीदारी प्लान एपीआई से यह तय होता है कि GTAF, DPA के ज़रिए प्लान कैसे खरीद सकता है. GTAF, DPA को एक डेटा प्लान खरीदने के लिए लेन-देन शुरू करता है. अनुरोध में, लेन-देन का यूनीक आइडेंटिफ़ायर (transactionId) शामिल होना चाहिए. इससे अनुरोधों को ट्रैक करने और लेन-देन को डुप्लीकेट तरीके से पूरा होने से रोकने में मदद मिलती है. डीपीए को जवाब में यह बताना होगा कि अनुरोध पूरा हुआ या नहीं.

लेन-देन का अनुरोध

किसी क्लाइंट से अनुरोध मिलने पर, GTAF, DPA को POST अनुरोध भेजता है. अनुरोध का यूआरएल यह है:

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

यहां userKey, CPID या MSISDN में से कोई एक है. अनुरोध के मुख्य भाग में TransactionRequest का एक इंस्टेंस होता है. इसमें ये फ़ील्ड शामिल होते हैं:

{
  "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.
}

लेन-देन की प्रतिक्रिया

डेटा प्रोसेसिंग ऐप्लिकेशन (डीपीए), लेन-देन पूरा होने या कतार में लगे लेन-देन के लिए ही 200-OK रिस्पॉन्स जनरेट करेगा. गड़बड़ियों के मामले में, अनुमानित जवाब के लिए कृपया गड़बड़ी के मामले देखें. अगर लेन-देन को कतार में रखा गया है, तो डीपीए को सिर्फ़ लेन-देन की स्थिति भरनी होगी. साथ ही, जवाब में अन्य फ़ील्ड खाली छोड़ने होंगे. जब कोई कतार में मौजूद लेन-देन पूरा हो जाता है, तो डीपीए को GTAF को जवाब देना होगा. जवाब का मुख्य हिस्सा, TransactionResponse का एक इंस्टेंस होता है. इसमें यह जानकारी शामिल होती है:

{
  "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 मौजूद नहीं है, तो GTAF यह मान लेगा कि प्लान चालू कर दिया गया है.

सीपीआईडी रजिस्टर करना

सूचनाएं पाने की सुविधा देने वाला क्लाइंट, CPID एंडपॉइंट से नया CPID मिलने पर, उसे GTAF के साथ रजिस्टर करता है. ऐसा तब होता है, जब क्लाइंट की शर्तों के मुताबिक GTAF को ऐसा करने की अनुमति हो. अगर क्लाइंट, CPID को GTAF के साथ रजिस्टर कर लेता है, तो GTAF, CPID को DPA के साथ रजिस्टर करेगा. इसके लिए, वह इस एपीआई कॉल का इस्तेमाल करेगा:

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

यहां userKey CPID है और सिर्फ़ mobiledataplan CLIENT_ID इस्तेमाल किया जा सकता है. अनुरोध का मुख्य हिस्सा, RegisterCpidRequest का उदाहरण है. इसमें वह समय शामिल होता है जिसके बाद CPID का इस्तेमाल सूचनाएं भेजने के लिए नहीं किया जा सकता. यह इस तरह दिखता है:

{"staleTime": "2017-01-29T01:00:03.14159Z"}

यह एपीआई सिर्फ़ उन ऑपरेटर के लिए काम का है जो Google Play services में मोबाइल डेटा प्लान मॉड्यूल को सपोर्ट करना चाहते हैं. उपयोगकर्ता को भरोसेमंद तरीके से सूचनाएं भेजने के लिए, डीपीए हर उपयोगकर्ता के लिए, रजिस्टर किया गया नया सीपीआईडी सेव कर सकता है. सूचनाएं भेजने के लिए, रजिस्टर किए गए सीपीआईडी का इस्तेमाल करने के तरीके के बारे में जानने के लिए, कृपया सीपीआईडी चुनना लेख पढ़ें.

अगर डीपीए, सीपीआईडी को उपयोगकर्ता से जोड़ देता है और उसे हमेशा के लिए सेव कर लेता है, तो उसे 200-OK रिस्पॉन्स जनरेट करना होगा. गड़बड़ियों के मामले में, अनुमानित जवाब के लिए कृपया गड़बड़ी के मामले देखें.

सहमति

GTAF, उपयोगकर्ता की सहमति की प्राथमिकता को कैरियर को पास करने के लिए, यह अनुरोध जारी कर सकता है.

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

यहां userKey, CPID या MSISDN में से कोई एक है. अनुरोध का मुख्य हिस्सा, SetConsentStatusRequest का एक इंस्टेंस है. अगर अनुरोध पूरा हो जाता है, तो जवाब का मुख्य हिस्सा खाली होना चाहिए.

GTAF से DPA को किए गए हर कॉल पर, कॉल करने वाले Google क्लाइंट की सेवा की शर्तें लागू होती हैं. डीपीए जिन ऐप्लिकेशन के साथ काम करना चाहता है उनके आधार पर, ऑपरेटर को यह तय करना होता है कि डीपीए इस एपीआई को लागू करे या नहीं. अगर डीपीए, सहमति वाले एपीआई को लागू करने का विकल्प चुनता है, तो डीपीए को हर उपयोगकर्ता के लिए, सहमति की मौजूदा स्थिति को सेव करना होगा. सहमति की स्थिति की जानकारी का इस्तेमाल करने के बारे में दिशा-निर्देश पाने के लिए, कृपया सीपीआईडी चुनना लेख पढ़ें.

अगर अनुरोध पूरा हो जाता है, तो DPA को खाली जवाब के मुख्य हिस्से के साथ HTTP 200 OK जवाब देना होगा. गड़बड़ियों के मामले में, अनुमानित जवाब के लिए कृपया गड़बड़ी के मामले देखें.