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

इस गाइड में, 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 में वैल्यू दिखाता है. ध्यान दें कि वर्शन के हिसाब से, बदलाव करने की सुविधा अलग-अलग हो सकती है. उदाहरण के लिए, VideoResponsiveAdInfo पर मौजूद Ad में, वर्शन 24 और उसके बाद के वर्शन में बदलाव किया जा सकता है.

संसाधनों के नाम

हर संसाधन की पहचान, resource_name स्ट्रिंग से होती है. इसमें संसाधन और उसके पैरंट को पाथ में जोड़ा जाता है. उदाहरण के लिए, कैंपेन के संसाधन के नाम इस फ़ॉर्मैट में होते हैं:

customers/customer_id/campaigns/campaign_id

इसलिए, Google Ads के उस खाते में मौजूद 987654 आईडी वाले कैंपेन का resource_name यह होगा जिसका ग्राहक आईडी 1234567 है:

customers/1234567/campaigns/987654

सेवाएं

सेवाओं की मदद से, Google Ads की इकाइयों को वापस पाया जा सकता है और उनमें बदलाव किया जा सकता है. सेवाएं तीन तरह की होती हैं: बदलाव करने वाली सेवाएं, ऑब्जेक्ट और आंकड़ों को वापस पाने वाली सेवाएं, और मेटाडेटा को वापस पाने वाली सेवाएं.

ऑब्जेक्ट में बदलाव करना (म्यूटेट करना)

संसाधन के हिसाब से सेवाएं, mutate अनुरोध का इस्तेमाल करके, उससे जुड़े संसाधन टाइप के इंस्टेंस में बदलाव करती हैं. `GoogleAdsService.Mutate` का इस्तेमाल करके, एक ही अनुरोध में कई तरह के संसाधनों में एक साथ बदलाव किए जा सकते हैं. जैसे, कैंपेन का बजट, कैंपेन, और विज्ञापन ग्रुप एक साथ बनाना.GoogleAdsService.Mutate

संसाधन के हिसाब से सेवाओं के उदाहरण:

• CustomerService ग्राहकों में बदलाव करने के लिए, customers.

• 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 RPC गड़बड़ी के साथ फ़ेल हो जाता है (partial_failure = false). इसके अलावा, partial_failure = true होने पर, ऑपरेशन से जुड़ी गड़बड़ियों के साथ सामान्य जवाब मिलता है. ये गड़बड़ियां, partial_failure_error में दिखती हैं.

validate_only सुविधा, नीति के सामान्य उल्लंघनों के लिए विज्ञापनों की जांच करने में खास तौर पर काम आती है. अगर विज्ञापन, नीतियों का उल्लंघन करते हैं, तो उन्हें अपने-आप अस्वीकार कर दिया जाता है. जैसे, उनमें कुछ खास शब्द, विराम चिह्न, कैपिटल लेटर या तय सीमा से ज़्यादा वर्ण शामिल होना. एक खराब विज्ञापन की वजह से, पूरा बैच फ़ेल हो सकता है. validate_only अनुरोध में, किसी नए विज्ञापन की जांच करने से, ऐसे उल्लंघनों के बारे में पता चल सकता है. नीति के उल्लंघन से जुड़ी गड़बड़ियों को ठीक करने के बारे में जानने के लिए, कोड का उदाहरण देखें.

ऑब्जेक्ट और परफ़ॉर्मेंस के आंकड़े पाना

GoogleAdsService , ऑब्जेक्ट और परफ़ॉर्मेंस के आंकड़े वापस पाने के लिए, एक ही और यूनिफ़ाइड सेवा है.

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

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

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

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