Google Ads API का सेटअप करने से जुड़ी गाइड

इस गाइड में, Google Ads API में शामिल होने, पुष्टि करने, और पहला कॉल करने की पूरी प्रोसेस के बारे में बताया गया है.

1. ज़रूरी शर्तें और खाते की हैरारकी

Google Ads API के साथ इंटरैक्ट करने से पहले, आपको खाते की हैरारकी के बारे में समझना होगा. साथ ही, आपके पास टॉप-लेवल खाते का सही स्ट्रक्चर होना चाहिए.

  • मैनेजर खाता (एमसीसी): Google Ads मैनेजर खाता (इसे पहले मेरा ग्राहक केंद्र कहा जाता था) एक प्राइमरी खाता होता है. इसका इस्तेमाल, एक से ज़्यादा क्लाइंट खातों को देखने और मैनेज करने के लिए किया जाता है. Google Ads API डेवलपर टोकन के लिए आवेदन करने के लिए, आपके पास एक मैनेजर खाता होना चाहिए.
  • क्लाइंट खाता: यह एक स्टैंडर्ड खाता होता है, जिसमें कैंपेन, विज्ञापन ग्रुप, और विज्ञापन बनाए जाते हैं. साथ ही, बिलिंग को कॉन्फ़िगर किया जाता है.

कार्रवाई का आइटम: अगर आपके पास मैनेजर खाता नहीं है, तो Google Ads मैनेजर खातों पर जाकर एक खाता बनाएं.

2. डेवलपर टोकन पाना

डेवलपर टोकन, Google Ads API के लिए आपके ऐप्लिकेशन की यूनीक पहचान करता है. साथ ही, यह कॉल वॉल्यूम ऐक्सेस टियर को कंट्रोल करता है.

प्रोसेस चल रही है

  1. अपने Google Ads मैनेजर खाते में साइन इन करें.
  2. टूल और सेटिंग > सेट अप > एपीआई सेंटर (या एडमिन > एपीआई सेंटर) पर जाएं.
  3. डेवलपर की जानकारी वाला फ़ॉर्म भरें और एपीआई की सेवा की शर्तों से सहमत हों.
  4. अपना आवेदन सबमिट करें.

ऐक्सेस लेवल

  • मंज़ूरी बाकी है: नए टोकन को तुरंत "मंज़ूरी बाकी है" स्टेटस मिलता है. मंज़ूरी बाकी वाले टोकन का इस्तेमाल, टेस्ट खातों से तुरंत कनेक्ट करने के लिए किया जा सकता है. हालांकि, यह प्रोडक्शन खातों के लिए काम नहीं करेगा.
  • बुनियादी ऐक्सेस: मंज़ूरी मिलने के बाद, हर दिन 15,000 एपीआई ऑपरेशन किए जा सकते हैं.
  • स्टैंडर्ड ऐक्सेस: ज़रूरी तौर पर मुहैया कराई जाने वाली सुविधाएं (आरएमएफ़) की ज़रूरी शर्तों को पूरा करने वाले ऐप्लिकेशन के लिए, हर दिन एपीआई के असीमित ऑपरेशन किए जा सकते हैं.

3. टेस्ट खाते सेट अप करना

प्रोडक्शन खातों के लिए डेवलपमेंट और टेस्टिंग करने से, विज्ञापन पर अनचाहा खर्च हो सकता है और कैंपेन में बदलाव हो सकते हैं. हमारा सुझाव है कि सभी ऐक्टिव डेवलपमेंट, टेस्ट खातों के लिए किए जाएं.

टेस्ट मैनेजर खाता बनाना

  1. Google Ads टेस्ट मैनेजर खाता बनाने के लिए पेज पर जाएं.
  2. ऐसे Google खाते से साइन इन करें जो आपके प्रोडक्शन Google Ads मैनेजर खाते से पहले से लिंक न हो.
  3. खाते का ऐसा नाम डालें जिससे उसकी पहचान हो सके. जैसे, MyCompany Test MCC.
  4. प्राइमरी इस्तेमाल के तौर पर, दूसरे लोगों के खाते मैनेज करें को चुनें.
  5. बिलिंग देश, टाइम ज़ोन, और करंसी चुनें. सेव करें और जारी रखें पर क्लिक करें.

टेस्ट क्लाइंट खाता बनाना

टेस्ट मैनेजर खाता बन जाने के बाद, टेस्ट कैंपेन चलाने के लिए कम से कम एक चाइल्ड क्लाइंट खाता बनाना ज़रूरी है.

  1. नए बनाए गए टेस्ट मैनेजर खाते में साइन इन करें.
  2. बाईं ओर मौजूद नेविगेशन मेन्यू में, खाते पर क्लिक करें. इसके बाद, उप-खाता सेटिंग (या परफ़ॉर्मेंस) को चुनें.
  3. नीले रंग के + (प्लस) बटन पर क्लिक करें और नया खाता बनाएं को चुनें.
  4. Google Ads खाता चुनें.
  5. खाते का नाम डालें. जैसे, Test Client Account A.
  6. कोई टाइम ज़ोन और करंसी चुनें. इसके बाद, सेव करें और जारी रखें पर क्लिक करें.
  7. इस नए क्लाइंट खाते का 10 अंकों वाला ग्राहक आईडी नोट करें. जैसे, 1234567890 (बिना हाइफ़न के).

टेस्ट खातों के लिए ज़रूरी नियम

  • डेवलपर टोकन का इस्तेमाल: अपने टेस्ट मैनेजर खाते से, डेवलपर टोकन के लिए आवेदन न करें. हमेशा अपने प्रोडक्शन मैनेजर खाते से, मंज़ूरी बाकी वाले या मंज़ूरी मिल चुके डेवलपर टोकन का इस्तेमाल करें.
  • बिलिंग: टेस्ट खातों से असली विज्ञापन नहीं दिखाए जाते. इसलिए, आपको असली बिलिंग की जानकारी डालने की ज़रूरत नहीं है.

4. Google Cloud प्रोजेक्ट सेट अप करना

एपीआई के सभी अनुरोधों की पुष्टि, Google Ads API की सुविधा चालू किए गए Google Cloud प्रोजेक्ट का इस्तेमाल करके की जानी चाहिए.

एपीआई चालू करने के तरीके

  1. Google Cloud Console पर जाएं.
  2. कोई नया प्रोजेक्ट बनाएं या कोई मौजूदा प्रोजेक्ट चुनें.
  3. एपीआई और सेवाएं > लाइब्रेरी पर जाएं.
  4. Google Ads API खोजें और चालू करें पर क्लिक करें.

कीमत तय करना और बिलिंग

  • एपीआई के लिए कोई शुल्क नहीं: Google Cloud प्रोजेक्ट बनाना, Google Ads API को चालू करना, और OAuth 2.0 क्रेडेंशियल जनरेट करना पूरी तरह से मुफ़्त है. Google, Google Ads API को कॉल करने या उसका इस्तेमाल करने के लिए कोई शुल्क नहीं लेता.
  • क्लाउड के अन्य संसाधन: Google Cloud का शुल्क सिर्फ़ तब लगेगा, जब अपने ऐप्लिकेशन को होस्ट करने या विज्ञापन का डेटा सेव करने के लिए, Google Cloud की बिलिंग वाली अन्य सेवाओं (जैसे, Compute Engine, Cloud Run या BigQuery) का इस्तेमाल, उनके फ़्री टियर की सीमाओं से ज़्यादा किया जाएगा.

5. OAuth 2.0 से पुष्टि करने के लिए कॉन्फ़िगरेशन

Google Ads API, अनुरोधों की पुष्टि करने और उन्हें अनुमति देने के लिए OAuth 2.0 का इस्तेमाल करता है.

डेस्कटॉप ऐप्लिकेशन फ़्लो के लिए चरण

  1. अपने Google Cloud प्रोजेक्ट में, एपीआई और सेवाएं > OAuth के लिए सहमति देने की स्क्रीन पर जाएं और सहमति देने की स्क्रीन को कॉन्फ़िगर करें. ऐप्लिकेशन के टेस्टिंग स्टेटस में होने के दौरान, टेस्ट उपयोगकर्ता सेक्शन में अपना ईमेल पता जोड़ें. इससे, अनुमति देने के दौरान ऐक्सेस से जुड़ी गड़बड़ियां नहीं होंगी.
  2. एपीआई और सेवाएं > क्रेडेंशियल पर जाएं.
  3. क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी पर क्लिक करें.
  4. ऐप्लिकेशन के टाइप के तौर पर, डेस्कटॉप ऐप्लिकेशन को चुनें.
  5. बनाएं पर क्लिक करें. इसके बाद, OAuth क्रेडेंशियल वाली फ़ाइल को client_secret.json के तौर पर डाउनलोड करें. इसके अलावा, अपना Client ID और Client Secret कॉपी करें.

रीफ़्रेश टोकन जनरेट करना

क्लाइंट आईडी और क्लाइंट सीक्रेट मिलने के बाद, आपको रीफ़्रेश टोकन जनरेट करना होगा. इसके लिए, Google OAuth 2.0 Playground या क्लाइंट लाइब्रेरी स्क्रिप्ट का इस्तेमाल किया जा सकता है.

पहला तरीका: Google OAuth 2.0 Playground का इस्तेमाल करना

  1. Google OAuth 2.0 Playground पर जाएं.
  2. सबसे ऊपर दाएं कोने में मौजूद, गियर आइकॉन (OAuth 2.0 कॉन्फ़िगरेशन) पर क्लिक करें.
  3. अपने OAuth क्रेडेंशियल का इस्तेमाल करें वाले बॉक्स पर सही का निशान लगाएं.
  4. अपना OAuth2 Client ID और Client Secret डालें. इसके बाद, बंद करें पर क्लिक करें.
  5. बाईं ओर मौजूद पहला चरण (एपीआई चुनें और उन्हें अनुमति दें) में, "अपने दायरे डालें" फ़ील्ड में Google Ads API का दायरा डालें: https://www.googleapis.com/auth/adwords
  6. एपीआई को अनुमति दें पर क्लिक करें. जब आपसे कहा जाए, तब उस Google खाते से साइन इन करें जिसके पास आपके Google Ads मैनेजर खाते (या टेस्ट खाते) का ऐक्सेस हो.
  7. सहमति देने की स्क्रीन पर, जारी रखें पर क्लिक करें.
  8. दूसरा चरण (टोकन के लिए ऑथराइज़ेशन कोड बदलें) में, नीले रंग के टोकन के लिए ऑथराइज़ेशन कोड बदलें बटन पर क्लिक करें.
  9. जवाब वाले पैनल में, आपका Refresh token और Access token दिखेगा. Refresh token को कॉपी करके सेव करें.

दूसरा तरीका: क्लाइंट लाइब्रेरी स्क्रिप्ट का इस्तेमाल करना (Python का उदाहरण)

आधिकारिक Python क्लाइंट लाइब्रेरी में, क्रेडेंशियल जनरेट करने के लिए एक बिल्ट-इन हेल्पर स्क्रिप्ट होती है. इसके अलावा, Google Cloud Console से अपना client_secret.json डाउनलोड किया जा सकता है और Python की इस स्टैंडअलोन स्क्रिप्ट को चलाया जा सकता है:

  1. OAuth की ज़रूरी लाइब्रेरी इंस्टॉल करें:
pip install google-auth-oauthlib
  1. client_secret.json वाली डायरेक्ट्री में, generate_refresh_token.py नाम की स्क्रिप्ट बनाएं और उसे रन करें:
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. क्लाइंट लाइब्रेरी और क्रेडेंशियल सेट अप करना

Google, आधिकारिक तौर पर इस्तेमाल की जा सकने वाली क्लाइंट लाइब्रेरी उपलब्ध कराता है. ये लाइब्रेरी, gRPC एंडपॉइंट के साथ पुष्टि, क्रम से लगाना, और कम्यूनिकेशन को हैंडल करती हैं.

इस्तेमाल की जा सकने वाली भाषाएं

  • Python: pip install google-ads
  • Java: Maven या Gradle के ज़रिए उपलब्ध है
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads
  • Perl: cpanm Google::Ads::GoogleAds::Client

कॉन्फ़िगरेशन फ़ाइल (google-ads.yaml)

अपने क्रेडेंशियल वाली एक कॉन्फ़िगरेशन फ़ाइल बनाएं. डिफ़ॉल्ट रूप से, क्लाइंट लाइब्रेरी का इनिशियलाइज़ेशन तरीका (जैसे, GoogleAdsClient.load_from_storage()), google-ads.yaml को इन दो जगहों पर अपने-आप खोजेगा:

  1. मौजूदा वर्किंग डायरेक्ट्री, जहां से आपकी स्क्रिप्ट चलाई जाती है.
  2. आपका उपयोगकर्ता होम डायरेक्ट्री (Linux/macOS पर ~ या Windows पर %HOMEPATH%).

अगर फ़ाइल को किसी कस्टम जगह पर सेव किया जाता है, तो इनिशियलाइज़ेशन तरीके में पाथ को साफ़ तौर पर पास किया जा सकता है. जैसे, load_from_storage("path/to/google-ads.yaml").

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. अपना पहला एपीआई कॉल करें

ऑनबोर्डिंग सेटअप की पुष्टि करने के लिए, अपने टेस्ट खाते से मौजूदा कैंपेन फ़ेच करने के लिए, क्विकस्टार्ट स्क्रिप्ट चलाएं.

Python स्क्रिप्ट का उदाहरण (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. सबसे सही तरीके और संसाधन

  • लॉगिंग: अपनी क्लाइंट लाइब्रेरी में, विस्तृत लॉगिंग की सुविधा चालू करें. इससे, अनुरोध और जवाब के आईडी (request-id) कैप्चर किए जा सकेंगे. Google से सहायता का अनुरोध करते समय, ये आईडी ज़रूरी होते हैं.
  • गड़बड़ी ठीक करना: GoogleAdsException के लिए, गड़बड़ी ठीक करने की मज़बूत सुविधा लागू करें. खास तौर पर, रेट लिमिट (RESOURCE_TEMPORARILY_EXHAUSTED) को मैनेज करें.
  • आधिकारिक दस्तावेज़: Google Ads API के डेवलपर के लिए दस्तावेज़
  • क्लाइंट लाइब्रेरी और कोड के उदाहरण: GitHub पर Google Ads के डेटाबेस
पीछे जाएं
शुरुआती जानकारी
आगे बढ़ें
क्विकस्टार्ट