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

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

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

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

1. [प्राथमिकता दी जाती है] अनुरोध के मुख्य हिस्से को प्रोटोकॉल बफ़र के तौर पर बनाएं और एचटीटीपी/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 गाइड में देखे जा सकते हैं. ऐक्सेस टोकन मिलने के बाद, वह एक घंटे तक मान्य होता है. इसकी समयसीमा खत्म होने पर, नया ऐक्सेस टोकन पाने के लिए उसे रीफ़्रेश करें. ध्यान दें कि हमारी क्लाइंट लाइब्रेरी, समयसीमा खत्म हो चुके टोकन को अपने-आप रीफ़्रेश कर देती हैं.

developer-token

डेवलपर टोकन, 22 वर्णों की एक स्ट्रिंग होती है. इससे Google Ads API डेवलपर की पहचान की जाती है. डेवलपर टोकन स्ट्रिंग का उदाहरण ABcdeFGH93KL-NOPQ_STUv है. डेवलपर टोकन को developer-token : ABcdeFGH93KL-NOPQ_STUv के तौर पर शामिल किया जाना चाहिए.

login-customer-id

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

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

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

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

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

linked-customer-id

इस हेडर का इस्तेमाल सिर्फ़ तीसरे पक्ष के ऐप्लिकेशन ऐनलिटिक्स प्रोवाइडर, लिंक किए गए Google Ads खाते में कन्वर्ज़न अपलोड करते समय करते हैं.

मान लें कि खाते A के उपयोगकर्ता, ThirdPartyAppAnalyticsLink की मदद से, खाते B को अपनी इकाइयों को पढ़ने और उनमें बदलाव करने का ऐक्सेस देते हैं. लिंक होने के बाद, खाता B का उपयोगकर्ता, खाता A के लिए API कॉल कर सकता है. हालांकि, ऐसा लिंक से मिली अनुमतियों के हिसाब से ही किया जा सकता है. इस मामले में, खाते A के लिए एपीआई कॉल करने की अनुमतियां, मैनेजर खाते के संबंध के बजाय, खाते B के तीसरे पक्ष के लिंक से तय होती हैं. मैनेजर खाते के संबंध का इस्तेमाल, अन्य एपीआई कॉल में किया जाता है.

तीसरे पक्ष की ऐप्लिकेशन एनालिटिक्स सेवा देने वाली कंपनी, एपीआई कॉल इस तरह करती है:

• linked-customer-id: तीसरे पक्ष का वह ऐप्लिकेशन आंकड़े वाला खाता जो डेटा अपलोड करता है (खाता B).
• customer-id: वह Google Ads खाता जिसमें डेटा अपलोड किया गया है (खाता A).
• login-customer-id और Authorization हेडर: ऐसे उपयोगकर्ता की पहचान करने के लिए वैल्यू का कॉम्बिनेशन जिसके पास खाता B का ऐक्सेस है.

रिस्पॉन्स हेडर

रिस्पॉन्स बॉडी के साथ ये हेडर (या grpc trailing-metadata) दिखाए जाते हैं. हमारा सुझाव है कि डीबग करने के लिए, इन वैल्यू को लॉग करें.

request-id

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