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

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

उदाहरण

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

ज़रूरी शर्तें

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

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

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

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

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

API_VERSION="16"
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 वाला तरीका, पेज पर नंबर डालने की प्रक्रिया का इस्तेमाल करता है. इसमें query के साथ बताए गए pageSize पैरामीटर को अडजस्ट किया जा सकता है.

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 '{
"pageSize": 10,
"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'

स्ट्रीमिंग

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'

बदलाव

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

बनाना

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

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

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

दिए गए 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 एन्कोडिंग को स्वीकार किया जाता है.

इस उदाहरण में, सैंपल को छोटा रखने के लिए, एक पिक्सल वाले 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'
      }
    }
  }
]
}"