चेतावनी: आप एपीआई के REST इंटरफ़ेस के बारे में दस्तावेज़ देख रहे हैं. हमारी ज़्यादातर आधिकारिक क्लाइंट लाइब्रेरी, gRPC का इस्तेमाल करती हैं. ज़्यादा जानकारी के लिए, REST के बारे में जानकारी देखें.

इस पेज का अनुवाद Cloud Translation API से किया गया है.

उदाहरण

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

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

नीचे दिए गए सभी सैंपल, curl कमांड का इस्तेमाल करके, कॉपी करके बैश शेल में चिपकाने के लिए हैं.

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

अहम जानकारी: इन उदाहरणों में, हम यह मानकर चलते हैं कि जिस उपयोगकर्ता के पास क्लाइंट खाते को सीधे तौर पर मैनेज करने वाले मैनेजर खाते (MANAGER_CUSTOMER_ID) का एडमिन ऐक्सेस है वह किसी क्लाइंट खाते (CUSTOMER_ID) को ऐक्सेस कर रहा है. अगर इसके बजाय, किसी व्यक्तिगत क्लाइंट खाते को सीधे ऐक्सेस किया जा रहा है, तो login-customer-id हेडर को छोड़ दें या उसे CUSTOMER_ID की वैल्यू पर सेट करें. ध्यान दें कि खाते बनाने जैसे कुछ उदाहरणों के लिए, मैनेजर खाता होना ज़रूरी है.

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

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

API_VERSION="17"
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

अगर ऐसा नहीं है, तो दो बदलाव - उदाहरण बनाएं से एक नया बजट और कैंपेन बनाया जा सकता है.

रिपोर्ट में खोजना

क्वेरी कुकबुक गाइड में रिपोर्टिंग के कई सैंपल हैं, जो कुछ डिफ़ॉल्ट 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}"
}'

जीएक्यूएल

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'
"
}'

जीएक्यूएल

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'

बदलाव

operations कलेक्शन में अपने-आप जानकारी भरकर, JSON अनुरोध के एक ही मुख्य भाग में एक से ज़्यादा बदलाव किए जा सकते हैं (create, update या remove).

बनाएं

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

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

ये संसाधन, दूसरे संसाधनों के बारे में बताते हैं. ऐसा संसाधन के नाम से किया जाता है. नीचे बनाया गया कैंपेन, स्ट्रिंग की वैल्यू वाले रिसॉर्स के नाम से 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': {}
    }
  }
]
}"

अपडेट

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'
  }
],
}"

हटाएं

ऑब्जेक्ट को 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, तो अनुरोध की सभी कार्रवाइयां तभी सफल होती हैं, जब सभी कार्रवाइयां मान्य हों.

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

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'
}
}"

ऐक्सेस किए जा सकने वाले खातों की लिस्टिंग

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

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 एन्कोडिंग का इस्तेमाल करके, स्ट्रिंग के तौर पर एन्कोड किया जाता है. पैडिंग (जगह) के साथ या उसके बिना, स्टैंडर्ड या यूआरएल के हिसाब से कोड में बदलने का तरीका स्वीकार किया जाता है.

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

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

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'
      }
    }
  }
]
}"