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

इस गाइड में, सभी एपीआई कॉल के सामान्य स्ट्रक्चर के बारे में बताया गया है.

अगर एपीआई के साथ इंटरैक्ट करने के लिए क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है, तो आपको अनुरोध की बुनियादी जानकारी के बारे में चिंता करने की ज़रूरत नहीं है. हालांकि, जांच और डीबग करते समय, इनके बारे में थोड़ी-बहुत जानकारी हासिल करना फ़ायदेमंद हो सकता है.

Google Ads API, REST बाइंडिंग वाला gRPC API है. इसका मतलब है कि एपीआई को कॉल करने के दो तरीके हैं.

1. [Preferred] अनुरोध के मुख्य हिस्से को प्रोटोकॉल बफ़र के तौर पर बनाएं, HTTP/2 का इस्तेमाल करके सर्वर को भेजें, प्रोटोकॉल बफ़र में रिस्पॉन्स को डीसीरियलाइज़ करें, और नतीजों को समझें. हमारे ज़्यादातर दस्तावेज़ों में gRPC के इस्तेमाल के बारे में बताया गया है.

2. [ज़रूरी नहीं] अनुरोध के मुख्य हिस्से को JSON ऑब्जेक्ट के तौर पर बनाएं, इसे एचटीटीपी 1.1 का इस्तेमाल करके सर्वर पर भेजें. इसके बाद, रिस्पॉन्स को JSON ऑब्जेक्ट के तौर पर डीसीरियलाइज़ करें, और नतीजों को समझें. REST का इस्तेमाल करने के बारे में ज़्यादा जानकारी के लिए, REST इंटरफ़ेस गाइड देखें.

ध्यान दें: इस गाइड में स्ट्रक्चर और ट्रांसपोर्ट हेडर के बारे में बताया गया है. ये हेडर, gRPC और REST, दोनों प्रोटोकॉल के लिए सामान्य हैं.

संसाधनों के नाम

एपीआई में मौजूद ज़्यादातर ऑब्जेक्ट की पहचान, संसाधन के नाम वाली स्ट्रिंग से की जाती है. ये स्ट्रिंग, REST इंटरफ़ेस का इस्तेमाल करते समय यूआरएल के तौर पर भी काम करती हैं. REST इंटरफ़ेस के संसाधन के नाम देखें.

अहम जानकारी: इस्तेमाल किए जा सकने वाले सभी संसाधनों और उनके पाथ को दिखाने (resource_name) के बारे में जानने के लिए, संसाधनों के दस्तावेज़ देखें. इस फ़ॉर्मैट का इस्तेमाल दूसरी सेवाओं के लिए भी किया जाता है.

कंपोज़िट आईडी

अगर किसी ऑब्जेक्ट का आईडी ग्लोबल लेवल पर यूनीक नहीं है, तो उस ऑब्जेक्ट के लिए एक कंपोज़िट आईडी, उसके पैरंट आईडी और टिल्ड (~) से पहले बनाया जाता है.

उदाहरण के लिए, एक विज्ञापन ग्रुप का विज्ञापन आईडी दुनिया भर में यूनीक नहीं होता, इसलिए हम एक यूनीक कंपोज़िट आईडी बनाने के लिए, उसके पैरंट ऑब्जेक्ट (विज्ञापन ग्रुप) आईडी से शुरुआत करते हैं:

• 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

यह अनुरोध में इस्तेमाल करने के लिए, हाइफ़न (-) के बिना, उस आधिकारिक ग्राहक का ग्राहक आईडी है. अगर ग्राहक खाते का ऐक्सेस, मैनेजर खाते के ज़रिए दिया गया है, तो यह हेडर ज़रूरी है. साथ ही, इसे मैनेजर खाते के ग्राहक आईडी पर सेट किया जाना चाहिए.

मुख्य अवधि: ऑपरेटिंग ग्राहक, अनुरोध के पेलोड में मौजूद ग्राहक आईडी होता है. उदाहरण के लिए, इस CampaignBudgetService अनुरोध में ऑपरेटिंग ग्राहक का नाम 1234567890 है:

https://googleads.googleapis.com/v17/customers/1234567890/campaignBudgets:mutate

login-customer-id को सेट करना, साइन इन करने के बाद Google Ads यूज़र इंटरफ़ेस (यूआई) में कोई खाता चुनने के बराबर है या सबसे ऊपर दाईं ओर मौजूद अपनी प्रोफ़ाइल इमेज पर क्लिक करें. अगर इस हेडर को शामिल नहीं किया जाता है, तो यह डिफ़ॉल्ट रूप से ऑपरेटिंग ग्राहक को दिखता है.

ध्यान दें: उन खातों की सूची को वापस लाया जा सकता है जिन्हें आपके OAuth क्रेडेंशियल से सीधे ऐक्सेस किया जा सकता है. इसके लिए, आपको CustomerService.ListAccessibleCustomers अनुरोध करना होगा. इस तरह के अनुरोध के लिए, login-customer-id की ज़रूरत नहीं होती. साथ ही, लौटाए गए ग्राहकों की सूची पर इसका कोई असर नहीं पड़ता.

लिंक किया गया ग्राहक आईडी

इस हेडर का इस्तेमाल सिर्फ़ तीसरे पक्ष के ऐप्लिकेशन ऐनलिटिक्स प्रोवाइडर से तब किया जाता है, जब लिंक किए गए 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 Trail-metadata) जवाब के मुख्य हिस्से के साथ दिखाए जाते हैं. हमारा सुझाव है कि आप डीबग करने के लिए, इन वैल्यू को लॉग करें.

request-id

request-id एक ऐसी स्ट्रिंग है जिससे इस अनुरोध की खास तौर पर पहचान की जाती है.