Search Ads 360 Reporting API में खोज रिपोर्ट बनाना

Search Ads 360 Reporting API में सर्च रिपोर्ट बनाने का तरीका जानने के लिए, नीचे दिए गए सेक्शन पढ़ें.

Search की सेवा

Search Ads 360 Reporting API, खोजने और रिपोर्ट करने के लिए एक खास सेवा उपलब्ध कराता है.

SearchAds360Service, ऑब्जेक्ट को वापस पाने और रिपोर्टिंग की एक यूनिफ़ाइड सेवा है. इसमें खोज के दो तरीके उपलब्ध हैं: SearchStream और Search. खोजों को Search Ads 360 क्वेरी लैंग्वेज में लिखी गई क्वेरी स्ट्रिंग में पास किया जाता है. क्वेरी तय करके, ये काम किए जा सकते हैं:

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

खोज के दोनों तरीके, आपकी क्वेरी से मैच होने वाली सभी पंक्तियां दिखाते हैं. उदाहरण के लिए, campaign.id, campaign.name, और metrics.clicks को फिर से पाने पर, एपीआई एक SearchAds360Row दिखाता है. इसमें कैंपेन ऑब्जेक्ट के साथ id और name फ़ील्ड सेट होते हैं. साथ ही, metrics ऑब्जेक्ट के साथ clicks फ़ील्ड सेट होते हैं.

खोज के तरीके

SearchStream

यह एक अनुरोध भेजता है और रिपोर्ट के साइज़ के बावजूद, Search Ads 360 Reporting API के साथ लगातार कनेक्शन शुरू करता है.

  • डेटा बफ़र में कैश मेमोरी में सेव किए गए पूरे नतीजे के साथ, डेटा पैकेट तुरंत डाउनलोड होने लगते हैं.
  • आपका कोड, पूरी स्ट्रीम के खत्म होने का इंतज़ार किए बिना, बफ़र किए गए डेटा को पढ़ना शुरू कर सकता है.
Search

पूरी रिपोर्ट डाउनलोड करने के लिए, पेज के हिसाब से कई अनुरोध भेजता है.

आम तौर पर, SearchStream बेहतर परफ़ॉर्मेंस देता है, क्योंकि इससे अलग-अलग पेजों का अनुरोध करने के लिए, नेटवर्क राउंड ट्रिप का समय खत्म हो जाता है. हमारा सुझाव है कि 10,000 से ज़्यादा लाइनों वाली सभी रिपोर्ट के लिए, SearchStream का इस्तेमाल करें. छोटी रिपोर्ट (<10,000 लाइनें) के लिए, इन तरीकों की परफ़ॉर्मेंस में कोई ज़रूरी अंतर नहीं होता.

आपके इस्तेमाल किए गए तरीके से, आपके एपीआई के कोटा और सीमाओं पर कोई असर नहीं पड़ता: एक क्वेरी या रिपोर्ट को एक ऑपरेशन के तौर पर गिना जाता है. भले ही, नतीजे पेज किए गए हों या स्ट्रीम किए गए हों.

खोज क्वेरी का उदाहरण

इस उदाहरण की क्वेरी, किसी खाते के लिए पिछले 30 दिनों की परफ़ॉर्मेंस का डेटा दिखाती है. यह डेटा, कैंपेन के हिसाब से डिवाइस के हिसाब से बांटा गया होता है:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

अनुरोध करें

अनुरोध करने के लिए, आपको SearchAds360Service.SearchStream या SearchAds360Service.Search इंटरफ़ेस में customer_id और query स्ट्रिंग डालनी होगी.

अनुरोध में, Search Ads 360 Reporting API के सर्वर पर, इनमें से किसी एक यूआरएल पर एचटीटीपी POST शामिल होता है:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

यहां एचटीटीपी POST अनुरोध में शामिल searchStream के लिए, रिपोर्ट की परिभाषा का पूरा उदाहरण दिया गया है:

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

जवाब प्रोसेस करना

SearchAds360Service, SearchAds360Row ऑब्जेक्ट की सूची दिखाता है.

हर SearchAds360Row, क्वेरी से मिले ऑब्जेक्ट को दिखाता है. हर ऑब्जेक्ट में एट्रिब्यूट का एक सेट होता है. ये एट्रिब्यूट, क्वेरी के SELECT क्लॉज़ में अनुरोध किए गए फ़ील्ड के आधार पर पॉप्युलेट होते हैं. SELECT क्लॉज़ में शामिल नहीं किए गए एट्रिब्यूट, रिस्पॉन्स में मौजूद ऑब्जेक्ट में पॉप्युलेट नहीं किए जाते.

उदाहरण के लिए, नीचे दी गई क्वेरी, हर SearchAds360Row ऑब्जेक्ट में सिर्फ़ campaign.id, campaign.name, और campaign.status की वैल्यू डालती है. campaign.engine_id या campaign.bidding_strategy_type जैसे अन्य एट्रिब्यूट को शामिल नहीं किया जाता.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

रेफ़रंस दस्तावेज़

रेफ़रंस सेक्शन में, हर आर्टफ़ैक्ट का सही तरीके से इस्तेमाल करने के लिए ज़रूरी जानकारी शामिल होती है. हर रिसॉर्स के लिए एक पेज होता है. उदाहरण के लिए, ad_group और campaign. segments और metrics पेजों पर, सभी उपलब्ध सेगमेंट और मेट्रिक फ़ील्ड की सूची होती है.

कुछ संसाधन, सेगमेंट, और मेट्रिक साथ काम नहीं करती हैं और इनका इस्तेमाल एक साथ नहीं किया जा सकता. वहीं, कुछ संसाधन, सेगमेंट, और मेट्रिक एक साथ काम करती हैं और एक-दूसरे के साथ मिलकर बेहतर नतीजे देती हैं. हर संसाधन पेज पर, यहां दी गई जानकारी (अगर उपलब्ध और सही हो) के साथ-साथ और भी जानकारी शामिल होती है:

एट्रिब्यूट किए गए संसाधन

कुछ रिसॉर्स के लिए, आपके पास अपने FROM क्लॉज़ में रिसॉर्स के फ़ील्ड के साथ-साथ उनसे जुड़े रिसॉर्स के फ़ील्ड चुनकर, उनसे चुपचाप जॉइन करने का विकल्प हो सकता है. उदाहरण के लिए, campaign रिसॉर्स, ad_group रिसॉर्स का एट्रिब्यूट किया गया रिसॉर्स है. इसका मतलब है कि FROM क्लॉज़ में ad_group का इस्तेमाल करते समय, अपनी क्वेरी में campaign.id और campaign.bidding_strategy_type जैसे फ़ील्ड शामिल किए जा सकते हैं.

एट्रिब्यूट किए गए संसाधन सेक्शन में, एट्रिब्यूट किए गए उपलब्ध संसाधनों की सूची होती है. सभी रिसॉर्स में एट्रिब्यूट किए गए रिसॉर्स नहीं होते.

रिसॉर्स फ़ील्ड कॉलम

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

सेगमेंट कॉलम

किसी दिए गए संसाधन के साथ, सभी सेगमेंट फ़ील्ड नहीं चुने जा सकते.

सेगमेंट कॉलम में, ऐसे segments फ़ील्ड की सूची होती है जिनका इस्तेमाल, रिसॉर्स के फ़ील्ड के तौर पर एक ही SELECT क्लॉज़ में किया जा सकता है. हर फ़ील्ड, फ़ील्ड के बारे में पूरी जानकारी से लिंक होता है. इसमें फ़ील्ड का ब्यौरा, कैटगरी, डेटा टाइप, टाइप यूआरएल, और फ़िल्टर करने, चुनने, क्रम से लगाने, और दोहराए जाने की सेटिंग शामिल होती है. अगर FROM क्लॉज़ में संसाधन का इस्तेमाल किया जा रहा है, तो हां/नहीं ड्रॉपडाउन का इस्तेमाल करके, उपलब्ध न होने वाले सेगमेंट को फ़िल्टर किया जा सकता है.

मेट्रिक कॉलम

किसी दिए गए संसाधन के साथ, सभी मेट्रिक फ़ील्ड नहीं चुने जा सकते.

मेट्रिक कॉलम में, ऐसे metrics फ़ील्ड की सूची होती है जिनका इस्तेमाल, रिसॉर्स के फ़ील्ड के तौर पर एक ही SELECT क्लॉज़ में किया जा सकता है. हर फ़ील्ड, फ़ील्ड के बारे में पूरी जानकारी से लिंक होता है. इसमें फ़ील्ड का ब्यौरा, कैटगरी, डेटा टाइप, टाइप यूआरएल, और फ़िल्टर करने, चुनने, क्रम से लगाने, और दोहराए जाने की सेटिंग शामिल होती है. अगर FROM क्लॉज़ में संसाधन का इस्तेमाल किया जा रहा है, तो उपलब्ध न होने वाली मेट्रिक को फ़िल्टर करने के लिए, हां/नहीं ड्रॉपडाउन का इस्तेमाल करें.

संसाधनों को सेगमेंट में बांटना

कुछ संसाधनों में, सेगमेंट करने वाले संसाधन फ़ील्ड होते हैं. जब संसाधन आपके FROM क्लॉज़ में हो, तो उन्हें चुना जा सकता है. उदाहरण के लिए, अगर आपने FROM क्लॉज़ में campaign_budget का इस्तेमाल करते समय, campaign.name जैसे campaign रिसॉर्स फ़ील्ड चुना है, तो campaign.resource_name अपने-आप दिखेगा और उस पर सेगमेंट किया जाएगा. ऐसा इसलिए होगा, क्योंकि campaign, campaign_budget का सेगमेंट करने वाला रिसॉर्स है.

सेगमेंट बनाने के लिए संसाधन सेक्शन में, सेगमेंट बनाने के लिए उपलब्ध संसाधनों की सूची होती है. सभी रिसॉर्स में सेगमेंट करने वाले रिसॉर्स नहीं होते.

इनके साथ चुना जा सकता है

कुछ segments फ़ील्ड, अन्य रिसॉर्स, सेगमेंट, और मेट्रिक के साथ काम नहीं करते.

segments पेज पर, हर segments फ़ील्ड के लिए इसके साथ चुना जा सकता है विकल्प होता है. इसे बड़ा करके, उन सभी संसाधन फ़ील्ड, metrics फ़ील्ड, और अन्य segments फ़ील्ड की सूची देखी जा सकती है जिन्हें SELECT क्लॉज़ में शामिल किया जा सकता है.

सेगमेंट करने की सुविधा

अपनी क्वेरी के SELECT क्लॉज़ में segments.FIELD_NAME फ़ील्ड जोड़कर, खोज के नतीजों को सेगमेंट में बांटा जा सकता है.

उदाहरण के लिए, नीचे दी गई क्वेरी में segments.device का इस्तेमाल करने पर, FROM क्लॉज़ में बताए गए रिसॉर्स के लिए, हर डिवाइस के impressions की एक पंक्ति वाली रिपोर्ट दिखती है.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

SearchAds360Service.SearchStream से मिले नतीजे, इस JSON स्ट्रिंग जैसे दिखते हैं:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

इस्तेमाल किए जा सकने वाले उपलब्ध सेगमेंट फ़ील्ड की सूची के लिए, segments देखें.

एक से ज़्यादा सेगमेंट

अपनी क्वेरी के SELECT क्लॉज़ में, एक से ज़्यादा सेगमेंट तय किए जा सकते हैं. रिस्पॉन्स में, FROM क्लॉज़ में बताए गए मुख्य रिसॉर्स के इंस्टेंस के हर कॉम्बिनेशन के लिए एक SearchAds360Row ऑब्जेक्ट और चुने गए हर segment फ़ील्ड की वैल्यू शामिल होती है.

उदाहरण के लिए, नीचे दी गई क्वेरी से campaign, segments.ad_network_type, और segments.date के हर कॉम्बिनेशन के लिए एक लाइन दिखेगी.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

ध्यान दें कि नतीजों को मुख्य संसाधन के हर इंस्टेंस के हिसाब से सेगमेंट में बांटा जाता है, न कि चुने गए अलग-अलग फ़ील्ड की वैल्यू के हिसाब से.

नीचे दिए गए उदाहरण में, campaign.status फ़ील्ड की हर अलग वैल्यू के लिए एक लाइन के बजाय, हर कैंपेन के लिए एक लाइन दिखती है.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

इंप्लिसिट सेगमेंटेशन

हर रिपोर्ट को शुरुआत में, FROM क्लॉज़ में बताए गए संसाधन के हिसाब से सेगमेंट में बांटा जाता है. मेट्रिक को इस रिसॉर्स के resource_name फ़ील्ड के हिसाब से सेगमेंट में बांटा जाता है

इस उदाहरण में दी गई क्वेरी, ad_group.resource_name को अपने-आप दिखाती है. साथ ही, ad_group लेवल पर मेट्रिक को सेगमेंट करने के लिए, इसका इस्तेमाल करती है.

SELECT metrics.impressions
FROM ad_group

रिटर्न की गई JSON स्ट्रिंग कुछ इस तरह दिखती है:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

तारीख के मुख्य सेगमेंट

तारीख या समयावधि तय करने के लिए, अपने WHERE क्लॉज़ में मुख्य तारीख सेगमेंट का इस्तेमाल किया जा सकता है.

इन सेगमेंट फ़ील्ड को तारीख के मुख्य सेगमेंट कहा जाता है: segments.date, segments.week, segments.month, segments.quarter, और segments.year.

इस उदाहरण की क्वेरी, पिछले 30 दिनों के लिए कैंपेन clicks की मेट्रिक दिखाती है.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

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

तारीख के सेगमेंट के मुख्य नियम:

  • WHERE क्लॉज़ में, कोर तारीख फ़ील्ड का इस्तेमाल किया जा सकता है. इसके लिए, SELECT क्लॉज़ में उसे शामिल करने की ज़रूरत नहीं है. आपके पास दोनों क्लॉज़ में फ़ील्ड शामिल करने का विकल्प भी है.

    इस उदाहरण की क्वेरी, तारीख की सीमा के दौरान कैंपेन के नाम के हिसाब से clicks मेट्रिक दिखाती है. ध्यान दें कि segments.date को SELECT क्लॉज़ में शामिल नहीं किया गया है.

    SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

  • अगर आपने SELECT क्लॉज़ में कोई मुख्य तारीख फ़ील्ड शामिल किया है, तो आपको WHERE क्लॉज़ में कोई तय तारीख या तारीख की सीमा तय करनी होगी. SELECT और WHERE क्लॉज़ में बताए गए फ़ील्ड मैच होने ज़रूरी नहीं हैं.

    इस उदाहरण की क्वेरी, तारीख की सीमा के सभी दिनों के लिए, कैंपेन के नाम के हिसाब से clicks मेट्रिक दिखाती है. ये मेट्रिक, महीने के हिसाब से सेगमेंट की गई होती हैं.

    SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

ISO 8601 के मुताबिक तारीखें

तारीखों और तारीख की सीमाओं की जानकारी देने के लिए, YYYY-MM-DD (ISO 8601) फ़ॉर्मैट का इस्तेमाल किया जा सकता है. उदाहरण के लिए:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

तारीख के उन मुख्य सेगमेंट के लिए जिनमें समयावधि (segments.week, segments.month, segments.quarter) की ज़रूरत होती है, समयावधि के पहले दिन के साथ = ऑपरेटर का इस्तेमाल किया जा सकता है. उदाहरण के लिए:

WHERE segments.month = '2022-06-01'

पहले से तय तारीखें

यहां दी गई तारीखों और तारीख की सीमाओं का भी इस्तेमाल किया जा सकता है:

पहले से तय तारीखें
TODAY सिर्फ़ आज के लिए.
YESTERDAY सिर्फ़ कल के लिए.
LAST_7_DAYS पिछले सात दिन, जिसमें आज शामिल नहीं है.
LAST_BUSINESS_WEEK पिछले पांच दिन का कारोबारी हफ़्ता (सोमवार से शुक्रवार).
THIS_MONTH मौजूदा महीने के सभी दिन.
LAST_MONTH पिछले महीने के सभी दिन.
LAST_14_DAYS आज को छोड़कर, पिछले 14 दिन.
LAST_30_DAYS पिछले 30 दिन (आज को छोड़कर).
THIS_WEEK_SUN_TODAY पिछले रविवार और मौजूदा दिन के बीच की अवधि.
THIS_WEEK_MON_TODAY पिछले सोमवार से लेकर मौजूदा दिन के बीच की अवधि.
LAST_WEEK_SUN_SAT पिछले रविवार से शुरू होने वाली सात दिनों की अवधि.
LAST_WEEK_MON_SUN पिछले सोमवार से शुरू होने वाली सात दिनों की अवधि.

उदाहरण:

WHERE segments.date DURING LAST_30_DAYS

शून्य मेट्रिक

क्वेरी लागू करने पर, आपको कुछ इकाइयों के लिए मेट्रिक की वैल्यू शून्य दिख सकती है. अपनी क्वेरी में शून्य मेट्रिक को मैनेज करने का तरीका जानें.

UNKNOWN enum types

अगर कोई संसाधन UNKNOWN enum डेटा टाइप के साथ दिखाया जाता है, तो इसका मतलब है कि एपीआई वर्शन में यह टाइप पूरी तरह से काम नहीं करता. ऐसा हो सकता है कि इन संसाधनों को, दूसरे इंटरफ़ेस की मदद से बनाया गया हो. उदाहरण के लिए, Search Ads 360 के यूज़र इंटरफ़ेस (यूआई) में नया कैंपेन या विज्ञापन जोड़ा गया है, लेकिन फ़िलहाल वह एपीआई के उस वर्शन में काम नहीं करता जिससे आपने क्वेरी की है.

किसी संसाधन का टाइप UNKNOWN होने पर भी, मेट्रिक चुनी जा सकती हैं. हालांकि, आपको इन बातों का ध्यान रखना होगा:

  • UNKNOWN टाइप वाले संसाधन के लिए, बाद में सहायता मिल सकती है. हालांकि, यह संसाधन कभी भी UNKNOWN टाइप का रह सकता है.
  • UNKNOWN टाइप वाले नए ऑब्जेक्ट कभी भी दिख सकते हैं. ये ऑब्जेक्ट, पुराने सिस्टम के साथ काम करते हैं, क्योंकि वैल्यू पहले से उपलब्ध है. हम इस बदलाव के साथ संसाधनों को उपलब्ध कराते हैं, ताकि आपके पास अपने खाते की सटीक जानकारी हो. UNKNOWN रिसॉर्स, आपके खाते में किसी दूसरे इंटरफ़ेस से की गई नई गतिविधि की वजह से दिख सकता है. इसके अलावा, किसी रिसॉर्स के लिए अब आधिकारिक तौर पर सहायता उपलब्ध न होने की वजह से भी यह दिख सकता है.
  • UNKNOWN संसाधनों में ज़्यादा जानकारी वाली मेट्रिक हो सकती हैं, जिनके लिए आपके पास क्वेरी करने का विकल्प होता है.
  • UNKNOWN संसाधन, आम तौर पर Search Ads 360 के यूज़र इंटरफ़ेस (यूआई) में पूरी तरह से दिखते हैं.