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 फ़ील्ड सेट होते हैं. साथ ही, इसमें 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 जैसे संसाधन फ़ील्ड को चुना है, तो campaign.resource_name अपने-आप वापस आ जाएगा और campaign के आधार पर सेगमेंट किया जाएगा. ऐसा इसलिए, क्योंकि campaign, campaign_budget का सेगमेंट करने वाला संसाधन है.campaign.name

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

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

कुछ 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 क्लॉज़ में कई सेगमेंट तय किए जा सकते हैं. जवाब में, SearchAds360Row ऑब्जेक्ट शामिल होता है. यह ऑब्जेक्ट, FROM क्लॉज़ में बताए गए मुख्य संसाधन के हर instance और चुने गए हर segment फ़ील्ड की value के हर combination के लिए होता है.

उदाहरण के लिए, इस क्वेरी से 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 टाइप की सूची

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

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

  • UNKNOWN टाइप वाले संसाधन के लिए, बाद में सहायता उपलब्ध कराई जा सकती है. हालांकि, यह हमेशा के लिए UNKNOWN स्थिति में भी रह सकता है.

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

  • UNKNOWN संसाधनों से जुड़ी ज़्यादा जानकारी वाली मेट्रिक हो सकती हैं. इन्हें क्वेरी किया जा सकता है.

  • UNKNOWN संसाधन आम तौर पर, Search Ads 360 के यूज़र इंटरफ़ेस (यूआई) में पूरी तरह से दिखते हैं.