एपीआई का स्ट्रक्चर

इस गाइड में, 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 खातों में यूनीक होते हैं. वहीं, कुछ आईडी सिर्फ़ सीमित दायरे में यूनीक होते हैं.

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, ऑब्जेक्ट और परफ़ॉर्मेंस के आंकड़े पाने के लिए एक ही सेवा है.

Search और SearchStream के सभी अनुरोधों के लिए, GoogleAdsService की ज़रूरत होती है. इसमें क्वेरी करने के लिए संसाधन, संसाधन एट्रिब्यूट, और परफ़ॉर्मेंस मेट्रिक शामिल होती हैं. साथ ही, अनुरोध को फ़िल्टर करने के लिए इस्तेमाल किए जाने वाले प्रेडिकेट और परफ़ॉर्मेंस के आंकड़ों को और ज़्यादा ब्रेकडाउन करने के लिए इस्तेमाल किए जाने वाले सेगमेंट भी शामिल होते हैं. क्वेरी फ़ॉर्मैट के बारे में ज़्यादा जानने के लिए, Google Ads क्वेरी लैंग्वेज गाइड देखें.

मेटाडेटा वापस पाना

GoogleAdsFieldService, Google Ads API में मौजूद संसाधनों के बारे में मेटाडेटा को फिर से हासिल करता है. जैसे, किसी संसाधन के लिए उपलब्ध एट्रिब्यूट और उसका डेटा टाइप. इस सेवा के बारे में क्वेरी करने के बारे में जानने के लिए, संसाधन के मेटाडेटा की गाइड देखें.

यह सेवा, GoogleAdsService के लिए क्वेरी बनाने में ज़रूरी जानकारी देती है. आपकी सुविधा के लिए, GoogleAdsFieldService से मिली जानकारी, फ़ील्ड के रेफ़रंस दस्तावेज़ में भी उपलब्ध है.