उदाहरण

इस गाइड में, क्लाइंट लाइब्रेरी का इस्तेमाल किए बिना, सीधे REST एंडपॉइंट को कॉल करने के उदाहरण दिए गए हैं.

कोड के ज़्यादा उदाहरण देखने के लिए, REST कोड के उदाहरणों वाला GitHub रिपॉज़िटरी देखें.

एपीआई के हर तरीके के लिए, अनुरोध और जवाब के कोड देखने के लिए, सेवा के खास एंडपॉइंट के रेफ़रंस दस्तावेज़ देखें.

उदाहरण के लिए, रेफ़रंस पेज पर GoogleAdsService.Search के लिए अनुरोध और जवाब के कोड दिखाए जाते हैं Search तरीके के लिए.

ज़रूरी शर्तें

यहां दिखाए गए सभी सैंपल, curl कमांड का इस्तेमाल करके, bash shell में कॉपी-एंड-पेस्ट किए जाने के लिए हैं.

आपके पास डेवलपर टोकन होना चाहिए. टेस्ट खाते का ऐक्सेस भी काम करेगा. साथ ही, आपके पास Google Ads का मैनेजर खाता होना चाहिए, जिसमें कम से कम एक क्लाइंट खाता हो.

एनवायरमेंट वैरिएबल

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

API_VERSION="25"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

अन्य ऐसे ऑब्जेक्ट के आईडी जो ज़रूरी नहीं हैं

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

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

इसके अलावा, Mutates - Creates के दो उदाहरण, नया बजट और कैंपेन बनाते हैं.

क्वेरी कुकबुक गाइड में, रिपोर्टिंग के कई सैंपल दिए गए हैं. ये सैंपल, Google Ads की डिफ़ॉल्ट स्क्रीन में से कुछ के लिए हैं. साथ ही, ये इस गाइड में इस्तेमाल किए गए एनवायरमेंट वैरिएबल के साथ काम करते हैं. हमारी इंटरैक्टिव क्वेरी बिल्डर टूल भी, इंटरैक्टिव तरीके से कस्टम क्वेरी बनाने के लिए एक बेहतरीन संसाधन है.

पेज में बांटकर दिखाना

search तरीके में, पेज में बांटकर दिखाने की सुविधा का इस्तेमाल किया जाता है. इसमें हर पेज पर 10,000 आइटम दिखाए जाते हैं. साथ ही, query के साथ page_token की जानकारी दी जाती है.

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
",
"page_token":"${PAGE_TOKEN}"
}'

GAQL

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

स्ट्रीमिंग

searchStream तरीके से, सभी नतीजे एक ही जवाब में स्ट्रीम किए जाते हैं. इसलिए, pageSize फ़ील्ड मौजूद नहीं है.

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

GAQL

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

Mutates

operations कलेक्शन में जानकारी डालकर, एक ही JSON अनुरोध के कोड में, कई बदलाव करने की कार्रवाइयां (create, update, या remove) भेजी जा सकती हैं.

Creates

इस उदाहरण में, एक ही अनुरोध में, कैंपेन के लिए शेयर किए गए दो बजट बनाए जाते हैं.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  },
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  }
]
}"

अगले उदाहरण में, मौजूदा कैंपेन बजट का BUDGET_ID इस्तेमाल किया गया है. इसे पिछले चरण के आउटपुट से कॉपी-एंड-पेस्ट किया जा सकता है.

BUDGET_ID=BUDGET_ID

जो संसाधन, दूसरे संसाधनों के बारे में बताते हैं वे संसाधन के नाम से ऐसा करते हैं resource name. यहां दिए गए उदाहरण में बनाया गया कैंपेन, स्ट्रिंग वैल्यू वाले संसाधन के नाम से campaignBudget के बारे में बताता है.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'status': 'PAUSED',
      'advertisingChannelType': 'SEARCH',
      'geoTargetTypeSetting': {
        'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
        'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
      },
      'name': 'My Search campaign #${RANDOM}',
      'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}',
      'targetSpend': {}
    }
  }
]
}"

Updates

update कार्रवाइयों का इस्तेमाल करके, मौजूदा ऑब्जेक्ट के एट्रिब्यूट अपडेट करें. अगले उदाहरण में, मौजूदा कैंपेन का इस्तेमाल किया गया है. इसे पिछले चरण के आउटपुट से कॉपी-एंड-पेस्ट किया जा सकता है.

CAMPAIGN_ID=CAMPAIGN_ID

सभी अपडेट के लिए, updateMask फ़ील्ड ज़रूरी है. यह उन JSON एट्रिब्यूट की कॉमा लगाकर अलग की गई लिस्ट होती है जो अनुरोध में होने चाहिए और जिन्हें अपडेट के तौर पर लागू किया जाना चाहिए. updateMask में शामिल एट्रिब्यूट, अगर अनुरोध के कोड में मौजूद नहीं हैं, तो किसी ऑब्जेक्ट पर साफ़ कर दिए जाते हैं. updateMask में शामिल नहीं किए गए एट्रिब्यूट, अगर अनुरोध के कोड में मौजूद हैं, तो उन्हें अनदेखा कर दिया जाता है.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'name': 'A changed campaign name #${RANDOM}',
    },
    'updateMask': 'name'
  }
],
}"

Removes

ऑब्जेक्ट को हटाने के लिए, उनके संसाधन के नाम को remove कार्रवाई के तौर पर बताया जाता है.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
  }
],
}"

कुछ फ़ाइलों का फ़ॉर्मैट नहीं बदला जा सका

अगर एक ही अनुरोध में कई कार्रवाइयां शामिल हैं, तो ज़रूरत के हिसाब से partialFailure की जानकारी दें. अगर इसकी वैल्यू true है, तो पूरी हो चुकी कार्रवाइयां लागू हो जाती हैं और अमान्य कार्रवाइयों के लिए गड़बड़ियां दिखती हैं. अगर इसकी वैल्यू false है, तो अनुरोध में शामिल सभी कार्रवाइयां सिर्फ़ तब पूरी होती हैं, जब वे सभी मान्य हों.

अगले उदाहरण में, मौजूदा कैंपेन का इस्तेमाल किया गया है. इसे Creates के उदाहरण के आउटपुट से कॉपी-एंड-पेस्ट किया जा सकता है.

CAMPAIGN_ID=CAMPAIGN_ID

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

curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'partialFailure': false,
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'manualCpc': {
        'enhancedCpcEnabled': false
      }
    },
    'updateMask': 'manual_cpc.enhanced_cpc_enabled'
  },
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID'
  }
]
}"

ग्रुप में की जाने वाली कार्रवाइयां

googleAds:mutate तरीके से, कई तरह के संसाधनों के साथ, कार्रवाइयों के ग्रुप भेजे जा सकते हैं. अलग-अलग तरह की कई कार्रवाइयां भेजी जा सकती हैं, ताकि कार्रवाइयों की एक ऐसी चेन बनाई जा सके जिसे ग्रुप के तौर पर लागू किया जाना चाहिए. अगर कोई भी कार्रवाई पूरी नहीं होती है, तो कार्रवाइयों का सेट पूरी तरह से लागू हो जाता है. वहीं, अगर कोई एक कार्रवाई भी पूरी नहीं होती है, तो सभी कार्रवाइयां पूरी नहीं होती हैं.

इस उदाहरण में, कैंपेन का बजट, कैंपेन, विज्ञापन ग्रुप, और विज्ञापन को एक साथ, कार्रवाइयों के एक सेट के तौर पर बनाने का तरीका दिखाया गया है. हर अगली कार्रवाई, पिछली कार्रवाई पर निर्भर करती है. अगर कोई एक कार्रवाई पूरी नहीं होती है, तो कार्रवाइयों का पूरा ग्रुप पूरी नहीं होता.

संसाधन के नामों में, प्लेसहोल्डर के तौर पर नेगेटिव पूर्णांकों (-1, -2, -3) का इस्तेमाल किया जाता है. इन्हें रनटाइम में, कार्रवाइयों की चेन से मिले नतीजों के साथ डाइनैमिक तरीके से भरा जाता है.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'mutateOperations': [
  {
    'campaignBudgetOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'name': 'My Campaign Budget #${RANDOM}',
        'deliveryMethod': 'STANDARD',
        'amountMicros': 500000,
        'explicitlyShared': false
      }
    }
  },
  {
    'campaignOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'status': 'PAUSED',
        'advertisingChannelType': 'SEARCH',
        'geoTargetTypeSetting': {
          'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
          'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
        },
        'name': 'My Search campaign #${RANDOM}',
        'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'targetSpend': {}
      }
    }
  },
  {
    'adGroupOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'name': 'My ad group #${RANDOM}',
        'status': 'PAUSED',
        'type': 'SEARCH_STANDARD'
      }
    }
  },
  {
    'adGroupAdOperation': {
      'create': {
        'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'status': 'PAUSED',
        'ad': {
          'responsiveSearchAd': {
            'headlines': [
              {
                'pinned_field': 'HEADLINE_1',
                'text': 'An example headline'
              },
              {
                'text': 'Another example headline'
              },
              {
                'text': 'Yet another headline'
              }
            ],
            'descriptions': [
              {
                'text': 'An example description'
              },
              {
                'text': 'Another example description'
              }
            ],
            'path1': 'all-inclusive',
            'path2': 'deals'
          },
          'finalUrls': ['https://www.example.com']
        }
      }
    }
  }
]
}"

खाते का मैनेजमेंट

खाते बनाए जा सकते हैं, ऐक्सेस किए जा सकने वाले खातों की सूची बनाई जा सकती है, और बाइनरी ऐसेट अपलोड की जा सकती हैं.

खाते बनाएं

createCustomerClient तरीके का इस्तेमाल करके, नए खाते बनाएं. ध्यान दें कि यूआरएल के लिए, क्लाइंट खाते के आईडी के बजाय मैनेजर खाते के आईडी की ज़रूरत होती है. मैनेजर खाते के तहत, नया क्लाइंट खाता बनाया जाता है.

curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'customerClient': {
  'descriptiveName': 'My Client #${RANDOM}',
  'currencyCode': 'USD',
  'timeZone': 'America/New_York'
}
}"

ऐक्सेस किए जा सकने वाले खातों की सूची बनाएं

दिए गए OAuth 2.0 ऐक्सेस टोकन की मदद से, ऐक्सेस किए जा सकने वाले Google Ads खातों की सूची पाने के लिए, listAccessibleCustomers तरीके के लिए, सामान्य GET अनुरोध का इस्तेमाल करें. इस अनुरोध में, मैनेजर या क्लाइंट खाते के आईडी का इस्तेमाल नहीं किया जाना चाहिए.

curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

बाइनरी ऐसेट अपलोड करें

assets:mutate तरीके का इस्तेमाल, ऐसेट अपलोड करने और उन्हें मैनेज करने के लिए किया जाता है ऐसेट. बाइनरी डेटा, जैसे कि इमेज को पैडिंग के साथ, स्टैंडर्ड base64 एन्कोडिंग का इस्तेमाल करके, स्ट्रिंग के तौर पर कोड में बदला जाता है. पैडिंग के साथ या उसके बिना, स्टैंडर्ड या यूआरएल के लिए सुरक्षित base64 एन्कोडिंग स्वीकार की जाती है.

इस उदाहरण में, सैंपल को छोटा रखने के लिए, 1 पिक्सल वाली GIF को कोड में बदला गया है. असल में, data पेलोड का साइज़ काफ़ी बड़ा होता है.

1 पिक्सल वाली GIF इमेज को कोड में बदलने के लिए, base64 कमांड लाइन यूटिलिटी (GNU कोर यूटिलिटी का हिस्सा) का इस्तेमाल करें.

base64 1pixel.gif

base64 में कोड में बदली गई वैल्यू को, एपीआई अनुरोध में data एट्रिब्यूट के तौर पर बताया जाता है.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My image asset #${RANDOM}',
      'type': 'IMAGE',
      'imageAsset': {
        'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA'
      }
    }
  }
]
}"
पीछे जाएं
आम तौर पर होने वाली गड़बड़ियां
आगे बढ़ें
इसे आज़माएं!