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

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

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 ऐसा अनुरोध भी उपलब्ध कराते हैं जिससे किसी एक संसाधन का इंस्टेंस वापस मिलता है. यह संसाधन के स्ट्रक्चर की जांच करने के लिए काम आ सकता है.

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

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

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

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

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

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

पीछे जाएं
खास जानकारी
आगे बढ़ें
वर्शन