উদাহরণ

এই গাইডটিতে ক্লায়েন্ট লাইব্রেরি ব্যবহার না করে সরাসরি REST এন্ডপয়েন্টে কল করার উদাহরণ রয়েছে।

পূর্বশর্ত

নীচের সমস্ত নমুনা curl কমান্ড ব্যবহার করে একটি ব্যাশ শেলে অনুলিপি এবং আটকানো বোঝানো হয়েছে।

এছাড়াও আপনার একটি ডেভেলপার টোকেন প্রয়োজন, পরীক্ষা অ্যাকাউন্ট অ্যাক্সেস ভাল, এবং অন্তত একটি ক্লায়েন্ট অ্যাকাউন্ট ধারণকারী Google বিজ্ঞাপন পরিচালক অ্যাকাউন্ট।

গুরুত্বপূর্ণ: এই উদাহরণগুলিতে, আমরা ধরে নিই যে আপনি একজন ব্যবহারকারীর দ্বারা একটি ক্লায়েন্ট অ্যাকাউন্ট ( 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

অন্যথায়, দুটি মিউটেট - উদাহরণ তৈরি করে একটি নতুন বাজেট এবং প্রচারণা তৈরি করে।

অনুসন্ধান করুন

কোয়েরি কুকবুক গাইডে অনেক রিপোর্টিং নমুনা রয়েছে যা কিছু ডিফল্ট Google বিজ্ঞাপন স্ক্রিনের সাথে মিলে যায় এবং এই গাইডে ব্যবহৃত একই পরিবেশের ভেরিয়েবলের সাথে কাজ করে। আমাদের ইন্টারেক্টিভ ক্যোয়ারী বিল্ডার টুলটিও ইন্টারেক্টিভভাবে কাস্টম কোয়েরি তৈরি করার জন্য একটি দুর্দান্ত সম্পদ।

পৃষ্ঠাসংক্রান্ত

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

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'

মিউটেটস

একাধিক মিউটেট অপারেশন ( 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 পদ্ধতি ব্যবহার করে নতুন অ্যাকাউন্ট তৈরি করুন। মনে রাখবেন যে URL-এর জন্য ক্লায়েন্ট অ্যাকাউন্ট আইডির পরিবর্তে একটি ম্যানেজার অ্যাকাউন্ট আইডি প্রয়োজন। ম্যানেজার অ্যাকাউন্টের অধীনে একটি নতুন ক্লায়েন্ট অ্যাকাউন্ট তৈরি করা হয়।

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 বিজ্ঞাপন অ্যাকাউন্টগুলির একটি তালিকা পেতে 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 এনকোডিং ব্যবহার করে একটি স্ট্রিং হিসাবে এনকোড করা হয়। প্যাডিং সহ বা ছাড়া স্ট্যান্ডার্ড বা ইউআরএল-নিরাপদ বেস64 এনকোডিং গ্রহণ করা হয়।

নমুনা সংক্ষিপ্ত রাখতে এই উদাহরণটি একটি 1-পিক্সেল GIF এনকোড করে৷ অনুশীলনে, data পেলোডগুলি অনেক বড়।

একটি 1-পিক্সেল GIF ইমেজ এনকোড করতে base64 কমান্ড লাইন ইউটিলিটি ( GNU কোর ইউটিলিটিগুলির অংশ) ব্যবহার করুন।

base64 1pixel.gif

বেস64-এনকোডেড মান একটি API অনুরোধে 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'
      }
    }
  }
]
}"