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

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

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

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

सुझाया गया:

1. अनुरोध के मुख्य हिस्से को प्रोटोकॉल बफ़र के तौर पर बनाएं.
2. इसे एचटीटीपी/2 का इस्तेमाल करके सर्वर पर भेजें.
3. प्रोटोकॉल बफ़र में जवाब को डिसिरियलाइज़ करता है.
4. परिणामों की व्याख्या करें.

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

ज़रूरी नहीं:

1. अनुरोध के मुख्य हिस्से को JSON ऑब्जेक्ट के तौर पर बनाएं.
2. इसे एचटीटीपी 1.1 का इस्तेमाल करके सर्वर पर भेजें.
3. रिस्पॉन्स को JSON ऑब्जेक्ट के तौर पर डीसीरियलाइज़ करें.
4. परिणामों की व्याख्या करें.

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

संसाधन के आइडेंटिफ़ायर

Google Ads API में ऑब्जेक्ट को स्ट्रक्चर्ड रिसॉर्स के नामों और कंपोज़िट आइडेंटिफ़ायर का इस्तेमाल करके ऐक्सेस किया जाता है.

संसाधन के नाम

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

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

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

उदाहरण के लिए, AdGroupAd का संसाधन नाम पैटर्न customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id} है. इसके कंपोज़िट आइडेंटिफ़ायर में पैरंट विज्ञापन ग्रुप आईडी (ad_group.id) और विज्ञापन आईडी (ad_group_ad.ad.id) शामिल होता है. इसलिए, हम विज्ञापन आईडी से पहले विज्ञापन ग्रुप आईडी जोड़ते हैं:

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

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

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

अनुमति देना

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

अगर आपको अनुमति से जुड़ी गड़बड़ियां दिखती हैं, तो पक्का करें कि आपने सही क्रेडेंशियल का इस्तेमाल किया हो और आपके पास ज़रूरी अनुमतियां हों. USER_PERMISSION_DENIED गड़बड़ी से पता चलता है कि पुष्टि किए गए उपयोगकर्ता के पास, अनुरोध में बताए गए ग्राहक खाते का ऐक्सेस नहीं है. अगर आपके Google Cloud प्रोजेक्ट को सिर्फ़ Test ऐक्सेस करने की अनुमति मिली है और आपने प्रोडक्शन खाते को टारगेट करने का अनुरोध भेजा है, तो एपीआई, v25 और उसके बाद के वर्शन में AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION या v24 और उससे पहले के वर्शन में AuthorizationError.ACTION_NOT_PERMITTED दिखाता है. अनुमतियां मैनेज करने के बारे में जानकारी पाने के लिए, Google Ads के ऐक्सेस लेवल लेख पढ़ें.

login-customer-id

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

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

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

linked-customer-id

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

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

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

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

अनुरोध के हेडर इस तरह से सेट किए जाने चाहिए:

• Authorization: यह उस उपयोगकर्ता के लिए OAuth 2.0 ऐक्सेस टोकन है जिसके पास Partner का ऐक्सेस है.
• login-customer-id: यह पार्टनर खाते का ग्राहक आईडी होता है. पुष्टि किए गए उपयोगकर्ता के पास इस खाते का ऐक्सेस होना चाहिए.
• linked-customer-id: यह लिंक किए गए खाते का ग्राहक आईडी होता है. इस हेडर से पता चलता है कि इस अनुरोध के लिए अनुमति, पार्टनर के साथ लिंक किए गए खाते के प्रॉडक्ट लिंक पर निर्भर करती है.

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

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

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

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

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

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

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

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

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

request-id

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