এই নির্দেশিকায় কোনো ক্লায়েন্ট লাইব্রেরি ব্যবহার না করে সরাসরি REST এন্ডপয়েন্ট কল করার উদাহরণ রয়েছে।
আরও বিস্তারিত কোড উদাহরণের জন্য, REST কোড উদাহরণের গিটহাব রিপোজিটরিটি দেখুন।
প্রতিটি এপিআই মেথডের রিকোয়েস্ট ও রেসপন্স বডি দেখতে, নির্দিষ্ট সার্ভিস এন্ডপয়েন্টগুলোর রেফারেন্স ডকুমেন্টেশন দেখুন।
উদাহরণস্বরূপ, GoogleAdsService.Search এর রেফারেন্স পেজটি Search মেথডের জন্য রিকোয়েস্ট এবং রেসপন্স বডিগুলো দেখায়।
পূর্বশর্ত
এখানে দেখানো সমস্ত নমুনা `curl` কমান্ড ব্যবহার করে ব্যাশ শেলে কপি-পেস্ট করার জন্য তৈরি করা হয়েছে।
আপনার একটি ডেভেলপার টোকেনও প্রয়োজন, টেস্ট অ্যাকাউন্টের অ্যাক্সেস হলেও চলবে, এবং একটি গুগল অ্যাডস ম্যানেজার অ্যাকাউন্ট লাগবে যাতে অন্তত একটি ক্লায়েন্ট অ্যাকাউন্ট রয়েছে।
পরিবেশগত পরিবর্তনশীল
দেখানো অনুযায়ী অ্যাকাউন্টের ক্রেডেনশিয়াল এবং আইডিগুলো প্রবেশ করান, এবং তারপর পরবর্তী উদাহরণগুলোতে ব্যবহৃত এনভায়রনমেন্ট ভেরিয়েবলগুলো কনফিগার করার জন্য আপনার টার্মিনালে কপি-পেস্ট করুন। অথরাইজেশন গাইডে একটি 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অন্যথায়, দুটি 'মিউটেটস - ক্রিয়েটস' উদাহরণ একটি নতুন বাজেট এবং প্রচারাভিযান তৈরি করে।
অনুসন্ধান
কোয়েরি কুকবুক গাইডটিতে অনেক রিপোর্টিং নমুনা রয়েছে যা গুগল অ্যাডস-এর কিছু ডিফল্ট স্ক্রিনের অনুরূপ এবং এই গাইডে ব্যবহৃত একই এনভায়রনমেন্ট ভেরিয়েবলগুলোর সাথে কাজ করে। ইন্টারেক্টিভভাবে কাস্টম কোয়েরি তৈরি করার জন্য আমাদের ইন্টারেক্টিভ কোয়েরি বিল্ডার টুলটিও একটি চমৎকার রিসোর্স।
পৃষ্ঠাঙ্কিত
search পদ্ধতিতে পেজিনেশন ব্যবহার করা হয়, যেখানে পেজের আকার ১০,০০০ আইটেম পর্যন্ত নির্দিষ্ট করা থাকে এবং query পাশাপাশি একটি page_token উল্লেখ করা হয়।
কার্ল
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 -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'
পরিবর্তিত হয়
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 , অনুরোধের সমস্ত অপারেশন সফল হবে যদি এবং কেবল যদি সেগুলো সবই বৈধ হয়।
পরবর্তী উদাহরণটিতে একটি বিদ্যমান ক্যাম্পেইন ব্যবহার করা হয়েছে; আপনি '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 মেথড ব্যবহার করে নতুন অ্যাকাউন্ট তৈরি করুন। মনে রাখবেন যে, 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 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 মেথডটি অ্যাসেট আপলোড এবং পরিচালনা করার জন্য ব্যবহৃত হয়। বাইনারি ডেটা, যেমন একটি ছবি, প্যাডিং সহ স্ট্যান্ডার্ড বেস৬৪ এনকোডিং ব্যবহার করে একটি স্ট্রিং হিসাবে এনকোড করা হয়। প্যাডিং সহ বা প্যাডিং ছাড়া স্ট্যান্ডার্ড অথবা ইউআরএল-সেফ বেস৬৪ এনকোডিং উভয়ই গ্রহণ করা হয়।
নমুনাটিকে সংক্ষিপ্ত রাখার জন্য এই উদাহরণে একটি ১-পিক্সেলের GIF এনকোড করা হয়েছে। বাস্তবে, data পরিমাণ এর চেয়ে অনেক বেশি হয়ে থাকে।
১-পিক্সেলের একটি GIF ছবি এনকোড করতে base64 কমান্ড লাইন ইউটিলিটি (যা GNU core utilities- এর একটি অংশ) ব্যবহার করুন।
base64 1pixel.gif
এপিআই অনুরোধে 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' } } } ] }"