इस गाइड में, Google Ads API के मुख्य कॉम्पोनेंट के बारे में बताया गया है. Google Ads API में संसाधन और सेवाएं शामिल हैं. संसाधन, Google Ads की इकाई को दिखाता है. वहीं, सेवाएं Google Ads की इकाइयों को वापस लाती हैं और उनमें बदलाव करती हैं.
ऑब्जेक्ट की हैरारकी
Google Ads खाते को ऑब्जेक्ट की हैरारकी के तौर पर देखा जा सकता है.
किसी खाते का टॉप-लेवल रिसॉर्स, ग्राहक होता है.
हर ग्राहक के पास एक या उससे ज़्यादा चालू कैंपेन होते हैं.
हर कैंपेन में एक या उससे ज़्यादा विज्ञापन ग्रुप होते हैं. इनका इस्तेमाल, आपके विज्ञापनों को लॉजिकल कलेक्शन में ग्रुप करने के लिए किया जाता है.
विज्ञापन ग्रुप का विज्ञापन, उस विज्ञापन को दिखाता है जिसे किसी विज्ञापन ग्रुप में चलाया जा रहा है. ऐप्लिकेशन कैंपेन के हर विज्ञापन ग्रुप में सिर्फ़ एक विज्ञापन ग्रुप विज्ञापन हो सकता है. हालांकि, अन्य कैंपेन के हर विज्ञापन ग्रुप में एक या उससे ज़्यादा विज्ञापन ग्रुप विज्ञापन हो सकते हैं.
परफ़ॉर्मेंस मैक्स कैंपेन का स्ट्रक्चर, अन्य कैंपेन टाइप से अलग होता है: विज्ञापन ग्रुप और विज्ञापन ग्रुप के विज्ञापनों के बजाय, परफ़ॉर्मेंस मैक्स कैंपेन में ऐसेट ग्रुप होते हैं. AssetGroupAsset का इस्तेमाल करके, क्रिएटिव ऐसेट को किसी ऐसेट ग्रुप से लिंक किया जा सकता है. साथ ही, AssetGroupSignal का इस्तेमाल करके, ऑडियंस या सर्च थीम के सिग्नल अटैच किए जा सकते हैं.
किसी विज्ञापन ग्रुप या कैंपेन में एक या उससे ज़्यादा AdGroupCriterion या CampaignCriterion रिसॉर्स अटैच किए जा सकते हैं. ये ऐसी शर्तें हैं जिनसे यह तय होता है कि विज्ञापन कैसे ट्रिगर होंगे.
शर्त के कई टाइप होते हैं, जैसे कि कीवर्ड, उम्र की सीमा, और जगहें. कैंपेन लेवल पर तय की गई शर्तें, कैंपेन में मौजूद अन्य सभी संसाधनों पर असर डालती हैं. AdGroupAd.start_date_time और AdGroupAd.end_date_time का इस्तेमाल करके, कैंपेन या अलग-अलग विज्ञापनों के लिए बजट के साथ-साथ, शुरू और खत्म होने की तारीख और समय भी तय किया जा सकता है.
आखिर में, खाते, कैंपेन, विज्ञापन ग्रुप या ऐसेट ग्रुप के लेवल पर ऐसेट अटैच की जा सकती हैं. ऐसेट की मदद से, विज्ञापनों में ज़्यादा जानकारी जोड़ी जा सकती है. जैसे, फ़ोन नंबर, मोहल्ले का पता या प्रमोशन. ऐसेट की खास जानकारी देखें.
संसाधन
संसाधन, आपके Google Ads खाते में मौजूद इकाइयों को दिखाते हैं.
Campaign और AdGroup,
संसाधनों के दो उदाहरण हैं.
ऑब्जेक्ट आईडी
Google Ads में हर ऑब्जेक्ट की पहचान उसके आईडी से होती है. इनमें से कुछ आईडी, सभी Google Ads खातों के लिए दुनिया भर में यूनीक होते हैं. वहीं, कुछ आईडी सिर्फ़ एक सीमित दायरे में यूनीक होते हैं.
| ऑब्जेक्ट आईडी | यूनीकनेस का दायरा | क्या यह दुनिया भर में यूनीक है? |
|---|---|---|
| बजट ID | ग्लोबल | हां |
| कैंपेन आईडी | ग्लोबल | हां |
| विज्ञापन समूह आईडी | ग्लोबल | हां |
| विज्ञापन आईडी | विज्ञापन ग्रुप | नहीं, लेकिन (AdGroupId, AdId) पेयर, दुनिया भर में यूनीक है. एक AdId को कई विज्ञापन ग्रुप के साथ शेयर करने की अनुमति नहीं है. |
| AdGroupCriterion आईडी | विज्ञापन ग्रुप | नहीं, लेकिन (AdGroupId, CriterionId) पेयर दुनिया भर में यूनीक है |
| CampaignCriterion ID | कैंपेन | नहीं, लेकिन (CampaignId, CriterionId) पेयर दुनिया भर में यूनीक है |
| लेबल ID | ग्राहक | नहीं, लेकिन (CustomerId, LabelId) पेयर दुनिया भर में यूनीक है |
| UserList ID | ग्लोबल | हां |
| एसेट का आईडी | ग्लोबल | हां |
आईडी के ये नियम, Google Ads ऑब्जेक्ट के लिए लोकल स्टोरेज डिज़ाइन करते समय काम आ सकते हैं.
कुछ ऑब्जेक्ट का इस्तेमाल, कई तरह की इकाइयों के लिए किया जा सकता है. ऐसे मामलों में, ऑब्जेक्ट में एक type फ़ील्ड होता है, जो उसके कॉन्टेंट के बारे में बताता है. उदाहरण के लिए,
AdGroupAd किसी ऑब्जेक्ट को रेफ़र कर सकता है. जैसे, रिस्पॉन्सिव सर्च विज्ञापन (सर्च क्वेरी के हिसाब से ढल जाने वाले विज्ञापन), होटल विज्ञापन या मांग बढ़ाने में मदद करने वाला विज्ञापन. इस वैल्यू को AdGroupAd.ad.type फ़ील्ड से ऐक्सेस किया जा सकता है. साथ ही, यह AdType enum में वैल्यू दिखाती है. ध्यान दें कि
म्यूटबिलिटी, वर्शन के हिसाब से अलग-अलग हो सकती है. उदाहरण के लिए, Ad पर VideoResponsiveAdInfo को
v24 और उसके बाद के वर्शन में बदला जा सकता है.
संसाधन के नाम
हर संसाधन की पहचान, resource_name स्ट्रिंग से की जाती है. यह स्ट्रिंग, संसाधन और उसके पैरंट को एक पाथ में जोड़ती है. उदाहरण के लिए, कैंपेन के संसाधन के नाम इस फ़ॉर्मैट में होते हैं:
customers/customer_id/campaigns/campaign_id
इसलिए, ग्राहक आईडी 1234567 वाले Google Ads खाते में, आईडी 987654 वाले कैंपेन के लिए, resource_name यह होगा:
customers/1234567/campaigns/987654
सेवाएं
सेवाओं की मदद से, Google Ads की इकाइयों को वापस लाया जा सकता है और उनमें बदलाव किया जा सकता है. सेवाएं तीन तरह की होती हैं: बदलाव करने की सेवा, ऑब्जेक्ट और आंकड़े वापस पाने की सेवा, और मेटाडेटा वापस पाने की सेवा.
ऑब्जेक्ट में बदलाव करना
संसाधन के हिसाब से सेवाएं, mutate अनुरोध का इस्तेमाल करके, उससे जुड़े संसाधन टाइप के इंस्टेंस में बदलाव करती हैं. एक ही अनुरोध में कई तरह के संसाधनों में बदलाव करने के लिए, GoogleAdsService.Mutate का इस्तेमाल भी किया जा सकता है. जैसे, कैंपेन का बजट, कैंपेन, और विज्ञापन ग्रुप को एक साथ बनाना.
संसाधन के हिसाब से सेवाओं के उदाहरण:
ग्राहकों में बदलाव करने के लिए
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 पर सेट करें. अनुरोध की पूरी तरह से पुष्टि की जाती है, जैसे कि उसे लागू किया जाने वाला हो. हालांकि,
आखिरी चरण को छोड़ दिया जाता है. अगर कोई गड़बड़ी नहीं मिलती है, तो जवाब में कोई भी बदला हुआ नतीजा नहीं दिखता है. इसका मतलब है कि results खाली है. अगर पुष्टि नहीं हो पाती है, तो अनुरोध डिफ़ॉल्ट रूप से GoogleAdsFailure आरपीसी गड़बड़ी (partial_failure = false) के साथ पूरा नहीं हो पाता है. इसके अलावा, partial_failure = true होने पर, partial_failure_error में कार्रवाई से जुड़ी गड़बड़ियों के साथ सामान्य जवाब मिलता है.
validate_only, नीति के सामान्य उल्लंघनों के लिए विज्ञापनों की जांच करने में खास तौर पर मददगार है. अगर विज्ञापन, नीतियों का उल्लंघन करते हैं, तो उन्हें अपने-आप अस्वीकार कर दिया जाता है. जैसे, कुछ खास शब्दों, विराम चिह्न, कैपिटल लेटर या लंबाई से जुड़ी नीतियों का उल्लंघन करना. एक खराब विज्ञापन की वजह से,
पूरा बैच फ़ेल हो सकता है. validate_only के अनुरोध में नए विज्ञापन की जांच करने से, इस तरह के उल्लंघनों का पता चल सकता है. नीति के उल्लंघन से जुड़ी गड़बड़ियों को मैनेज करने के लिए, कोड का उदाहरण देखें. इससे आपको पता चलेगा कि यह कैसे काम करता है.
ऑब्जेक्ट और परफ़ॉर्मेंस के आंकड़े पाना
GoogleAdsService, ऑब्जेक्ट और परफ़ॉर्मेंस के आंकड़े पाने के लिए एक ही सेवा है.
GoogleAdsService के लिए सभी Search और SearchStream अनुरोधों के लिए, एक क्वेरी की ज़रूरत होती है. इस क्वेरी में, क्वेरी किए जाने वाले संसाधन, वापस पाने के लिए संसाधन एट्रिब्यूट और परफ़ॉर्मेंस मेट्रिक, अनुरोध को फ़िल्टर करने के लिए इस्तेमाल किए जाने वाले प्रेडिकेट, और परफ़ॉर्मेंस के आंकड़ों को और ज़्यादा बांटने के लिए इस्तेमाल किए जाने वाले सेगमेंट की जानकारी दी जाती है. क्वेरी फ़ॉर्मैट के बारे में ज़्यादा जानकारी के लिए, Google Ads क्वेरी लैंग्वेज गाइड देखें.
मेटाडेटा वापस पाना
GoogleAdsFieldService, Google Ads API में मौजूद संसाधनों का मेटाडेटा हासिल करता है. जैसे, किसी संसाधन के लिए उपलब्ध एट्रिब्यूट और उसका डेटा टाइप. इस सेवा के बारे में क्वेरी करने के लिए, संसाधन के मेटाडेटा की गाइड देखें.
इस सेवा से, GoogleAdsService को क्वेरी बनाने के लिए ज़रूरी जानकारी मिलती है. आपकी सुविधा के लिए, GoogleAdsFieldService से मिलने वाली जानकारी, फ़ील्ड के रेफ़रंस दस्तावेज़ में भी उपलब्ध है.