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

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 CLI या 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() को कॉल करें. ऐप्लिकेशन के लिए डिफ़ॉल्ट क्रेडेंशियल का इस्तेमाल करते समय, क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन सेट नहीं किया जाना चाहिए.