पुष्टि करना और अनुमति देना

Google के अन्य एपीआई की तरह, Google Ads API भी पुष्टि करने और अनुमति देने के लिए, OAuth 2.0 प्रोटोकॉल का इस्तेमाल करता है. OAuth 2.0 की मदद से, Google Ads API क्लाइंट ऐप्लिकेशन, उपयोगकर्ता की लॉगिन जानकारी को मैनेज या सेव किए बिना, उसके Google Ads खाते को ऐक्सेस कर सकता है.

इस गाइड में, Google Ads API की पुष्टि के लिए Java क्लाइंट लाइब्रेरी को कॉन्फ़िगर करने का तरीका बताया गया है. इसके लिए, OAuth 2.0 के तीन सबसे सामान्य फ़्लो का इस्तेमाल किया गया है. साथ ही, ज़रूरी क्रेडेंशियल के बारे में भी बताया गया है.

Google Ads API के ऐक्सेस मॉडल के बारे में ज़्यादा जानने के लिए, Google Ads के ऐक्सेस मॉडल की गाइड पढ़ें.

क्रेडेंशियल

Google Ads API को ऐक्सेस करने के लिए, OAuth 2.0 क्रेडेंशियल की ज़रूरत होती है. कुछ मामलों में, लॉगिन ग्राहक आईडी की भी ज़रूरत होती है.

OAuth 2.0 क्रेडेंशियल

Google Ads खातों का ऐक्सेस रखने वाले Google खाते के उपयोगकर्ताओं के तौर पर अनुमति देने के लिए, आपको OAuth 2.0 क्रेडेंशियल का सेट देना होगा. इस्तेमाल किए जा रहे OAuth 2.0 फ़्लो के आधार पर, ज़रूरी क्रेडेंशियल का टाइप अलग-अलग होता है.

लाइब्रेरी में तीन फ़्लो काम करते हैं:

  • सेवा खाते का फ़्लो
  • एक उपयोगकर्ता की पुष्टि करने का फ़्लो
  • डिवाइस के एक से ज़्यादा उपयोगकर्ताओं की पुष्टि करने का फ़्लो

Google Ads API के OAuth फ़्लो के बारे में जानकारी पाने के लिए, OAuth की खास जानकारी देखें. साथ ही, ज़रूरी क्रेडेंशियल पाने के लिए, अपनी ज़रूरत के हिसाब से सबसे सही फ़्लो के निर्देशों का पालन करें.

लॉगिन ग्राहक आईडी

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

क्लाइंट लाइब्रेरी में, लॉगिन ग्राहक आईडी को आपकी ads.properties फ़ाइल में api.googleads.loginCustomerId कुंजी से तय किया जाता है.

कॉन्फ़िगरेशन

क्लाइंट लाइब्रेरी को ads.properties फ़ाइल, एनवायरमेंट वैरिएबल या प्रोग्राम के हिसाब से कॉन्फ़िगर किया जा सकता है. इस गाइड में, ads.properties फ़ाइल का इस्तेमाल करने के बारे में बताया गया है. सभी विकल्पों के बारे में जानकारी पाने के लिए, कॉन्फ़िगरेशन गाइड देखें.

अगर ads.properties फ़ाइल का इस्तेमाल किया जा रहा है, तो उसे अपनी होम डायरेक्ट्री में रखें: ~/ads.properties.

OAuth वर्कफ़्लो

Google Ads API का इस्तेमाल करते समय, तीन सामान्य वर्कफ़्लो इस्तेमाल किए जाते हैं.

सेवा खाते का फ़्लो

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

निजी कुंजी वाली JSON फ़ाइल मिलने के बाद, अपनी ads.properties फ़ाइल में यह जानकारी जोड़ें:

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

एक उपयोगकर्ता की पुष्टि करने का फ़्लो

अगर सेवा खातों का इस्तेमाल नहीं किया जा सकता, तो इस वर्कफ़्लो का इस्तेमाल किया जा सकता है. इस वर्कफ़्लो को कॉन्फ़िगर करने के लिए, दो चरणों को पूरा करना ज़रूरी है:

  1. Google Ads API का इस्तेमाल करके, किसी एक उपयोगकर्ता को उन सभी खातों का ऐक्सेस दें जिन्हें मैनेज करना है. एक सामान्य तरीका यह है कि उपयोगकर्ता को Google Ads API मैनेजर खाते का ऐक्सेस दिया जाए और सभी टारगेट Google Ads खातों को उस मैनेजर खाते से लिंक किया जाए.
  2. उपयोगकर्ता, gcloud सीएलआई या GenerateUserCredentials कोड के उदाहरण जैसे कमांड-लाइन टूल का इस्तेमाल करता है, ताकि आपके ऐप्लिकेशन को उनकी ओर से उनके सभी Google Ads खातों को मैनेज करने की अनुमति मिल सके.

ये क्रेडेंशियल मिलने के बाद, अपनी ads.properties फ़ाइल में ये चीज़ें जोड़ें:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

ज़्यादा जानने के लिए, एक उपयोगकर्ता की पुष्टि करने वाले वर्कफ़्लो की गाइड देखें.

डिवाइस के एक से ज़्यादा उपयोगकर्ताओं की पुष्टि करने का फ़्लो

अगर आपका ऐप्लिकेशन उपयोगकर्ताओं को साइन इन करने और उनकी ओर से उनके Google Ads खातों को मैनेज करने की अनुमति देता है, तो हमारा सुझाव है कि आप इस वर्कफ़्लो का इस्तेमाल करें. GenerateUserCredentials कोड का उदाहरण, कमांड-लाइन टूल है. इससे पता चलता है कि रनटाइम के दौरान उपयोगकर्ता की पुष्टि कैसे की जाती है, ताकि उनकी ओर से उनके Google Ads खातों को मैनेज किया जा सके. इस कोड के उदाहरण का इस्तेमाल, रेफ़रंस के तौर पर किया जा सकता है. इससे ऐसे डेस्कटॉप या वेब ऐप्लिकेशन बनाए जा सकते हैं जिनमें उपयोगकर्ता की पुष्टि करना ज़रूरी होता है.

डिवाइस के एक से ज़्यादा उपयोगकर्ताओं वाले ऐप्लिकेशन के लिए, अपने ऐप्लिकेशन के OAuth 2.0 क्लाइंट आईडी और क्लाइंट सीक्रेट को ads.properties (या किसी अन्य कॉन्फ़िगरेशन स्टोर) में सेव करें. साथ ही, हर असली उपयोगकर्ता के रीफ़्रेश टोकन को अपने ऐप्लिकेशन डेटाबेस में सुरक्षित तरीके से सेव करें. इसके बाद, UserCredentials और GoogleAdsClient बनाते समय, रनटाइम के दौरान इसे प्रोग्राम के हिसाब से पास करें:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

ज़्यादा जानने के लिए, डिवाइस के एक से ज़्यादा उपयोगकर्ताओं की पुष्टि करने के वर्कफ़्लो की गाइड देखें.

एक से ज़्यादा खाते प्रबंधित करना

आम तौर पर, कोई उपयोगकर्ता एक से ज़्यादा Google Ads खाते मैनेज करता है. इसके लिए, वह खातों को सीधे ऐक्सेस करता है या Google Ads मैनेजर खाते का इस्तेमाल करता है. Java क्लाइंट लाइब्रेरी में, यहां दिए गए कोड के उदाहरणों से पता चलता है कि ऐसे मामलों को कैसे मैनेज किया जाए:

  1. GetAccountHierarchy कोड के उदाहरण से पता चलता है कि Google Ads मैनेजर खाते में मौजूद सभी खातों की सूची को कैसे वापस लाया जाए.
  2. ListAccessibleCustomers कोड के उदाहरण से पता चलता है कि उन सभी खातों की सूची कैसे वापस पाई जा सकती है जिनका ऐक्सेस उपयोगकर्ता के पास सीधे तौर पर है. इसके बाद, इन खातों का इस्तेमाल loginCustomerId सेटिंग के लिए मान्य वैल्यू के तौर पर किया जा सकता है.

ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल

Java क्लाइंट लाइब्रेरी, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल से पुष्टि करने की सुविधा भी देती है.

यह सुविधा, स्थानीय डेवलपमेंट या अलग-अलग Google API के लिए डेवलपमेंट के लिए खास तौर पर मददगार है. इसकी वजह यह है कि एक ही क्रेडेंशियल का फिर से इस्तेमाल किया जा सकता है. हालांकि, इसके लिए ज़रूरी है कि वे ज़रूरी OAuth 2.0 स्कोप को ऐक्सेस कर सकें.

Google Ads API के लिए, पक्का करें कि आपके ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल, https://www.googleapis.com/auth/adwords OAuth 2.0 के दायरे को ऐक्सेस कर सकें.

ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल इस्तेमाल करने के लिए, अपनी ads.properties फ़ाइल में api.googleads.useApplicationDefaultCredentials विकल्प को true पर सेट करें या GoogleAdsClient.newBuilder() पर .enableApplicationDefaultCredentials() को कॉल करें. ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल इस्तेमाल करते समय, क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन सेट नहीं किया जाना चाहिए.