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

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

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

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

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

  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 मेटाडेटा) हैं, जो अनुरोध के मुख्य हिस्से के साथ शामिल होते हैं:

अनुमति देना

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

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

login-customer-id

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

है: 
https://googleads.googleapis.com/v26/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 का वह ऐक्सेस टोकन जो पार्टनर का ऐक्सेस रखने वाले किसी उपयोगकर्ता के लिए है.
  • 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 एक स्ट्रिंग है, जो इस अनुरोध की यूनीक पहचान करती है. एपीआई के काम न करने वाले या अनचाहे अनुरोधों से जुड़ी समस्याओं को हल करने के लिए, सहायता टीम से संपर्क करते समय यह वैल्यू दें.

पीछे जाएं
संसाधन मेटाडेटा