इस गाइड में, सभी एपीआई कॉल के सामान्य स्ट्रक्चर के बारे में बताया गया है.
अगर एपीआई के साथ इंटरैक्ट करने के लिए क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो आपको अनुरोध की बुनियादी जानकारी जानने की ज़रूरत नहीं होगी. हालांकि, टेस्टिंग और डीबग करने के दौरान, एपीआई कॉल के स्ट्रक्चर के बारे में कुछ जानकारी काम आ सकती है.
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 गाइड में दिए गए हैं. ऐक्सेस टोकन, हासिल करने के एक घंटे तक मान्य होता है. इसकी समयसीमा खत्म होने पर, नया ऐक्सेस टोकन पाने के लिए, ऐक्सेस टोकन को रीफ़्रेश करें. ध्यान दें कि हमारी क्लाइंट लाइब्रेरी, समयसीमा खत्म हो चुके टोकन को अपने-आप रीफ़्रेश करती हैं.
developer-token
डेवलपर टोकन, 22 वर्णों वाली एक स्ट्रिंग होती है. इससे Google Ads API डेवलपर की यूनीक पहचान होती है. डेवलपर टोकन स्ट्रिंग का एक उदाहरण ABcdeFGH93KL-NOPQ_STUv है. डेवलपर टोकन को developer-token : ABcdeFGH93KL-NOPQ_STUv के फ़ॉर्म में शामिल किया जाना चाहिए.
login-customer-id
यह उस ग्राहक का आईडी है जिसे अनुरोध में इस्तेमाल करने की अनुमति मिली है. इसमें हाइफ़न (-) नहीं होते. अगर आपको मैनेजर खाते के ज़रिए ग्राहक खाते का ऐक्सेस मिला है, तो यह हेडर ज़रूरी है. साथ ही, इसे मैनेजर खाते के ग्राहक आईडी पर सेट किया जाना चाहिए.
https://googleads.googleapis.com/v21/customers/1234567890/campaignBudgets:mutate
login-customer-id सेट करने का मतलब है कि आपने Google Ads के यूज़र इंटरफ़ेस (यूआई) में साइन इन करने के बाद कोई खाता चुना है. इसके अलावा, इसका मतलब यह भी हो सकता है कि आपने सबसे ऊपर दाईं ओर मौजूद अपनी प्रोफ़ाइल इमेज पर क्लिक किया है. अगर आपने इस हेडर को शामिल नहीं किया है, तो यह डिफ़ॉल्ट रूप से ऑपरेटिंग कस्टमर पर सेट हो जाता है.
linked-customer-id
इस हेडर का इस्तेमाल सिर्फ़ तीसरे पक्ष के ऐप्लिकेशन ऐनलिटिक्स प्रोवाइडर करते हैं. ऐसा तब होता है, जब वे लिंक किए गए Google Ads खाते में कन्वर्ज़न अपलोड करते हैं.
मान लें कि खाता A के उपयोगकर्ता, ThirdPartyAppAnalyticsLink के ज़रिए खाता B को अपनी इकाइयों का डेटा देखने और उनमें बदलाव करने का ऐक्सेस देते हैं.
खाता लिंक होने के बाद, B खाते का उपयोगकर्ता, A खाते के लिए एपीआई कॉल कर सकता है. हालांकि, ऐसा सिर्फ़ लिंक की गई अनुमतियों के तहत किया जा सकता है. इस मामले में, खाते A के लिए एपीआई कॉल करने की अनुमतियां, खाते 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 एक स्ट्रिंग है, जो इस अनुरोध की खास तौर पर पहचान करती है.