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

वीडियो: साल 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) की जोड़ी दुनिया भर में यूनीक है
अभियान मापदंड आईडी कैंपेन नहीं, लेकिन (CampaignId, CriterionId) की जोड़ी दुनिया भर में यूनीक है
विज्ञापन एक्सटेंशन कैंपेन नहीं, लेकिन (CampaignId, AdExtensionId) की जोड़ी दुनिया भर में यूनीक है
फ़ीड ID दुनिया भर में हां
फ़ीड आइटम की ID दुनिया भर में हां
फ़ीड विशेषता आईडी फ़ीड नहीं
फ़ीड मैपिंग ID दुनिया भर में हां
लेबल ID दुनिया भर में हां
UserList ID दुनिया भर में हां

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

कुछ ऑब्जेक्ट, एक से ज़्यादा तरह की इकाइयों के लिए इस्तेमाल किए जा सकते हैं. ऐसे मामलों में, ऑब्जेक्ट में एक type फ़ील्ड होता है, जो इसके कॉन्टेंट के बारे में बताता है. उदाहरण के लिए, AdGroupAd टेक्स्ट विज्ञापन, होटल विज्ञापन या स्थानीय विज्ञापन जैसी कोई चीज़ हो सकती है. इस वैल्यू को AdGroupAd.ad.type फ़ील्ड से ऐक्सेस किया जा सकता है और यह AdType एनम में वैल्यू दिखाता है.

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

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

customers/customer_id/campaigns/campaign_id

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

customers/1234567/campaigns/987654

सेवाएं

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

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

ये सेवाएं, mutate अनुरोध का इस्तेमाल करके, इससे जुड़े संसाधन टाइप के इंस्टेंस में बदलाव करती हैं. इनसे ऐसा get अनुरोध भी मिलता है जो किसी एक रिसॉर्स इंस्टेंस को हासिल करता है. इससे किसी रिसॉर्स के स्ट्रक्चर की जांच करने में मदद मिल सकती है.

सेवाओं के उदाहरण:

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 से मिली जानकारी, फ़ील्ड के रेफ़रंस वाले दस्तावेज़ में भी उपलब्ध है.

पीछे जाएं
खास जानकारी
आगे बढ़ें
इकाई के संबंध