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

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 एनम में दिखती है.

संसाधन के नाम

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

customers/customer_id/campaigns/campaign_id

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

customers/1234567/campaigns/987654

सेवाएं

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

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

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

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

• ग्राहकों में बदलाव करने के लिए, 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 पर सेट करें. इसके बाद, अनुरोध की पूरी तरह से पुष्टि की जाएगी, जैसे कि उसे लागू किया जा रहा हो. हालांकि, आखिर में उसे लागू नहीं किया जाएगा. अगर कोई गड़बड़ी नहीं मिलती है, तो खाली रिस्पॉन्स दिखता है. अगर पुष्टि नहीं हो पाती है, तो जवाब में गड़बड़ी के मैसेज से, गड़बड़ी के पॉइंट का पता चलेगा.

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

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

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

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

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

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

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