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

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

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

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) को जोड़ता है. इसलिए, हम विज्ञापन आईडी से पहले विज्ञापन ग्रुप आईडी जोड़ते हैं:

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

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

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

अनुमति देना

आपको Authorization: Bearer YOUR_ACCESS_TOKEN के तौर पर OAuth 2.0 ऐक्सेस टोकन शामिल करना होगा. इससे, क्लाइंट की ओर से काम करने वाले मैनेजर खाते या सीधे तौर पर अपना खाता मैनेज करने वाले विज्ञापन देने वाले व्यक्ति या कंपनी की पहचान की जाती है. ऐक्सेस टोकन पाने के निर्देश, 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/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 trailing-metadata) दिखाए जाते हैं. हमारा सुझाव है कि आप डीबग करने के लिए, इन वैल्यू को लॉग करें.

request-id

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

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