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

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

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

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

सुझाया गया तरीका:

1. अनुरोध के मुख्य हिस्से को प्रोटोकॉल बफ़र के तौर पर बनाएं.

2. इसे एचटीटीपी/2 का इस्तेमाल करके, सर्वर को भेजें.

3. रिस्पॉन्स को प्रोटोकॉल बफ़र में डीसीरियलाइज़ करें.

4. परिणामों की व्याख्या करें.

हमारे ज़्यादातर दस्तावेज़ों में, gRPC का इस्तेमाल करने के बारे में बताया गया है.

ज़रूरी नहीं:

1. अनुरोध के मुख्य हिस्से को JSON ऑब्जेक्ट के तौर पर बनाएं.

2. इसे एचटीटीपी 1.1 का इस्तेमाल करके, सर्वर को भेजें.

3. रिस्पॉन्स को JSON ऑब्जेक्ट के तौर पर डीसीरियलाइज़ करें.

4. परिणामों की व्याख्या करें.

REST का इस्तेमाल करने के बारे में ज़्यादा जानकारी के लिए, REST इंटरफ़ेस की गाइड देखें.

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

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

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

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

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

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

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

• 123 का AdGroupId + ~ + 45678 का AdGroupAdId = 123~45678 का कंपोज़िट विज्ञापन ग्रुप विज्ञापन आईडी.

अनुरोध का हेडर

ये एचटीटीपी हेडर (या grpc मेटाडेटा) हैं, जो अनुरोध के मुख्य हिस्से के साथ भेजे जाते हैं:

अनुमति देना

आपको Authorization: Bearer YOUR_ACCESS_TOKEN के फ़ॉर्मैट में OAuth2 ऐक्सेस टोकन शामिल करना होगा. इससे यह पता चलता है कि क्लाइंट की ओर से कोई मैनेजर खाता काम कर रहा है या कोई विज्ञापन देने वाला व्यक्ति या कंपनी सीधे तौर पर अपना खाता मैनेज कर रही है. ऐक्सेस टोकन पाने के निर्देश, OAuth2 गाइड में दिए गए हैं. ऐक्सेस टोकन, इसे हासिल करने के एक घंटे बाद तक मान्य रहता है. इसकी समयसीमा खत्म होने पर, नया ऐक्सेस टोकन पाने के लिए, इसे रीफ़्रेश करें. ध्यान दें कि हमारी क्लाइंट लाइब्रेरी, समयसीमा खत्म हो चुके टोकन को अपने-आप रीफ़्रेश कर देती हैं.

अगर आपको अनुमति से जुड़ी गड़बड़ियां दिखती हैं, तो पक्का करें कि आपने सही क्रेडेंशियल का इस्तेमाल किया हो और आपके पास ज़रूरी अनुमतियां हों. USER_PERMISSION_DENIED गड़बड़ी से पता चलता है कि प्रमाणित उपयोगकर्ता के पास, अनुरोध में बताए गए ग्राहक खाते का ऐक्सेस नहीं हो सकता है. अनुमतियां मैनेज करने के बारे में ज़्यादा जानकारी के लिए, Google Ads के ऐक्सेस लेवल देखें.

डेवलपर-टोकन

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

लॉगिन-कस्टमर-आईडी

यह, अनुरोध में इस्तेमाल करने के लिए, अनुमति वाले ग्राहक का आईडी है. इसमें हाइफ़न (-) शामिल नहीं होते. अगर आपको ग्राहक खाते का ऐक्सेस, किसी मैनेजर खाते के ज़रिए मिला है, तो यह हेडर ज़रूरी है. इसे मैनेजर खाते के ग्राहक आईडी पर सेट करना होगा. अगर मैनेजर खाते के ज़रिए पुष्टि करते समय, login-customer-id शामिल नहीं किया जाता है, तो AuthorizationError.USER_PERMISSION_DENIED गड़बड़ी होती है. इस गड़बड़ी के टाइप के बारे में ज़्यादा जानकारी के लिए, सामान्य गड़बड़ियां देखें.

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

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

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

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

लिंक-कस्टमर-आईडी

यह हेडर ज़रूरी है. इसका इस्तेमाल पार्टनर (जैसे, तीसरे पक्ष के ऐप्लिकेशन के आंकड़ों की जानकारी देने वाले या डेटा पार्टनर) तब करते हैं, जब वे लिंक किए गए Google Ads खाते पर कार्रवाई करते हैं. इस हेडर में, उस Google Ads खाते का ग्राहक आईडी बताना ज़रूरी है जिसमें प्रॉडक्ट लिंकमौजूद है.

मान लें कि किसी पार्टनर को प्रॉडक्ट लिंक के आधार पर, Google Ads खाते में एपीआई कॉल करने की ज़रूरत है.

• विज्ञापन देने वाला व्यक्ति या कंपनी: वह Google Ads खाता जिसे एपीआई कॉल की मदद से मैनेज या अपडेट किया जा रहा है. अनुरोध में, विज्ञापन देने वाले व्यक्ति या कंपनी के खाते का आईडी बताया जाता है. REST में, यह customerId पाथ पैरामीटर होता है. उदाहरण के लिए, customers/1111111111/.... वहीं, gRPC में, यह अनुरोध में मौजूद customer_id फ़ील्ड होता है.
• पार्टनर: पार्टनर खाता. उदाहरण के लिए, तीसरे पक्ष के ऐप्लिकेशन के आंकड़ों की जानकारी देने वाला या डेटा पार्टनर.
• लिंक किया गया खाता: वह Google Ads खाता जिसमें पार्टनर के साथ प्रॉडक्ट लिंक मौजूद है. इससे पार्टनर को विज्ञापन देने वाले व्यक्ति या कंपनी के खाते का ऐक्सेस मिलता है.

पार्टनर के पास ऐक्सेस रखने वाला कोई उपयोगकर्ता, विज्ञापन देने वाले व्यक्ति या कंपनी की इकाइयों पर कार्रवाई करने के लिए, एपीआई कॉल करता है. उदाहरण के लिए, कन्वर्ज़न अपलोड करने या उपयोगकर्ता सूचियां मैनेज करने के लिए. लिंक किया गया खाता, विज्ञापन देने वाले व्यक्ति या कंपनी का खाता या उसका कोई मैनेजर खाता हो सकता है.

अनुरोध के हेडर को इस तरह सेट करना होगा:

• Authorization: उस उपयोगकर्ता के लिए OAuth2 टोकन जिसके पास पार्टनर का ऐक्सेस है.
• developer-token: एपीआई ऐप्लिकेशन के लिए डेवलपर टोकन. आम तौर पर, यह पार्टनर से जुड़ा होता है.
• login-customer-id: पार्टनर का ग्राहक आईडी. प्रमाणित उपयोगकर्ता के पास इस खाते का ऐक्सेस होना चाहिए.
• linked-customer-id: लिंक किए गए खाते का ग्राहक आईडी. इस हेडर से पता चलता है कि इस अनुरोध के लिए अनुमति, पार्टनर के साथ लिंक किए गए खाते के प्रॉडक्ट लिंक पर निर्भर करती है.

लिंक करने के दो तरीके हैं:

• अगर विज्ञापन देने वाले व्यक्ति या कंपनी का पार्टनर के साथ डायरेक्ट प्रॉडक्ट लिंक है, तो लिंक किया गया खाता, विज्ञापन देने वाले व्यक्ति या कंपनी का खाता होगा. साथ ही, linked-customer-id को विज्ञापन देने वाले व्यक्ति या कंपनी के ग्राहक आईडी पर सेट करना होगा.
• अगर विज्ञापन देने वाले व्यक्ति या कंपनी का खाता, किसी ऐसे मैनेजर खाते से मैनेज किया जाता है जिसका पार्टनर के साथ प्रॉडक्ट लिंक है, तो लिंक किया गया खाता, मैनेजर खाता होगा. साथ ही, linked-customer-id को मैनेजर के ग्राहक आईडी पर सेट करना होगा.

पहला उदाहरण: डायरेक्ट लिंक

अगर विज्ञापन देने वाले व्यक्ति या कंपनी 1111111111 का पार्टनर 2222222222 के साथ डायरेक्ट लिंक है और एपीआई कॉल, customers/1111111111/... को टारगेट कर रहा है:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

दूसरा उदाहरण: मैनेजर लिंक

अगर विज्ञापन देने वाले व्यक्ति या कंपनी 1111111111 का खाता, मैनेजर 3333333333 मैनेज करता है, मैनेजर 3333333333 का पार्टनर 2222222222 के साथ लिंक है, और एपीआई कॉल, customers/1111111111/... को टारगेट कर रहा है:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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

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

अनुरोध-आईडी

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