এই নির্দেশিকা Google Ads API-এর প্রাথমিক উপাদানগুলির সাথে পরিচয় করিয়ে দেয়। Google Ads API-তে রিসোর্স ও পরিষেবা থাকে। রিসোর্স Google Ads এন্টিটির প্রতিনিধিত্ব করে, যখন পরিষেবা Google Ads এন্টিটি পুনরুদ্ধার এবং ম্যানিপুলেট করে।
অবজেক্ট হায়ারার্কি
Google Ads অ্যাকাউন্টকে অবজেক্টের হায়ারার্কি হিসেবে দেখা যেতে পারে।
অ্যাকাউন্টের টপ-লেভেল রিসোর্স হল গ্রাহক।
প্রতিটি গ্রাহকের এক বা একাধিক অ্যাক্টিভ ক্যাম্পেন আছে।
প্রতিটি ক্যাম্পেনে এক বা একাধিক বিজ্ঞাপন গ্রুপ থাকে, যা আপনার বিজ্ঞাপনগুলিকে লজিক্যাল সংগ্রহে গ্রুপ করতে ব্যবহৃত হয়।
বিজ্ঞাপন গ্রুপ বিজ্ঞাপন হল এমন একটি বিজ্ঞাপন যা আপনি বিজ্ঞাপন গ্রুপে চালাচ্ছেন। অ্যাপ ক্যাম্পেন ছাড়া, যেগুলিতে বিজ্ঞাপন গ্রুপ পিছু একটি করে বিজ্ঞাপন গ্রুপ বিজ্ঞাপন থাকে, প্রতিটি বিজ্ঞাপন গ্রুপে একটি বা একাধিক বিজ্ঞাপন গ্রুপ বিজ্ঞাপন থাকে।
পারফর্ম্যান্স ম্যাক্স ক্যাম্পেন অন্যান্য ক্যাম্পেনের ধরনের থেকে আলাদা
স্ট্রাকচার ব্যবহার করে: বিজ্ঞাপন গ্রুপ এবং বিজ্ঞাপন গ্রুপের বিজ্ঞাপনের পরিবর্তে, পারফর্ম্যান্স ম্যাক্স ক্যাম্পেনে অ্যাসেট গ্রুপ থাকে। আপনি
AssetGroupAsset ব্যবহার করে অ্যাসেট গ্রুপে ক্রিয়েটিভ অ্যাসেট লিঙ্ক করতে
এবং AssetGroupSignal ব্যবহার করে দর্শক বা সার্চ থিম সিগন্যাল
অ্যাটাচ করতে পারবেন।
আপনি এক বা একাধিক AdGroupCriterion
বা CampaignCriterion রিসোর্স কোনও বিজ্ঞাপন গ্রুপ বা ক্যাম্পেনের সাথে
অ্যাটাচ করতে পারবেন। এগুলি এমন মাপকাঠি দেখায় যা বিজ্ঞাপন কীভাবে ট্রিগার হয় তা নির্ধারণ করে।
অনেক মাপকাঠির ধরন আছে,
যেমন কীওয়ার্ড, বয়সের রেঞ্জ ও লোকেশন। ক্যাম্পেন লেভেলে
নির্ধারিত মাপকাঠি ক্যাম্পেনের মধ্যে থাকা অন্যান্য সব রিসোর্সকে প্রভাবিত করে। এছাড়াও, আপনি ক্যাম্পেন বা স্বতন্ত্র বিজ্ঞাপনের জন্য বাজেট এবং শুরু ও শেষ হওয়ার তারিখ ও সময় নির্দিষ্ট করতে পারবেন। এর জন্য AdGroupAd.start_date_time এবং AdGroupAd.end_date_time ব্যবহার করুন।
সবশেষে, আপনি অ্যাকাউন্ট, ক্যাম্পেন, বিজ্ঞাপন গ্রুপ বা অ্যাসেট গ্রুপ লেভেলে অ্যাসেট অ্যাটাচ করতে পারবেন। অ্যাসেট আপনাকে বিজ্ঞাপনে অতিরিক্ত তথ্য যোগ করতে দেয়, যেমন ফোন নম্বর, রাস্তার ঠিকানা বা প্রোমোশন। অ্যাসেট এক নজরে দেখুন।
রিসোর্স
আপনার Google Ads অ্যাকাউন্টের মধ্যে থাকা এন্টিটিগুলিকে রিসোর্স বলা হয়।
Campaign এবং AdGroup হল
রিসোর্সের দুটি উদাহরণ।
অবজেক্ট আইডি
Google Ads-এ প্রতিটি অবজেক্ট তার নিজস্ব আইডি দ্বারা শনাক্ত করা হয়। এইসব আইডির মধ্যে কিছু আইডি সব Google Ads অ্যাকাউন্ট জুড়ে বিশ্বব্যাপী অনন্য, অন্যগুলি শুধুমাত্র একটি সীমিত স্কোপের মধ্যে অনন্য।
| অবজেক্ট আইডি | অনন্যতার স্কোপ | বিশ্বব্যাপী অনন্য? |
|---|---|---|
| বাজেট ID | গ্লোবাল | হ্যাঁ |
| ক্যাম্পেন আইডি | গ্লোবাল | হ্যাঁ |
| বিজ্ঞাপন গ্রুপ আইডি | গ্লোবাল | হ্যাঁ |
| বিজ্ঞাপন ID | বিজ্ঞাপন গ্রুপ | না, তবে (AdGroupId, AdId) পেয়ারটি বিশ্বজুড়ে অনন্য। একাধিক বিজ্ঞাপন গ্রুপে AdId শেয়ার করা নিষিদ্ধ। |
| AdGroupCriterion ID | বিজ্ঞাপন গ্রুপ | না, তবে (AdGroupId, CriterionId) পেয়ার বিশ্বব্যাপী অনন্য |
| CampaignCriterion ID | ক্যাম্পেন | না, তবে (CampaignId, CriterionId) পেয়ারটি বিশ্বজুড়ে অনন্য |
| লেবেল ID | গ্রাহক | না, তবে (CustomerId, LabelId) পেয়ার বিশ্বব্যাপী অনন্য |
| UserList ID | গ্লোবাল | হ্যাঁ |
| অ্যাসেট আইডি | গ্লোবাল | হ্যাঁ |
আপনার Google Ads অবজেক্টের জন্য লোকাল স্টোরেজ ডিজাইন করার সময় এই আইডি সংক্রান্ত নিয়ম কাজে লাগতে পারে।
কিছু অবজেক্ট একাধিক এন্টিটি টাইপের জন্য ব্যবহার করা যেতে পারে। এই ধরনের ক্ষেত্রে, অবজেক্টে
একটি type ফিল্ড থাকে যা এর কন্টেন্টের বিবরণ দেয়। যেমন,
AdGroupAd বলতে এমন কোনও অবজেক্টকে বোঝানো হতে পারে, যেমন
রেসপন্সিভ সার্চ বিজ্ঞাপন, হোটেল বিজ্ঞাপন বা ডিমান্ড জেনারেশন বিজ্ঞাপন। এই ভ্যালু AdGroupAd.ad.type ফিল্ডের মাধ্যমে
অ্যাক্সেস করা যেতে পারে এবং AdType enum-এ
একটি ভ্যালু রিটার্ন করে। মনে রাখবেন যে
মিউটেবিলিটি ভার্সন অনুযায়ী আলাদা হতে পারে (যেমন, Ad-এ VideoResponsiveAdInfo
v24 এবং তার পরবর্তী ভার্সনে মিউটেবল)।
রিসোর্সের নাম
প্রতিটি রিসোর্সকে একটি resource_name স্ট্রিং দ্বারা অনন্যভাবে শনাক্ত করা হয় যা
রিসোর্স এবং এর পেরেন্টকে একটি পাথে একত্রিত করে। যেমন, ক্যাম্পেন
রিসোর্স নামের ফর্ম হল:
customers/customer_id/campaigns/campaign_id
তাই, 1234567 কাস্টমার আইডি সহ Google Ads অ্যাকাউন্টে 987654 আইডি সহ ক্যাম্পেনের জন্য, resource_name হবে:
customers/1234567/campaigns/987654
পরিষেবা
পরিষেবা আপনাকে Google Ads এন্টিটি ফিরিয়ে আনতে ও পরিবর্তন করতে দেয়। তিন ধরনের পরিষেবা রয়েছে: পরিবর্তন, অবজেক্ট ও স্ট্যাটাস রিট্রিভাল এবং মেটাডেটা রিট্রিভাল পরিষেবা।
অবজেক্ট পরিবর্তন (মিউটেশন) করা
রিসোর্স-নির্দিষ্ট পরিষেবাগুলি mutate অনুরোধ ব্যবহার করে একটি সংশ্লিষ্ট রিসোর্স প্রকারের দৃষ্টান্তগুলি পরিবর্তন করে। এছাড়াও, আপনি
GoogleAdsService.Mutate ব্যবহার করে একটি অনুরোধে একাধিক রিসোর্স টাইপ জুড়ে অ্যাটমিক মিউটেশন
সম্পাদন করতে পারেন (যেমন ক্যাম্পেন বাজেট, ক্যাম্পেন এবং বিজ্ঞাপন গ্রুপ একসাথে
তৈরি করা)।
রিসোর্স-নির্দিষ্ট পরিষেবার উদাহরণ:
গ্রাহকদের তথ্য পরিবর্তন করার জন্য
CustomerService।CampaignServiceপরিবর্তন করার জন্য ক্যাম্পেন।বিজ্ঞাপন গ্রুপ পরিবর্তন করার জন্য
AdGroupService।
প্রতিটি mutate অনুরোধে সংশ্লিষ্ট operation অবজেক্ট থাকতে হবে। যেমন, CampaignService.MutateCampaigns পদ্ধতিতে এক বা একাধিক
CampaignOperation ইনস্ট্যান্স থাকতে হবে। অপারেশন সম্পর্কে বিস্তারিত আলোচনার জন্য
অবজেক্ট পরিবর্তন করুন দেখুন।
কনকারেন্ট মিউটেশন
একাধিক সোর্স থেকে একই সাথে Google Ads অবজেক্ট পরিবর্তন করা যাবে না। আপনার অ্যাপের মাধ্যমে একাধিক ব্যবহারকারী একই অবজেক্ট আপডেট করলে অথবা আপনি একাধিক থ্রেড ব্যবহার করে সমান্তরালভাবে Google Ads অবজেক্ট মিউটেট করলে, এর ফলে সমস্যা দেখা দিতে পারে। এর মধ্যে একই অ্যাপ্লিকেশনের একাধিক থ্রেড থেকে অথবা আলাদা আলাদা অ্যাপ্লিকেশন থেকে (যেমন, আপনার অ্যাপ এবং একই সাথে চলা Google Ads UI সেশন) অবজেক্ট আপডেট করা অন্তর্ভুক্ত।
আপডেট করার আগে অবজেক্ট লক করার কোনও উপায় API প্রদান করে না; দুটি সোর্স
একইসাথে কোনও অবজেক্ট মিউটেট করার চেষ্টা করলে, API
DatabaseError.CONCURRENT_MODIFICATION_ERROR দেখায়।
অ্যাসিঙ্ক্রোনাস বনাম সিঙ্ক্রোনাস মিউটেট
Google Ads API-এর মিউটেশন পদ্ধতি সিঙ্ক্রোনাস। API কল শুধুমাত্র অবজেক্ট মিউট করার পরেই উত্তর দেয়, এর ফলে প্রতিটি অনুরোধের জন্য আপনাকে উত্তরের জন্য অপেক্ষা করতে হয়। এই পদ্ধতিটি কোড করার জন্য তুলনামূলকভাবে সহজ হলেও, প্রসেসগুলিকে কল সম্পূর্ণ হওয়ার জন্য অপেক্ষা করতে বাধ্য করা হলে, লোড ব্যালেন্সিংয়ের উপর নেতিবাচক প্রভাব পড়তে পারে এবং রিসোর্স নষ্ট হতে পারে।
বিকল্প পদ্ধতি হল
BatchJobService ব্যবহার করে অ্যাসিঙ্ক্রোনাসভাবে অবজেক্ট মিউটেট করা, যা একাধিক পরিষেবায় ব্যাচ অপারেশন করে এবং সেগুলি সম্পূর্ণ হওয়ার জন্য অপেক্ষা করে না। ব্যাচ জব জমা দেওয়ার পরে, Google Ads API সার্ভার অ্যাসিঙ্ক্রোনাসভাবে অপারেশন এক্সিকিউট করে,
অন্যান্য অপারেশন পারফর্ম করার জন্য প্রসেস ফ্রি করে দেয়। সম্পূর্ণ হয়েছে কিনা তা জানতে আপনি মাঝে মাঝে
জবের স্ট্যাটাস চেক করতে পারেন।
অ্যাসিঙ্ক্রোনাস প্রসেসিং সম্পর্কে আরও জানতে ব্যাচ প্রসেসিং নির্দেশিকা দেখুন।
পরিবর্তন যাচাইকরণ
আসল ডেটার উপর কলটি কার্যকর না করেই বেশিরভাগ মিউটেট রিকোয়েস্ট যাচাই করা যায়। আপনি অপারেশনটি বাস্তবে না চালিয়েই, অনুপস্থিত প্যারামিটার ও ভুল ফিল্ড ভ্যালুর জন্য অনুরোধ পরীক্ষা করতে পারবেন।
এই ফিচার ব্যবহার করতে, অনুরোধের ঐচ্ছিক validate_only বুলিয়ান ফিল্ড
true-এ সেট করুন। অনুরোধটি সম্পূর্ণভাবে যাচাই করা হয়, যেন এটি এক্সিকিউট করা হবে, কিন্তু
চূড়ান্ত এক্সিকিউশন এড়িয়ে যাওয়া হয়। কোনও সমস্যা না পাওয়া গেলে, কোনও মিউটেট করা ফলাফল ছাড়াই
উত্তর ফেরত পাঠানো হয় (results খালি থাকে)। যাচাইকরণ ব্যর্থ হলে,
ডিফল্ট হিসেবে GoogleAdsFailure RPC
সমস্যার (partial_failure = false) কারণে অনুরোধ ব্যর্থ হয় অথবা partial_failure_error-এ অপারেশন-নির্দিষ্ট সমস্যা সহ
সাধারণ উত্তর ফেরত দেয় যখন
partial_failure = true।
সাধারণ নীতি লঙ্ঘনের জন্য বিজ্ঞাপন পরীক্ষা করার ক্ষেত্রে validate_only বিশেষভাবে উপযোগী। বিজ্ঞাপন নির্দিষ্ট শব্দ, যতিচিহ্ন, ক্যাপিটালাইজেশন বা দৈর্ঘ্যের মতো নীতি লঙ্ঘন করলে তা অটোমেটিক বাতিল করা হয়।
একটি খারাপ বিজ্ঞাপন
পুরো ব্যাচকে ব্যর্থ করতে পারে। validate_only-এর মধ্যে নতুন বিজ্ঞাপন পরীক্ষা করার
অনুরোধ করলে এই ধরনের কোনও লঙ্ঘন প্রকাশ পেতে পারে। এটি কীভাবে কাজ করে তা দেখতে, নীতি লঙ্ঘন সংক্রান্ত সমস্যা
সমাধান করার কোডের উদাহরণ দেখুন।
অবজেক্ট ও পারফর্ম্যান্সের পরিসংখ্যান পাওয়া
GoogleAdsService হল অবজেক্ট ও পারফর্ম্যান্স পরিসংখ্যান
উদ্ধার করার জন্য একক, ইউনিফায়েড পরিষেবা।
Search ও
SearchStream সব অনুরোধের জন্য
GoogleAdsService এমন কোয়েরি প্রয়োজন যা
কোয়েরি করার রিসোর্স, রিসোর্স অ্যাট্রিবিউট ও পারফর্ম্যান্স মেট্রিক
রিট্রিভ করার জন্য, অনুরোধ ফিল্টার করার জন্য ব্যবহার করা প্রেডিকেট এবং পারফর্ম্যান্স পরিসংখ্যানকে
আরও বিশদে দেখার জন্য ব্যবহার করা সেগমেন্ট নির্দিষ্ট করে। কোয়েরি ফর্ম্যাট সম্পর্কে আরও জানতে, Google Ads কোয়েরি ল্যাঙ্গুয়েজ গাইড দেখুন।
মেটাডেটা ফিরিয়ে আনা
GoogleAdsFieldService Google Ads API-তে রিসোর্স সম্পর্কে মেটাডেটা ফিরিয়ে আনে, যেমন রিসোর্সের জন্য উপলভ্য অ্যাট্রিবিউট এবং এর ডেটার ধরন। এই পরিষেবা কোয়েরি করার ব্যাপারে বিস্তারিত জানতে রিসোর্স মেটাডেটা
গাইড দেখুন।
এই পরিষেবাটি
GoogleAdsService-এর জন্য কোয়েরি তৈরি করতে প্রয়োজনীয় তথ্য প্রদান করে। সুবিধার জন্য, GoogleAdsFieldService-এর মাধ্যমে
ফেরত পাঠানো তথ্য
ফিল্ড রেফারেন্স ডকুমেন্টেশনে-ও উপলভ্য।