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

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

सेवा खोजें

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

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

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

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

खोज के तरीके

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'

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

आप पहले से तय की गई इन तारीखों और सीमाओं का भी इस्तेमाल कर सकते हैं:

उदाहरण:

WHERE segments.date DURING LAST_30_DAYS

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

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

UNKNOWN enum types

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

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

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