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