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

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

Google Ads के ऐक्सेस मॉडल को समझना

Google Ads API का असरदार तरीके से इस्तेमाल करने के लिए, Google Ads के ऐक्सेस मॉडल के काम करने का तरीका समझें. Google Ads ऐक्सेस मॉडल गाइड देखें.

OAuth वर्कफ़्लो

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

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

अगर आपके वर्कफ़्लो में किसी व्यक्ति के इंटरैक्शन की ज़रूरत नहीं है, तो हमारा सुझाव है कि आप यह वर्कफ़्लो अपनाएं. इस वर्कफ़्लो के लिए, कॉन्फ़िगरेशन का एक चरण ज़रूरी है. इसमें उपयोगकर्ता को अपने Google Ads खाते में एक सेवा खाता जोड़ना होता है. इसके बाद, ऐप्लिकेशन उपयोगकर्ता के Google Ads खाते को मैनेज करने के लिए, सेवा खाते के क्रेडेंशियल का इस्तेमाल कर सकता है. इसे कॉन्फ़िगर करने के लिए, Google Cloud Console में JSON कुंजी फ़ाइल बनाएं और डाउनलोड करें. इसके बाद, google_ads_config.rb को अपनी होम डायरेक्ट्री में कॉपी करें और उसमें बदलाव करके, अपने सेवा खाते की कुंजी वाली फ़ाइल की जगह की जानकारी दें. साथ ही, Google Workspace के डोमेन-वाइड डेलिगेशन का इस्तेमाल करते समय, उपयोगकर्ता के तौर पर काम करने के लिए, उसका ईमेल पता भी दें. हालांकि, ईमेल पता देना ज़रूरी नहीं है:

# You can also authenticate using a service account. If "keyfile" is
# specified below, then service account authentication will be assumed and
# the above authentication fields ignored. Read more about service account
# authentication here:
# https://developers.google.com/google-ads/api/docs/oauth/service-accounts
c.keyfile = 'path/to/keyfile.json'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

अगर आपको यह जानकारी किसी फ़ाइल में सेव नहीं करनी है और इसके बजाय एनवायरमेंट वैरिएबल का इस्तेमाल करना है, तो GOOGLE_ADS_JSON_KEY_FILE_PATH (और वैकल्पिक GOOGLE_ADS_IMPERSONATED_EMAIL) सेट किया जा सकता है:

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

रनटाइम के दौरान, प्रोग्राम के हिसाब से सेवा खाते की कुंजी वाली फ़ाइल का पाथ (और वैकल्पिक तौर पर, किसी दूसरे व्यक्ति के नाम पर बनाया गया ईमेल पता) भी पास किया जा सकता है:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

इसके अलावा, सेवा खाते के क्रेडेंशियल बनाने के लिए, googleauth जेम का इस्तेमाल किया जा सकता है. साथ ही, credentials.updater_proc को config.authentication में पास किया जा सकता है:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file.
key_file = '/path/to/your/service-account-key.json'

# Define the scopes needed for the Google Ads API.
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials.
credentials = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

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

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

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

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

OAuth 2.0 क्रेडेंशियल को Ruby के लिए कॉन्फ़िगर किया जा सकता है. इसके लिए, google_ads_config.rb फ़ाइल को अपनी होम डायरेक्ट्री में कॉपी करें. इसके बाद, उसमें बदलाव करके अपना क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन शामिल करें:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

अगर क्लाइंट को बिना किसी आर्ग्युमेंट के इंस्टैंशिएट किया जाता है, तो वह होम डायरेक्ट्री से कॉन्फ़िगरेशन फ़ाइल को अपने-आप पढ़ लेता है:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

इसके अलावा, अगर आपको फ़ाइल कहीं और सेव करनी है, तो क्लाइंट को इंस्टैंशिएट किया जा सकता है. इसके लिए, आपको उस पाथ को पास करना होगा जहां यह फ़ाइल सेव की गई है:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

अगर आपको इस जानकारी को किसी फ़ाइल में सेव नहीं करना है और इसके बजाय एनवायरमेंट वैरिएबल का इस्तेमाल करना है, तो इनमें से हर एक को सेट किया जा सकता है:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

रनटाइम के दौरान, प्रोग्राम के हिसाब से भी जानकारी पास की जा सकती है:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

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

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

अगर आपका ऐप्लिकेशन उपयोगकर्ताओं को साइन इन करने और उनकी ओर से उनके Google Ads खातों को मैनेज करने की अनुमति देता है, तो हमारा सुझाव है कि आप इस वर्कफ़्लो का इस्तेमाल करें. आपका ऐप्लिकेशन, OAuth 2.0 उपयोगकर्ता क्रेडेंशियल बनाता और मैनेज करता है. इस वर्कफ़्लो को सिंगल-यूज़र फ़्लो की तरह ही कॉन्फ़िगर किया जा सकता है. साथ ही, इसमें login_customer_id की जानकारी भी दी जा सकती है.

हमारा सुझाव है कि आप कॉन्फ़िगरेशन फ़ाइल का इस्तेमाल करें. google_ads_config.rb फ़ाइल को अपनी होम डायरेक्ट्री में कॉपी करें. इसके बाद, इसमें अपना क्लाइंट आईडी, क्लाइंट सीक्रेट, रीफ़्रेश टोकन, और ग्राहक आईडी शामिल करने के लिए, इसमें बदलाव करें:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. If you need to use different values for this field, then
# make sure to fetch a new copy of the service after each time you change the
# value.
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

अगर क्लाइंट को बिना किसी आर्ग्युमेंट के इंस्टैंशिएट किया जाता है, तो वह होम डायरेक्ट्री से कॉन्फ़िगरेशन फ़ाइल को अपने-आप पढ़ लेता है:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

इसके अलावा, अगर आपको फ़ाइल कहीं और सेव करनी है, तो क्लाइंट को इंस्टैंशिएट किया जा सकता है. इसके लिए, आपको उस पाथ को पास करना होगा जहां यह फ़ाइल सेव की गई है:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

अगर आपको इस जानकारी को किसी फ़ाइल में सेव नहीं करना है और इसके बजाय एनवायरमेंट वैरिएबल का इस्तेमाल करना है, तो इनमें से हर एक को सेट किया जा सकता है:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

रनटाइम के दौरान, प्रोग्राम के हिसाब से भी जानकारी पास की जा सकती है:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

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

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

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

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

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

Ruby क्लाइंट लाइब्रेरी (v36.1.0 और इसके बाद के वर्शन) में, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (एडीसी) की मदद से पुष्टि करने की सुविधा भी काम करती है. इसकी मदद से, अपने ऐप्लिकेशन के लिए डिफ़ॉल्ट क्रेडेंशियल सेट किए जा सकते हैं. इसके लिए, आपको अपने ऐप्लिकेशन के कॉन्फ़िगरेशन में OAuth 2.0 की जानकारी कॉन्फ़िगर करने की ज़रूरत नहीं पड़ती.

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

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

ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल इस्तेमाल करने के लिए, Google Cloud के कमांड-लाइन टूल का इस्तेमाल करें और एडीसी के लिए पुष्टि करें:

gcloud auth application-default login

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

google_ads_config.rb फ़ाइल को अपनी होम डायरेक्ट्री में कॉपी करें. इसके बाद, use_application_default_credentials को true पर सेट करें:

# You can also authenticate using Application Default Credentials (ADC).
# To understand how ADC discovers credentials in a given environment, see:
# https://developers.google.com/identity/protocols/application-default-credentials
c.use_application_default_credentials = true

अगर आपको यह जानकारी किसी फ़ाइल में सेव नहीं करनी है और इसके बजाय एनवायरमेंट वैरिएबल का इस्तेमाल करना है, तो GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS को सेट किया जा सकता है:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

रनटाइम के दौरान, प्रोग्राम के हिसाब से भी जानकारी पास की जा सकती है. अपने Ruby कोड में क्लाइंट को शुरू करते समय, config.use_application_default_credentials = true सेट करें और साफ़ तौर पर OAuth 2.0 क्रेडेंशियल न दें. लाइब्रेरी, Google Cloud के कमांड-लाइन टूल से सेट अप किए गए क्रेडेंशियल का अपने-आप पता लगाती है और उनका इस्तेमाल करती है:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = 'YOUR_LOGIN_CUSTOMER_ID'

  # Do NOT include client_id, client_secret, or refresh_token here.
end

Ruby क्लाइंट लाइब्रेरी को कॉन्फ़िगर करने के लिए उपलब्ध विकल्पों के बारे में ज़्यादा जानने के लिए, कॉन्फ़िगरेशन पेज पर जाएं.