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 को वापस लाया जाता है, तो एपीआई इसके id और name फ़ील्ड के सेट वाले कैंपेन ऑब्जेक्ट वाला SearchAds360Row दिखाता है. साथ ही, 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 रिसॉर्स फ़ील्ड campaign.name चुना जाता है, तो 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 क्लॉज़ में बताए गए मुख्य संसाधन के इंस्टेंस के हर कॉम्बिनेशन और चुने गए हर segment फ़ील्ड की वैल्यू के लिए, एक SearchAds360Row ऑब्जेक्ट शामिल होता है.

उदाहरण के लिए, नीचे दी गई क्वेरी 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 मेट्रिक दिखाती है. ध्यान दें कि SELECT क्लॉज़ में segments.date को शामिल नहीं किया गया है.

    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 डेटा टाइप के साथ दिया जाता है, तो इसका मतलब है कि वह टाइप, एपीआई वर्शन के साथ पूरी तरह से काम नहीं करता. मुमकिन है कि इन रिसॉर्स को अन्य इंटरफ़ेस से बनाया गया हो. उदाहरण के लिए, Search Ads 360 यूज़र इंटरफ़ेस (यूआई) में एक नया कैंपेन या विज्ञापन दिखाया गया है, लेकिन उसे एपीआई के जिस वर्शन के लिए क्वेरी की जा रही है वह फ़िलहाल उस वर्शन में काम नहीं कर रहा है.

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

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