वीडियो: साल 2019 की वर्कशॉप में हुई 'सेवाओं और संसाधनों' के बारे में बातचीत देखें
इस गाइड में, Google Ads API के मुख्य कॉम्पोनेंट के बारे में जानकारी दी गई है. Google Ads API में संसाधन और सेवाएं शामिल हैं. संसाधन किसी Google Ads इकाई को दिखाता है, जबकि सेवाएं, Google Ads की इकाइयों को दिखाती हैं और उनमें बदलाव करती हैं.
ऑब्जेक्ट की हैरारकी
Google Ads खाते को ऑब्जेक्ट की हैरारकी के तौर पर देखा जा सकता है.
किसी खाते का टॉप-लेवल संसाधन ग्राहक होता है.
हर ग्राहक में एक या उससे ज़्यादा सक्रिय कैंपेन होते हैं.
हर कैंपेन में एक या ज़्यादा विज्ञापन ग्रुप होते हैं. इनका इस्तेमाल आपके विज्ञापनों को लॉजिकल कलेक्शन में ग्रुप करने के लिए किया जाता है.
विज्ञापन समूह विज्ञापन उस विज्ञापन को दिखाता है, जिसे आप चला रहे हैं. जिन ऐप्लिकेशन कैंपेन में हर विज्ञापन समूह में सिर्फ़ एक विज्ञापन समूह का विज्ञापन हो सकता है, उन्हें छोड़कर हर विज्ञापन समूह में एक या उससे ज़्यादा विज्ञापन समूह के विज्ञापन होते हैं.
किसी विज्ञापन ग्रुप या कैंपेन में, एक या एक से ज़्यादा AdGroupCriterion
या CampaignCriterion अटैच किए जा सकते हैं. ये मानदंड दिखाते हैं कि विज्ञापन कैसे ट्रिगर होंगे.
शर्त के कई टाइप होते हैं, जैसे कि कीवर्ड, उम्र सीमा, और जगह. अभियान स्तर पर निर्धारित मानदंड अभियान के अन्य सभी संसाधनों को प्रभावित करते हैं. पूरे कैंपेन के लिए बजट और तारीखें भी तय की जा सकती हैं.
आखिर में, खाता, कैंपेन या विज्ञापन ग्रुप के लेवल पर एक्सटेंशन अटैच किए जा सकते हैं. एक्सटेंशन की मदद से, अपने विज्ञापनों में अतिरिक्त जानकारी दी जा सकती है, जैसे कि फ़ोन नंबर, मोहल्ले का पता या प्रमोशन.
रिसॉर्स
संसाधन, आपके Google Ads खाते में मौजूद इकाइयों को दिखाते हैं. Campaign और AdGroup संसाधनों के दो उदाहरण हैं.
ऑब्जेक्ट के आईडी
Google Ads में हर ऑब्जेक्ट की पहचान उसके अपने आईडी से की जाती है. इनमें से कुछ आईडी सभी Google Ads खातों में दुनिया भर में यूनीक होते हैं. वहीं, कुछ आईडी सिर्फ़ सीमित दायरे में यूनीक होते हैं.
| ऑब्जेक्ट आईडी | यूनीक वैल्यू का दायरा | दुनिया भर में सबसे अलग? |
|---|---|---|
| बजट ID | दुनिया भर में | हां |
| कैंपेन का आईडी | दुनिया भर में | हां |
| विज्ञापन समूह आईडी | दुनिया भर में | हां |
| विज्ञापन का आईडी | विज्ञापन ग्रुप | नहीं, लेकिन (AdGroupId, AdId) की जोड़ी दुनिया भर में खास है |
| विज्ञापन समूह शर्तों की आईडी | विज्ञापन ग्रुप | नहीं, लेकिन (AdGroupId, CriterionId) की जोड़ी दुनिया भर में खास है |
| अभियान मानदंड ID | कैंपेन | नहीं, लेकिन (CampaignId, CriterionId) की जोड़ी दुनिया भर में खास है |
| विज्ञापन एक्सटेंशन | कैंपेन | नहीं, लेकिन (CampaignId, AdExtensionId) की जोड़ी दुनिया भर में खास है |
| फ़ीड ID | दुनिया भर में | हां |
| फ़ीड आइटम की ID | दुनिया भर में | हां |
| फ़ीड विशेषता आईडी | फ़ीड | नहीं |
| फ़ीड मैपिंग ID | दुनिया भर में | हां |
| लेबल ID | दुनिया भर में | हां |
| UserList आईडी | दुनिया भर में | हां |
ये आईडी नियम आपके Google Ads ऑब्जेक्ट के लिए लोकल स्टोरेज डिज़ाइन करते समय काम आ सकते हैं.
कुछ ऑब्जेक्ट का इस्तेमाल, एक से ज़्यादा तरह की इकाई के लिए किया जा सकता है. ऐसे मामलों में, ऑब्जेक्ट में
एक type फ़ील्ड होता है, जो इसकी कॉन्टेंट की जानकारी देता है. उदाहरण के लिए,
AdGroupAd का मतलब टेक्स्ट विज्ञापन, होटल विज्ञापन या स्थानीय विज्ञापन जैसा कोई ऑब्जेक्ट हो सकता है. इस वैल्यू को
AdGroupAd.ad.type फ़ील्ड से ऐक्सेस किया जा सकता है और यह
AdType enum में वैल्यू दिखाता है.
संसाधनों के नाम
हर रिसॉर्स की पहचान, resource_name स्ट्रिंग से खास तौर पर की जाती है. यह स्ट्रिंग, रिसॉर्स और उसके पैरंट को पाथ में जोड़ती है. उदाहरण के लिए, कैंपेन
संसाधन के नामों में यह फ़ॉर्म होता है:
customers/customer_id/campaigns/campaign_id
इसलिए, Google Ads खाते में ग्राहक आईडी 1234567 वाले कैंपेन के लिए, 987654 आईडी वाला कैंपेन resource_name होगा:
customers/1234567/campaigns/987654
सेवाएं
सेवाओं की मदद से, Google Ads की इकाइयों को वापस पाया जा सकता है और उनमें बदलाव किया जा सकता है. सेवाएं तीन तरह की होती हैं: उनमें बदलाव करना, ऑब्जेक्ट और आंकड़े वापस पाना, और मेटाडेटा वापस पाना.
ऑब्जेक्ट में बदलाव करना
ये सेवाएं, mutate अनुरोध का इस्तेमाल करके, इससे जुड़े किसी संसाधन टाइप के इंस्टेंस में बदलाव करती हैं. वे एक ऐसा get अनुरोध भी उपलब्ध कराते हैं जो सिंगल रिसॉर्स इंस्टेंस को फिर से हासिल करता है. इससे किसी संसाधन के स्ट्रक्चर की जांच करने में मदद मिल सकती है.
सेवाओं के उदाहरण:
ग्राहकों में बदलाव करने के लिए
CustomerService.कैंपेन में बदलाव करने के लिए
CampaignService.विज्ञापन ग्रुप में बदलाव करने के लिए
AdGroupService.
हर mutate अनुरोध में, उससे जुड़े operation ऑब्जेक्ट शामिल होने चाहिए. उदाहरण के लिए, CampaignService.MutateCampaigns तरीके के लिए, CampaignOperation के एक या एक से ज़्यादा इंस्टेंस की ज़रूरत होती है. कार्रवाइयों के बारे में ज़्यादा जानकारी के लिए, ऑब्जेक्ट बदलना और उनकी जांच करना लेख देखें.
समवर्ती म्यूटेट
किसी Google Ads ऑब्जेक्ट में एक ही समय में एक से ज़्यादा सोर्स से बदलाव नहीं किया जा सकता. अगर आपके ऐप्लिकेशन में कई उपयोगकर्ता एक ही ऑब्जेक्ट को अपडेट करते हैं या एक से ज़्यादा थ्रेड का इस्तेमाल करके Google Ads ऑब्जेक्ट में एक साथ बदलाव करते हैं, तो इससे गड़बड़ियां हो सकती हैं. इसमें एक ही ऐप्लिकेशन में कई थ्रेड से या अलग-अलग ऐप्लिकेशन से ऑब्जेक्ट को अपडेट करना शामिल है (उदाहरण के लिए, आपका ऐप्लिकेशन और एक साथ होने वाला Google Ads यूज़र इंटरफ़ेस (यूआई) सेशन).
एपीआई, अपडेट करने से पहले किसी ऑब्जेक्ट को लॉक करने का तरीका नहीं देता. अगर दो सोर्स एक साथ किसी ऑब्जेक्ट में बदलाव करने की कोशिश करते हैं, तो एपीआई DatabaseError.CONCURRENT_MODIFICATION_ERROR को बढ़ाता है.
एसिंक्रोनस बनाम सिंक्रोनस म्यूटेट
Google Ads API में बदलाव करने के तरीके सिंक्रोनस होते हैं. एपीआई कॉल, ऑब्जेक्ट में बदलाव करने के बाद ही रिस्पॉन्स देते हैं. इसलिए, आपको हर अनुरोध के रिस्पॉन्स के लिए इंतज़ार करना पड़ता है. यह तरीका कोड करने के मुकाबले आसान है. हालांकि, अगर प्रोसेस को पूरा होने के लिए इंतज़ार करना पड़ता है, तो लोड बैलेंस करने और संसाधनों की बर्बादी करने पर इसका बुरा असर पड़ सकता है.
इसके अलावा, BatchJobService का इस्तेमाल करके, ऑब्जेक्ट में एसिंक्रोनस रूप से बदलाव किया जा सकता है. यह सुविधा, कई सेवाओं के पूरा होने का इंतज़ार किए बिना उन पर अलग-अलग तरह की कार्रवाइयों के बैच परफ़ॉर्म करती है. बैच जॉब सबमिट होने के बाद, Google Ads API सर्वर एसिंक्रोनस तरीके से काम करते हैं. इससे अन्य कार्रवाइयां करने के लिए कोई प्रोसेस नहीं होती. आप समय-समय पर नौकरी की स्थिति
देखकर देख सकते हैं कि काम पूरा हुआ है या नहीं.
एसिंक्रोनस प्रोसेसिंग के बारे में ज़्यादा जानकारी के लिए, बैच प्रोसेसिंग गाइड देखें.
पुष्टि में बदलाव करें
ज़्यादातर बदलाव करने के अनुरोधों की पुष्टि, असल डेटा के साथ कॉल को लागू किए बिना की जा सकती है. कार्रवाई को असल में लागू किए बिना, छूटे हुए पैरामीटर और फ़ील्ड की गलत वैल्यू के लिए अनुरोध की जांच की जा सकती है.
इस सुविधा का इस्तेमाल करने के लिए, अनुरोध के validate_only बूलियन फ़ील्ड को true पर सेट करें. हालांकि, यह फ़ील्ड ज़रूरी नहीं है. इसके बाद, इस अनुरोध की पूरी तरह से पुष्टि हो जाएगी, जैसे कि इसे लागू किया जाएगा. हालांकि, प्रोसेस को पूरा नहीं किया जा सकेगा. कोई गड़बड़ी न मिलने पर, बिना
जवाब वाला एक जवाब दिखता है. अगर पुष्टि नहीं हो पाती है, तो रिस्पॉन्स में गड़बड़ी के मैसेज, फ़ेलियर पॉइंट के बारे में बताएंगे.
validate_only का इस्तेमाल, खास तौर पर नीति के उल्लंघन के लिए विज्ञापनों की जांच करने में किया जा सकता है. अगर विज्ञापन खास शब्दों, विराम चिह्न, कैपिटल लेटर के इस्तेमाल या लंबाई जैसी नीतियों का उल्लंघन करते हैं, तो उन्हें अपने-आप अस्वीकार कर दिया जाता है. एक खराब विज्ञापन
से पूरा बैच विफल हो सकता है. validate_only के अनुरोध में नए विज्ञापन की जांच करने पर, इस तरह के उल्लंघन के किसी भी मामले का पता चल सकता है. नीति के उल्लंघन से जुड़ी गड़बड़ियों को मैनेज करने के बारे में जानने के लिए, कोड का उदाहरण देखें.
ऑब्जेक्ट और परफ़ॉर्मेंस के आंकड़े पाएं
GoogleAdsService, ऑब्जेक्ट और परफ़ॉर्मेंस के आंकड़ों को वापस पाने की सिंगल और यूनिफ़ाइड सेवा है.
GoogleAdsService के लिए सभी Search और SearchStream अनुरोधों के लिए ऐसी क्वेरी की ज़रूरत होती है जिसमें क्वेरी के लिए संसाधन, रिसॉर्स एट्रिब्यूट, और परफ़ॉर्मेंस मेट्रिक की जानकारी हो, अनुरोध को फ़िल्टर करने के लिए अनुमान, और परफ़ॉर्मेंस के आंकड़ों को और ज़्यादा बेहतर तरीके से इस्तेमाल करने के लिए सेगमेंट की जानकारी हो. क्वेरी के फ़ॉर्मैट के बारे में ज़्यादा जानने के लिए,
Google Ads क्वेरी लैंग्वेज गाइड देखें.
मेटाडेटा वापस पाएं
GoogleAdsFieldService, Google Ads API में मौजूद संसाधनों का मेटाडेटा इकट्ठा करता है. जैसे, संसाधन के लिए उपलब्ध एट्रिब्यूट और उसके डेटा टाइप.
यह सेवा GoogleAdsService के लिए क्वेरी बनाने के लिए ज़रूरी जानकारी उपलब्ध कराती है. सुविधा के लिए, GoogleAdsFieldService से मिली जानकारी, फ़ील्ड रेफ़रंस दस्तावेज़ में भी उपलब्ध है.