API স্ট্রাকচার

এই নির্দেশিকা 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 অ্যাকাউন্ট জুড়ে বিশ্বব্যাপী অনন্য, আবার অন্যগুলি শুধুমাত্র একটি নির্দিষ্ট সীমার মধ্যে অনন্য।

আপনার 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 হল অবজেক্ট ও পারফর্ম্যান্স পরিসংখ্যান উদ্ধার করার জন্য একক, ইউনিফায়েড পরিষেবা।

GoogleAdsService-এর জন্য Search এবং SearchStream সংক্রান্ত সব অনুরোধের জন্য এমন কোয়েরি প্রয়োজন যা কোয়েরি করার জন্য রিসোর্স, রিসোর্স অ্যাট্রিবিউট এবং পারফর্ম্যান্স মেট্রিক নির্দিষ্ট করে, অনুরোধ ফিল্টার করার জন্য প্রেডিকেট এবং পারফর্ম্যান্স পরিসংখ্যান আরও ভেঙে দেখানোর জন্য সেগমেন্ট ব্যবহার করে। কোয়েরি ফর্ম্যাট সম্পর্কে আরও জানতে, Google Ads কোয়েরি ল্যাঙ্গুয়েজ গাইড দেখুন।

মেটাডেটা ফিরিয়ে আনা

GoogleAdsFieldService Google Ads API-তে রিসোর্স সম্পর্কে মেটাডেটা ফিরিয়ে আনে, যেমন রিসোর্সের জন্য উপলভ্য অ্যাট্রিবিউট এবং এর ডেটার ধরন। এই পরিষেবা কোয়েরি করার ব্যাপারে বিস্তারিত জানতে রিসোর্স মেটাডেটা গাইড দেখুন।

এই পরিষেবা GoogleAdsService-এ কোয়েরি তৈরি করার জন্য প্রয়োজনীয় তথ্য প্রদান করে। সুবিধার জন্য, GoogleAdsFieldService-এর মাধ্যমে ফেরত পাঠানো তথ্য ফিল্ড রেফারেন্স ডকুমেন্টেশনে-ও উপলভ্য।