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 यूज़र इंटरफ़ेस (यूआई) में पूरी तरह दिखते हैं.