क्वेरी रिपोर्ट का डेटा

reportData.query तरीके से, रिपोर्ट का डेटा सिंक्रोनस तरीके से वापस मिलता है. स्टैंडर्ड Reports सेवा, फ़ाइल पर आधारित रिपोर्ट (CSV या Excel) जनरेट करती है. हालांकि, इस तरीके से स्ट्रक्चर्ड JSON डेटा सीधे रिस्पॉन्स में मिलता है. इससे पहले से Report संसाधन को तय करने, बनाने, और सेव करने की ज़रूरत नहीं पड़ती. इसलिए, यह रीयल-टाइम में डेटा पाने और एक्सप्लोर करने के लिए सबसे सही है.

खास जानकारी

इस गाइड को पढ़कर, Campaign Manager 360 के रिपोर्टिंग डेटा को क्वेरी करने के लिए, इस एंडपॉइंट का इस्तेमाल करने के बारे में जानें.

अनुरोध तैयार करना

डाइमेंशन, मेट्रिक, तारीख की सीमा, फ़िल्टर, और क्रम से लगाने की शर्तें तय करके, ReportDataQueryRequest बनाएं.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
DateRange ऑब्जेक्ट, जो क्वेरी के लिए समयावधि तय करता है. यह तारीख की कोई कस्टम सीमा या तारीख की कोई रिलेटिव सीमा हो सकती है.
dimensionNames
ग्रुप बनाने के लिए, स्टैंडर्ड डाइमेंशन के नामों की सूची.
metricNames
ज़रूरी है. शामिल करने के लिए स्टैंडर्ड मेट्रिक के नामों की सूची.
dimensionFilters
रिपोर्ट के डेटा को फ़िल्टर करने के लिए इस्तेमाल किए गए DimensionValue ऑब्जेक्ट की सूची. इसका इस्तेमाल करके, क्वेरी के नतीजों को किसी डाइमेंशन की खास वैल्यू तक सीमित किया जा सकता है.
sortBys
डाइमेंशन या मेट्रिक के लिए क्रम से लगाने के कॉन्फ़िगरेशन. हर कॉन्फ़िगरेशन में, फ़ील्ड का नाम और क्रम शामिल होता है.
maxResults
हर पेज पर दिखाई जाने वाली लाइनों की ज़्यादा से ज़्यादा संख्या (डिफ़ॉल्ट: 100, ज़्यादा से ज़्यादा: 1000).

पेज पर नंबर डालना

maxResults फ़ील्ड, एक जवाब में दिखाए गए नतीजों की संख्या को कंट्रोल करता है. उदाहरण के लिए, अगर आपने maxResults को 10 पर सेट किया है, तो एपीआई ज़्यादा से ज़्यादा 10 नतीजे दिखाएगा. ऐसा हो सकता है कि एपीआई, आपके अनुरोध से मेल खाने वाले 10 से कम नतीजे दिखाए. ऐसा तब होता है, जब आपके अनुरोध से मेल खाने वाले नतीजे 10 से कम हों.

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

अनुरोध भेजें

reportdata/query एंडपॉइंट पर, एचटीटीपी POST अनुरोध भेजें:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

पक्का करें कि आपके अनुरोध की पुष्टि, OAuth 2.0 के स्टैंडर्ड क्रेडेंशियल और ज़रूरी स्कोप से की गई हो. ज़्यादा जानकारी के लिए, अनुरोधों को अनुमति देना लेख पढ़ें.

जवाब मिल गया

क्वेरी के पूरा होने पर, एचटीटीपी 200 OK रिस्पॉन्स मिलता है. इसमें JSON पेलोड होता है. इस पेलोड में columnHeaders, rows, और totalRow शामिल होते हैं.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}
columnHeaders
जवाब में मिले फ़ील्ड के नाम और टाइप (DIMENSION या METRIC).
rows
ReportDataRow ऑब्जेक्ट की सूची, जिसमें क्वेरी के नतीजे शामिल हैं. हर लाइन में मौजूद स्ट्रिंग वैल्यू, columnHeaders के साथ पोज़िशन के हिसाब से अलाइन होती हैं.
totalRow
एक एग्रीगेट पंक्ति, जो मैच करने वाली सभी मेट्रिक के योग को दिखाती है. इस लाइन में, डाइमेंशन फ़ील्ड और ऐसी मेट्रिक खाली ("") हैं जिन्हें जोड़ा नहीं जा सकता. उदाहरण के लिए, uniqueReachTotalReach जैसी पहुंच से जुड़ी मेट्रिक.
nextPageToken
यह एक टोकन है. इसका इस्तेमाल, अगले पेज को वापस पाने के लिए बाद के अनुरोध में किया जाता है. ऐसा तब किया जाता है, जब अतिरिक्त लाइनें मौजूद हों.

इंतज़ार का समय और टाइम आउट

यह एक सिंक्रोनस एंडपॉइंट है. इसलिए, क्वेरी तुरंत लागू होती हैं और डेटा सीधे जवाब में दिखता है. हालांकि, यह maxResults पेज नंबर की सीमा तक ही दिखता है. क्वेरी को पूरा होने में ज़्यादा से ज़्यादा 60 सेकंड लगते हैं. अगर कोई क्वेरी इस सीमा से ज़्यादा है, तो एपीआई कार्रवाई को बंद कर देता है और HTTP 503 Service Unavailable गड़बड़ी का मैसेज दिखाता है.

अगर आपको यह गड़बड़ी दिखती है, तो तारीख की सीमा को कम करें. इसके अलावा, फ़िल्टर को कम करें. जैसे, विज्ञापन देने वाले कुछ लोगों या कंपनियों या कैंपेन के हिसाब से फ़िल्टर करना. साथ ही, अनुरोध किए गए डाइमेंशन और मेट्रिक की संख्या को कम करें. इसके अलावा, डाउनलोड की जा सकने वाली रिपोर्ट फ़ाइल को एसिंक्रोनस तरीके से जनरेट करने के लिए, Report reports.run का इस्तेमाल करके Report चलाएं.

क्वेरी की सीमाएं और शर्तें

reportdata.query एंडपॉइंट, भरोसेमंद जवाब देने के लिए कई सीमाएं लागू करता है. इन शर्तों का उल्लंघन करने वाले अनुरोधों को HTTP 400 Bad Request रिस्पॉन्स के साथ अस्वीकार कर दिया जाता है.

तारीख की सीमाएं

  • तारीख की कस्टम सीमाओं के लिए, startDate को रिपोर्ट के लिए अनुरोध किए गए डेटा टाइप के लिए, डेटा की उपलब्धता की अवधि के अंदर होना चाहिए. ज़्यादा जानकारी के लिए, डेटा की उपलब्धता देखें.

मेट्रिक और डाइमेंशन से जुड़ी पाबंदियां

  • metricNames में कम से कम एक मेट्रिक दी जानी चाहिए.
  • metricNames और dimensionNames सूचियों में मौजूद मेट्रिक और डाइमेंशन यूनीक होने चाहिए.
  • सिर्फ़ डाउनलोड करें के तौर पर लेबल की गई मेट्रिक और डाइमेंशन का इस्तेमाल इन क्वेरी में नहीं किया जा सकता.

सीमाएं

इस एंडपॉइंट पर किए गए अनुरोधों के लिए, यहां दिए गए कोटे का इस्तेमाल किया जाता है:

  • उपयोगकर्ता के लिए दर सीमा: हर उपयोगकर्ता के लिए, हर मिनट में 120 अनुरोध (2 QPS)
  • हर प्रोजेक्ट के लिए, हर दिन की सीमा: हर प्रोजेक्ट के लिए, हर दिन 10,000 अनुरोध

इन सीमाओं का पालन न करने वाले अनुरोधों को HTTP 429 Too Many Requests गड़बड़ी दिखाकर, रोक दिया जाएगा. अगर आपको नतीजों के अलग-अलग पेज देखने हैं, तो हर नए पेज के लिए किया गया अनुरोध (pageToken पैरामीटर का इस्तेमाल करके) एक अलग क्वेरी के तौर पर गिना जाता है. साथ ही, यह इस कोटे में से इस्तेमाल होता है.