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

ondemand_video वीडियो: साल 2019 की वर्कशॉप में, सेवाओं और संसाधनों के बारे में हुई बातचीत देखें

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

ऑब्जेक्ट की हैरारकी

Google Ads खाते को ऑब्जेक्ट की हैरारकी के तौर पर देखा जा सकता है.

• किसी खाते का सबसे ऊपर का संसाधन, ग्राहक होता है.

• हर ग्राहक के पास एक या उससे ज़्यादा चालू कैंपेन होते हैं.

• हर कैंपेन में एक या उससे ज़्यादा विज्ञापन ग्रुप होते हैं. इनका इस्तेमाल आपके विज्ञापनों को लॉजिकल कलेक्शन में ग्रुप करने के लिए किया जाता है.

• एक विज्ञापन ग्रुप का विज्ञापन, आपके दिखाए जा रहे विज्ञापन को दिखाता है. हर विज्ञापन ग्रुप में एक या उससे ज़्यादा विज्ञापन ग्रुप के विज्ञापन होते हैं. हालांकि, ऐप्लिकेशन कैंपेन के हर विज्ञापन ग्रुप में, सिर्फ़ एक विज्ञापन ग्रुप का विज्ञापन हो सकता है.

किसी विज्ञापन ग्रुप या कैंपेन में, एक या उससे ज़्यादा AdGroupCriterion या CampaignCriterion जोड़े जा सकते हैं. ये ऐसे मानदंड होते हैं जिनसे यह तय होता है कि विज्ञापन कैसे ट्रिगर होते हैं.

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

आखिर में, खाते, कैंपेन या विज्ञापन ग्रुप के लेवल पर एसेट जोड़ी जा सकती हैं. एसेट की मदद से, अपने विज्ञापनों में फ़ोन नंबर, पते या प्रमोशन जैसी ज़्यादा जानकारी दी जा सकती है. एसेट की खास जानकारी देखें.

संसाधन

संसाधन, आपके Google Ads खाते में मौजूद इकाइयों को दिखाते हैं. Campaign और AdGroup, संसाधनों के दो उदाहरण हैं.

ऑब्जेक्ट आईडी

Google Ads में मौजूद हर ऑब्जेक्ट की पहचान, उसके आईडी से होती है. इनमें से कुछ आईडी, Google Ads के सभी खातों में यूनीक होते हैं. वहीं, कुछ आईडी सिर्फ़ सीमित दायरे में यूनीक होते हैं.

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 ग्राहकों में बदलाव करने के लिए, customers.

• CampaignService कैंपेन में बदलाव करने के लिए, कैंपेन.

• AdGroupService विज्ञापन ग्रुप में बदलाव करने के लिए, ad groups.

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 Query Language की गाइड.

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

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

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