Ad Manager API, डेटा के कलेक्शन उपलब्ध कराता है. आम तौर पर, यह कलेक्शन List तरीकों में उपलब्ध होते हैं. कलेक्शन का साइज़ तय नहीं होता. साथ ही, एपीआई के जवाबों में, कलेक्शन को पेजों में बांटा जाता है.
बुनियादी बातें
कलेक्शन के लिए अनुरोध वाले मैसेज में, pageSize फ़ील्ड को इंटिजर के तौर पर तय किया जा सकता है. यह फ़ील्ड, लौटाए जाने वाले नतीजों की ज़्यादा से ज़्यादा संख्या तय करता है.
pageSize पैरामीटर को 1000 से कम पॉज़िटिव नंबर पर सेट करें. अगर कोई वैल्यू सेट नहीं की जाती है या पैरामीटर को शून्य पर सेट किया जाता है, तो एपीआई 50 की डिफ़ॉल्ट वैल्यू का इस्तेमाल करता है. अगर पैरामीटर को नेगेटिव वैल्यू पर सेट किया जाता है, तो एपीआई INVALID_ARGUMENT गड़बड़ी दिखाता है.
किसी संसाधन के लिए, pageSize की खास वैल्यू जानने के लिए, संसाधन के रेफ़रंस वाले दस्तावेज़ देखें. उदाहरण के लिए
AdBreaks,
के लिए, संसाधन का रेफ़रंस वाला दस्तावेज़ देखें.
एपीआई, अनुरोध किए गए नतीजों से कम नतीजे (शून्य नतीजे भी) लौटा सकता है. ऐसा तब भी हो सकता है, जब कलेक्शन के आखिर में न पहुंचा गया हो. यह पता लगाने के लिए कि कलेक्शन में और नतीजे हैं या नहीं, nextPageToken फ़ील्ड की मौजूदगी का इस्तेमाल करें.
कलेक्शन के लिए जवाब वाले मैसेज में, nextPageToken फ़ील्ड को स्ट्रिंग के तौर पर तय किया जाता है. इसका इस्तेमाल, अगला पेज पाने के लिए किया जा सकता है. कलेक्शन के आखिर में पहुंचने पर, nextPageToken फ़ील्ड खाली होता है. यह पता लगाने का यही तरीका है कि कलेक्शन के आखिर में पहुंचा गया है या नहीं.
कलेक्शन के लिए अनुरोध वाले मैसेज में, pageToken फ़ील्ड को स्ट्रिंग के तौर पर तय किया जा सकता है. इसका इस्तेमाल, कलेक्शन में अगले पेज पर जाने के लिए किया जाता है. बाद के पेजों के लिए किए गए अनुरोध में, pageSize में बदलाव किए जा सकते हैं. अन्य सभी आर्ग्युमेंट एक जैसे होने चाहिए. अगर कोई आर्ग्युमेंट अलग है, तो एपीआई INVALID_ARGUMENT गड़बड़ी दिखाता है.
उदाहरण
cURL
पहला अनुरोध
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500
{
"adUnits": [ ... ],
"nextPageToken": "eCGwAcs6hUerggzd2DGv"
}
अगले पेज के लिए अनुरोध
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv
{
"adUnits": [ ... ]
}
कुल आकार
कलेक्शन के लिए जवाब वाले मैसेज में, totalSize को इंटिजर के तौर पर तय किया जाता है. यह फ़िल्टरिंग लागू होने के बाद, कुल इकाइयों की संख्या दिखाता है. यह फ़ील्ड सिर्फ़ तब दिखता है, जब इसे फ़ील्ड मास्क में शामिल किया जाता है.
GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize
नतीजों को क्रम से लगाना
कलेक्शन के लिए अनुरोध वाले मैसेज में, orderBy फ़ील्ड को स्ट्रिंग के तौर पर तय किया जाता है. यह फ़ील्ड, क्रम से लगाने का ऑर्डर तय करता है.
वैल्यू, कॉमा से अलग की गई फ़ील्ड की सूची होनी चाहिए. उदाहरण के लिए: foo,bar. क्रम से लगाने का डिफ़ॉल्ट ऑर्डर, बढ़ते क्रम में होता है. किसी फ़ील्ड के लिए, घटते क्रम में लगाने का ऑर्डर तय करने के लिए,
desc सफ़िक्स जोड़ें. उदाहरण के लिए: foo desc, bar. सिंटैक्स में मौजूद, फ़ालतू स्पेस वाले वर्णों को अनदेखा किया जाता है. orderBy की वैल्यू foo, bar desc, foo , bar desc, और foo,bar desc एक ही हैं. सबफ़ील्ड को तय किया जाता है
एक . वर्ण के साथ, जैसे foo.bar या address.street.
क्रम से लगाने की सुविधा सिर्फ़ प्रिमिटिव फ़ील्ड पर उपलब्ध है.
नतीजे छोड़ना
पेजों में बांटी गई कार्रवाइयों के तरीकों में, skip फ़ील्ड को इंटिजर के तौर पर तय किया जाता है. इसका इस्तेमाल, नतीजों को छोड़ने के लिए किया जाता है. छोड़ने की वैल्यू, पेजों की संख्या नहीं, बल्कि छोड़े जाने वाले अलग-अलग संसाधनों की संख्या होती है.
उदाहरण के लिए:
बिना पेज टोकन और 30 की स्किप वैल्यू वाला अनुरोध, नतीजों का एक पेज लौटाता है. यह पेज, 31वें नतीजे से शुरू होता है.
51वें नतीजे से जुड़े पेज टोकन (क्योंकि पहले 50 नतीजे पहले पेज पर लौटाए गए थे) और 30 की स्किप वैल्यू वाला अनुरोध, नतीजों का एक पेज लौटाता है. यह पेज, 81वें नतीजे से शुरू होता है.
अगर ऐसी स्किप वैल्यू दी जाती है जिससे कर्सर, नतीजों के कलेक्शन के आखिर से आगे बढ़ जाता है, तो जवाब 200 OK होता है. इसमें नतीजों का खाली सेट होता है और कोई nextPageToken नहीं होता.