इस गाइड में, सभी एपीआई कॉल के सामान्य स्ट्रक्चर के बारे में बताया गया है.
अगर एपीआई के साथ इंटरैक्ट करने के लिए किसी क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो आपको अनुरोध की बुनियादी जानकारी जानने की ज़रूरत नहीं होगी. हालांकि, टेस्टिंग और डीबग करने के दौरान, एपीआई कॉल के स्ट्रक्चर के बारे में कुछ जानकारी काम आ सकती है.
Google Ads API, REST बाइंडिंग के साथ एक gRPC API है. इसका मतलब है कि एपीआई को दो तरीकों से कॉल किया जा सकता है.
पसंदीदा:
अनुरोध के मुख्य हिस्से को प्रोटोकॉल बफ़र के तौर पर बनाएं.
इसे एचटीटीपी/2 का इस्तेमाल करके सर्वर पर भेजें.
प्रोटोकॉल बफ़र में मौजूद जवाब को डीसीरियलाइज़ करता है.
परिणामों की व्याख्या करें.
हमारे ज़्यादातर दस्तावेज़ों में, gRPC का इस्तेमाल करने के बारे में बताया गया है.
ज़रूरी नहीं है:
अनुरोध के मुख्य हिस्से को JSON ऑब्जेक्ट के तौर पर बनाएं.
इसे एचटीटीपी 1.1 का इस्तेमाल करके सर्वर पर भेजें.
रिस्पॉन्स को JSON ऑब्जेक्ट के तौर पर डीसीरियलाइज़ करें.
परिणामों की व्याख्या करें.
REST का इस्तेमाल करने के बारे में ज़्यादा जानकारी के लिए, REST इंटरफ़ेस गाइड देखें.
संसाधन के नाम
एपीआई में मौजूद ज़्यादातर ऑब्जेक्ट की पहचान, उनके संसाधन के नाम वाली स्ट्रिंग से होती है. REST इंटरफ़ेस का इस्तेमाल करते समय, ये स्ट्रिंग यूआरएल के तौर पर भी काम करती हैं. इनके स्ट्रक्चर के लिए, REST इंटरफ़ेस के संसाधन के नाम देखें.
कंपोज़िट आईडी
अगर किसी ऑब्जेक्ट का आईडी दुनिया भर में यूनीक नहीं है, तो उस ऑब्जेक्ट के लिए कंपोज़िट आईडी बनाया जाता है. इसके लिए, उसके पैरंट आईडी और टिल्ड (~) को पहले जोड़ा जाता है.
उदाहरण के लिए, विज्ञापन ग्रुप का विज्ञापन आईडी दुनिया भर में यूनीक नहीं होता. इसलिए, हम इसे यूनीक कंपोज़िट आईडी बनाने के लिए, इसके पैरंट ऑब्जेक्ट (विज्ञापन ग्रुप) आईडी को इससे पहले जोड़ते हैं:
123काAdGroupId+~+45678काAdGroupAdId= कंपोज़िट विज्ञापन123~45678का ग्रुप विज्ञापन आईडी.
अनुरोध के हेडर
ये एचटीटीपी हेडर (या gRPC मेटाडेटा) हैं, जो अनुरोध के मुख्य हिस्से के साथ भेजे जाते हैं:
अनुमति देना
आपको OAuth2 ऐक्सेस टोकन को Authorization: Bearer YOUR_ACCESS_TOKEN के तौर पर शामिल करना होगा. यह टोकन, क्लाइंट की ओर से कार्रवाई करने वाले मैनेजर खाते या विज्ञापन देने वाले व्यक्ति या कंपनी के सीधे तौर पर अपने खाते को मैनेज करने की पहचान करता है. ऐक्सेस टोकन वापस पाने के निर्देश, OAuth2 गाइड में दिए गए हैं. ऐक्सेस टोकन, हासिल करने के एक घंटे तक मान्य होता है. इसकी समयसीमा खत्म होने पर, नया ऐक्सेस टोकन पाने के लिए, ऐक्सेस टोकन को रीफ़्रेश करें. ध्यान दें कि हमारी क्लाइंट लाइब्रेरी, समयसीमा खत्म हो चुके टोकन को अपने-आप रीफ़्रेश करती हैं.
अगर आपको पुष्टि से जुड़ी गड़बड़ियां मिलती हैं, तो पक्का करें कि आपने सही क्रेडेंशियल का इस्तेमाल किया हो और आपके पास ज़रूरी अनुमतियां हों. USER_PERMISSION_DENIED गड़बड़ी से पता चलता है कि पुष्टि किए गए उपयोगकर्ता के पास, अनुरोध में बताए गए ग्राहक खाते का ऐक्सेस नहीं है. अनुमतियां मैनेज करने के बारे में जानकारी पाने के लिए, Google Ads के ऐक्सेस लेवल लेख पढ़ें.
developer-token
डेवलपर टोकन, 22 वर्णों वाली एक स्ट्रिंग होती है. इससे Google Ads API डेवलपर की यूनीक पहचान होती है. डेवलपर टोकन स्ट्रिंग का एक उदाहरण ABcdeFGH93KL-NOPQ_STUv है. डेवलपर टोकन को developer-token : ABcdeFGH93KL-NOPQ_STUv के तौर पर शामिल किया जाना चाहिए.
login-customer-id
यह अनुरोध में इस्तेमाल करने के लिए, अनुमति पा चुके ग्राहक का आईडी है. इसमें हाइफ़न (-) नहीं होते. अगर आपको मैनेजर खाते के ज़रिए ग्राहक खाते का ऐक्सेस मिला है, तो यह हेडर ज़रूरी है. साथ ही, इसे मैनेजर खाते के ग्राहक आईडी पर सेट किया जाना चाहिए. अगर मैनेजर खाते से पुष्टि करते समय login-customer-id शामिल नहीं किया जाता है, तो AuthorizationError.USER_PERMISSION_DENIED गड़बड़ी होती है. इस तरह की गड़बड़ी के बारे में ज़्यादा जानने के लिए, सामान्य गड़बड़ियां देखें.
https://googleads.googleapis.com/v23/customers/1234567890/campaignBudgets:mutate
login-customer-id सेट करने का मतलब है कि आपने Google Ads के यूज़र इंटरफ़ेस (यूआई) में साइन इन करने के बाद कोई खाता चुना है. इसके अलावा, इसका मतलब यह भी हो सकता है कि आपने सबसे ऊपर दाईं ओर मौजूद अपनी प्रोफ़ाइल इमेज पर क्लिक किया है. अगर इस हेडर को शामिल नहीं किया जाता है, तो यह डिफ़ॉल्ट रूप से ऑपरेटिंग कस्टमर पर सेट हो जाता है.
linked-customer-id
इस हेडर का इस्तेमाल सिर्फ़ तीसरे पक्ष के ऐप्लिकेशन ऐनलिटिक्स प्रोवाइडर करते हैं. ऐसा तब किया जाता है, जब वे लिंक किए गए Google Ads खाते में कन्वर्ज़न अपलोड कर रहे हों.
मान लें कि खाता A के उपयोगकर्ता, ThirdPartyAppAnalyticsLink के ज़रिए खाता B को अपनी इकाइयों का डेटा देखने और उनमें बदलाव करने का ऐक्सेस देते हैं.
लिंक होने के बाद, खाता B का कोई उपयोगकर्ता, खाता A के लिए एपीआई कॉल कर सकता है. हालांकि, ऐसा लिंक की ओर से दी गई अनुमतियों के हिसाब से किया जा सकता है. इस मामले में, खाते A के लिए एपीआई कॉल करने की अनुमतियां, खाते A से तीसरे पक्ष के लिंक के हिसाब से तय की जाती हैं. इन्हें मैनेजर खाते के साथ संबंध के हिसाब से तय नहीं किया जाता. मैनेजर खाते के साथ संबंध के हिसाब से, अन्य एपीआई कॉल के लिए अनुमतियां तय की जाती हैं.B
तीसरे पक्ष की ऐप्लिकेशन ऐनलिटिक्स सेवा देने वाली कंपनी, इस तरह एपीआई कॉल करती है:
linked-customer-id: तीसरे पक्ष के ऐप्लिकेशन के आंकड़ों का वह खाता जो डेटा अपलोड करता है (खाताB).customer-id: वह Google Ads खाता जिसमें डेटा अपलोड किया गया है (खाताA).login-customer-idऔरAuthorizationहेडर: वैल्यू का ऐसा कॉम्बिनेशन जिससे यह पता चलता है कि किस उपयोगकर्ता के पास खाताBका ऐक्सेस है.
रिस्पॉन्स हेडर
जवाब के मुख्य हिस्से के साथ, यहां दिए गए हेडर (या grpc trailing-metadata) दिखाए जाते हैं. हमारा सुझाव है कि आप इन वैल्यू को डीबग करने के लिए लॉग करें.
request-id
request-id एक स्ट्रिंग है, जो इस अनुरोध की खास तौर पर पहचान करती है.