Google Ads কোয়েরি ল্যাঙ্গুয়েজ

পরামর্শ: আপনার GAQL কোয়েরি তৈরি ও যাচাই করতে ইন্ট্যার‍্যাক্টিভ কোয়েরি বিল্ডার ব্যবহার করুন।

মূল পরিভাষা

রিসোর্স

Google Ads-এ একটি এন্টিটি, যেমন campaign বা ad_group।

সেগমেন্ট

ডেটা গ্রুপ করার জন্য ব্যবহৃত ডাইমেনশন, যেমন segments.date বা segments.device। মেট্রিক সহ SELECT ক্লজে সেগমেন্ট অন্তর্ভুক্ত করা হলে, মেট্রিক সেগমেন্ট অনুযায়ী ভাগ করা হয়।

মেট্রিক

পারফর্ম্যান্সের পরিমাপ, যেমন metrics.impressions বা metrics.clicks।

অ্যাট্রিবিউট করা রিসোর্স

একটি রিসোর্স যা FROM ক্লজে মূল রিসোর্সের সাথে অন্তর্নিহিতভাবে যুক্ত, যা আপনাকে মূল রিসোর্স অ্যাট্রিবিউটের সাথে এর অ্যাট্রিবিউট বেছে নিতে দেয়।

রিসোর্স বা মেটাডেটা সংক্রান্ত তথ্যের জন্য কোয়েরি

Google Ads কোয়েরি ল্যাঙ্গুয়েজ নিম্নলিখিত ধরনের তথ্যের জন্য Google Ads API-কে কোয়েরি করতে পারে:

• GoogleAdsService Search বা SearchStream ব্যবহার করে রিসোর্স এবং তাদের সম্পর্কিত অ্যাট্রিবিউট, সেগমেন্ট ও মেট্রিক: GoogleAdsService কোয়েরি থেকে পাওয়া ফলাফল হল GoogleAdsRow ইনস্ট্যান্সের তালিকা, যেখানে প্রতিটি GoogleAdsRow একটি রিসোর্সকে দেখায়।

  কোনও অ্যাট্রিবিউট বা মেট্রিকের অনুরোধ করা হলে, সেই সারিতেও সেইসব ফিল্ড অন্তর্ভুক্ত থাকে। কোনও সেগমেন্টের জন্য অনুরোধ করা হলে, উত্তরে প্রতিটি সেগমেন্ট-রিসোর্স টাপলের জন্য একটি অতিরিক্ত সারিও দেখানো হয়।

• GoogleAdsFieldService-এ উপলভ্য ফিল্ড ও রিসোর্স সম্পর্কে মেটাডেটা: এই পরিষেবা কোয়েরি করা যায় এমন ফিল্ডের ক্যাটালগ প্রদান করে, যার মধ্যে তাদের মানানসই হওয়া ও ধরন সম্পর্কে নির্দিষ্ট তথ্য থাকে।

  GoogleAdsFieldService কোয়েরি থেকে পাওয়া ফলাফল হল GoogleAdsField ইনস্ট্যান্সের তালিকা, যেখানে প্রতিটি GoogleAdsField-এ অনুরোধ করা ফিল্ড সম্পর্কে বিবরণ থাকে।

কোয়েরি স্ট্রাকচার সম্পর্কে আরও জানতে, কোয়েরি স্ট্রাকচার এবং Google Ads কোয়েরি ল্যাঙ্গুয়েজ গ্রামার দেখুন।

রিসোর্স অ্যাট্রিবিউটের জন্য কোয়েরি

ক্যাম্পেন রিসোর্সের অ্যাট্রিবিউটের জন্য একটি বেসিক কোয়েরির উদাহরণ এখানে দেওয়া হল যা ক্যাম্পেন আইডি, নাম ও স্ট্যাটাস কীভাবে ফেরত দিতে হয় তা ব্যাখ্যা করে:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

এই কোয়েরি ক্যাম্পেন আইডি অনুযায়ী সাজায়। প্রতিটি ফলাফল GoogleAdsRow একটি campaign অবজেক্টকে উপস্থাপন করে যা ক্যাম্পেনের resource_name সহ নির্বাচিত ফিল্ড দিয়ে পূর্ণ হয়।

ক্যাম্পেন কোয়েরির জন্য আর কোন কোন ফিল্ড উপলভ্য আছে তা জানতে, Campaign রেফারেন্স ডকুমেন্টেশন দেখুন।

মেট্রিকের জন্য কোয়েরি

কোনও নির্দিষ্ট রিসোর্সের জন্য বেছে নেওয়া অ্যাট্রিবিউটের পাশাপাশি, আপনি সম্পর্কিত মেট্রিকের জন্যও কোয়েরি করতে পারেন:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

এই কোয়েরি শুধু সেইসব ক্যাম্পেন ফিল্টার করে যেগুলির স্ট্যাটাস PAUSED এবং ১০০০-এর বেশি ইম্প্রেশন আছে, ক্যাম্পেন আইডি অনুযায়ী সাজানো আছে। প্রতিটি ফলাফল GoogleAdsRow-এ একটি metrics ফিল্ড থাকবে যা বেছে নেওয়া মেট্রিক দিয়ে অটো-ফিল করা হবে।

কোয়েরি করা যায় এমন মেট্রিকের তালিকা দেখতে, Metrics ডকুমেন্টেশন দেখুন।

সেগমেন্টের জন্য কোয়েরি

কোনও নির্দিষ্ট রিসোর্সের জন্য বেছে নেওয়া অ্যাট্রিবিউটের পাশাপাশি, আপনি সম্পর্কিত সেগমেন্টের জন্যও কোয়েরি করতে পারবেন:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

মেট্রিকের জন্য কোয়েরি করার মতোই, এই কোয়েরি শুধুমাত্র সেইসব ক্যাম্পেন ফিল্টার করে যেগুলির স্ট্যাটাস PAUSED এবং যেগুলির ১০০০-এর বেশি ইম্প্রেশন আছে। তবে, এই কোয়েরি তারিখ অনুযায়ী ডেটা ভাগ করে। এর ফলে, প্রতিটি GoogleAdsRow-এ ক্যাম্পেন ও তারিখের সেগমেন্টের একটি টাপল থাকে। সেগমেন্ট করা হলে বেছে নেওয়া মেট্রিক স্প্লিট হয়ে যায় এবং SELECT ক্লজের প্রতিটি সেগমেন্ট অনুযায়ী গ্রুপ করা হয়।

কোয়েরি করা যায় এমন সেগমেন্টের তালিকা দেখতে, Segments ডকুমেন্টেশন দেখুন।

সম্পর্কিত রিসোর্সের অ্যাট্রিবিউটের জন্য কোয়েরি

প্রদত্ত রিসোর্সের জন্য করা কোয়েরিতে, উপলভ্য থাকলে আপনি হয়ত অন্যান্য সম্পর্কিত রিসোর্সের সাথে যোগ দিতে পারবেন। এইসব সম্পর্কিত রিসোর্সকে "অ্যাট্রিবিউট করা রিসোর্স" বলা হয়। আপনার কোয়েরিতে অ্যাট্রিবিউট বেছে নেওয়ার মাধ্যমে আপনি অ্যাট্রিবিউট করা রিসোর্সের সাথে অপ্রত্যক্ষভাবে যোগ দিতে পারবেন।

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

এই কোয়েরি শুধু ক্যাম্পেন অ্যাট্রিবিউট বেছে নেয় না, তার সাথে বেছে নেওয়া প্রতিটি ক্যাম্পেন থেকে সম্পর্কিত অ্যাট্রিবিউটও নিয়ে আসে। প্রতিটি ফলাফল GoogleAdsRow বেছে নেওয়া ক্যাম্পেন অ্যাট্রিবিউট এবং বেছে নেওয়া বিডিং স্ট্র্যাটেজি অ্যাট্রিবিউট bidding_strategy.name দিয়ে ভরা campaign অবজেক্টকে দেখায়।

ক্যাম্পেন কোয়েরির জন্য কোন কোন অ্যাট্রিবিউট করা রিসোর্স উপলভ্য তা জানতে, Campaign রেফারেন্স ডকুমেন্টেশন দেখুন।

পেশাদার পদ্ধতি

• দীর্ঘ সময় ধরে উত্তর দেওয়া এবং টাইমআউট এড়াতে শুধুমাত্র আপনার প্রয়োজনীয় ফিল্ডগুলি বেছে নিন।
• ডেভেলপমেন্ট ও টেস্টিংয়ের সময় LIMIT ব্যবহার করুন যাতে বড় ফলাফল সেট প্রসেস করতে না হয়।
• ডেটা ট্রান্সফার ও রেসপন্সের সাইজ কমাতে WHERE ক্লজে ফিল্টার প্রয়োগ করুন।
• জটিল কোয়েরি তৈরি করার আগে ফিল্ডের মানানসই ও ডেটার ধরন চেক করতে GoogleAdsFieldService ব্যবহার করুন।
• মনে রাখবেন যে কিছু ফিল্ড, বিশেষ করে যেগুলিতে প্রচুর পরিমাণে ডেটা বা জটিল গণনা থাকে, সেগুলি কোয়েরির খরচ বাড়াতে পারে।

কোয়েরির ফলাফলের ভিত্তিতে মিউটেট করুন

কোনও রিসোর্সের জন্য কোয়েরি করার সময়, আপনি সাথে সাথে অবজেক্ট হিসেবে ফেরত আসা ফলাফল নিতে, সেগুলি পরিবর্তন করতে এবং সেই রিসোর্সের পরিষেবায় মিউটেট পদ্ধতিতে ফেরত পাঠাতে পারবেন। এখানে একটি স্যাম্পেল ওয়ার্কফ্লো দেওয়া হল:

1. ১০০০-এর বেশি ইম্প্রেশন আছে এমন সব PAUSED ক্যাম্পেনের জন্য কোয়েরি এক্সিকিউট করুন।
2. উত্তরে প্রতিটি GoogleAdsRow-এর campaign ফিল্ড থেকে Campaign অবজেক্ট পান।
3. প্রতিটি ক্যাম্পেনের স্ট্যাটাস PAUSED থেকে ENABLED-এ পরিবর্তন করুন।
4. পরিবর্তিত ক্যাম্পেন এবং সংশ্লিষ্ট FieldMask সহ CampaignService.MutateCampaigns কল করুন যাতে সেগুলি আপডেট করা যায়।

মনে রাখবেন: কোয়েরি থেকে পাওয়া রিসোর্স আপডেট করার সময়, একটি FieldMask (অথবা আপনার ক্লায়েন্ট লাইব্রেরির বিল্ট-ইন ফিল্ড মাস্ক ইউটিলিটি ব্যবহার করুন) নির্দিষ্ট করুন যাতে শুধুমাত্র পরিবর্তিত ফিল্ড আপডেট করা হয়, READ_ONLY_FIELD বা IMMUTABLE_FIELD সংক্রান্ত সমস্যা এড়ানো যায় অথবা অনিচ্ছাকৃতভাবে অন্যান্য অ্যাট্রিবিউট ওভাররাইট করা যায়।

ফিল্ড মেটাডেটা

GoogleAdsFieldService-এ পাঠানো কোয়েরি ফিল্ড মেটাডেটা ফিরিয়ে আনার জন্য ব্যবহার করা হয়। এই তথ্য ব্যবহার করে বোঝা যাবে যে কীভাবে কোয়েরিতে ফিল্ডগুলি একসাথে ব্যবহার করা যেতে পারে। যেহেতু API থেকে ডেটা উপলভ্য এবং এটি কোনও কোয়েরি যাচাই বা তৈরি করার জন্য প্রয়োজনীয় মেটাডেটা প্রদান করে, তাই এটি ডেভেলপারদের প্রোগ্র্যামাটিক্যালি তা করার অনুমতি দেয়। মেটাডেটার জন্য একটি সাধারণ কোয়েরি এখানে দেওয়া হল:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

আপনি এই কোয়েরিতে <INSERT_RESOURCE_OR_FIELD>-এর পরিবর্তে রিসোর্স (যেমন customer বা campaign) অথবা ফিল্ড (যেমন campaign.id, metrics.impressions, বা ad_group.id) ব্যবহার করতে পারেন।

মূল পয়েন্ট: মনে রাখবেন যে এই কোয়েরিতে কোনও FROM ক্লজ নেই।

কোয়েরি করা যায় এমন ফিল্ডের তালিকা দেখতে, GoogleAdsField ডকুমেন্টেশন দেখুন।

ভার্সন-নির্দিষ্ট পার্থক্য

Google Ads কোয়েরি ল্যাঙ্গুয়েজ সিনট্যাক্স, ক্লজ ও অপারেটর সব কাজ করে এমন Google Ads API ভার্সনে (v23, v24, v25 ও v26) একই রকম হলেও, কোয়েরি করা যায় এমন রিসোর্স, সেগমেন্ট, মেট্রিক ও রিপোর্টিং আচরণের ক্যাটালগ মেজর ভার্সন অনুযায়ী আলাদা হয়। টার্গেট API ভার্সন এন্ডপয়েন্টে GoogleAdsFieldService কোয়েরি করুন যাতে সেই ভার্সনের ফিল্ড ও কম্প্যাটিবিলিটি সংক্রান্ত নিয়মগুলি পরীক্ষা করা যায়:

• ফাইনাল URL এক্সপ্যানশন অ্যাসেট ভিউ:
  • শপিং ক্যাম্পেন সংক্রান্ত সহায়তা (v26 এবং তার পরবর্তী ভার্সন): final_url_expansion_asset_view পারফর্ম্যান্স ম্যাক্স এবং সার্চ ক্যাম্পেন ছাড়াও শপিং ক্যাম্পেন (campaign.advertising_channel_type = 'SHOPPING') সমর্থন করে। শপিং ক্যাম্পেনের জন্য, আপনি ad_groupটি ফিল্ড বেছে নিতে এবং ফিল্টার করতে পারবেন, কিন্তু আপনি asset_groupটি ফিল্ড বেছে নিতে পারবেন না।
  • বেছে নেওয়া যায় এমন মেট্রিক (v25 এবং তার পরের ভার্সন): final_url_expansion_asset_view কোয়েরি করলে ভিউয়ের জন্য বেছে নেওয়া যায় এমন সব মেট্রিক রিটার্ন করে। v24 এবং তার আগের ভার্সনে, উত্তরে শুধুমাত্র পারফর্ম্যান্স ম্যাক্স ক্যাম্পেনের জন্য metrics.conversions এবং metrics.conversions_value এবং সার্চ ক্যাম্পেনের জন্য metrics.impressions অন্তর্ভুক্ত থাকে।
• লাইফসাইকেল গোল রিসোর্স: v25 এবং তার পরবর্তী ভার্সনে, সব লাইফসাইকেল গোল (নতুন গ্রাহক অর্জন, গ্রাহক ধরে রাখা এবং লয়ালটি রিটেনশন) ইউনিফায়েড goal এবং campaign_goal_config রিসোর্স থেকে কোয়েরি করা হয়, customer_lifecycle_goal এবং campaign_lifecycle_goal (যা v24 এবং তার আগের ভার্সনে নতুন গ্রাহক অর্জন গোলের জন্য ব্যবহার করা হত, এর পাশাপাশি গ্রাহক ধরে রাখার গোলের জন্য goal এবং campaign_goal_config ব্যবহার করা হত) পরিবর্তন করে।
• অ্যাপ ক্যাম্পেনের জন্য শপিং প্রোডাক্ট রিপোর্টিং: v24 এবং তার পরবর্তী ভার্সনে, shopping_product রিসোর্স শপিং, পারফর্ম্যান্স ম্যাক্স, ডিমান্ড জেনারেশন এবং ভিডিও ক্যাম্পেন ছাড়াও অ্যাপ ক্যাম্পেনের জন্য প্রোডাক্ট রো রিটার্ন করে (v23-এ, অ্যাপ ক্যাম্পেন shopping_product ফলাফল থেকে বাদ দেওয়া হয়েছে)।
• ভার্সন-নির্দিষ্ট রিসোর্স, সেগমেন্ট ও মেট্রিক:
  • v26 এবং তার পরবর্তী ভার্সন: এতে search_lift_keyword_bundle রিসোর্স, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property এবং সার্চ লিফ্ট মেট্রিক (যেমন metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros এবং metrics.search_lift_impressions) অন্তর্ভুক্ত।
  • v25 এবং তার পরের ভার্সন: লিফ্ট পরিমাপ রিসোর্স (যেমন lift_measurement_config), সেগমেন্ট যেমন segments.ad_sub_format_type এবং segments.loyalty_membership, এবং YouTube এনগেজমেন্ট মেট্রিক (metrics.youtube_likes, metrics.youtube_comments, এবং metrics.youtube_shares) অন্তর্ভুক্ত করে। local_services_lead.contact_details.email (যা v24 এবং তার আগের ভার্সনে বেছে নেওয়া যায়) সরিয়ে দেয়।
  • v24 এবং তার পরবর্তী ভার্সন: এর মধ্যে cart_data_sales_view রিসোর্স, segments.conversion_attribution_event_type-এ shopping_performance_view, segments.mobile_device_platform এবং performance_max_placement_view-এ segments.ad_network_type অন্তর্ভুক্ত। campaign_budget-এ campaign.video_brand_safety_suitability (customer.video_brand_safety_suitability দ্বারা প্রতিস্থাপিত), segments.ad_sub_network_type এবং ad_group_asset, campaign_asset ও customer_asset-এ segments.click_type সরিয়ে দেয় (যা শুধুমাত্র v23-এ বেছে নেওয়া যায়)।
• গ্র্যানুলার তারিখ লুকব্যাক সংক্রান্ত ত্রুটি কোড: ৩৭-মাসের লুকব্যাক উইন্ডোর বাইরে segments.date, segments.week বা segments.hour (অথবা সাব-মান্থলি তারিখের রেঞ্জে ফিল্টার) দ্বারা কোয়েরি সেগমেন্ট করলে, v24 এবং তার পরবর্তী ভার্সনে DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (অথবা v23-এ DateRangeError.UNKNOWN) রিটার্ন করে। আরও বিবরণের জন্য তারিখের রেঞ্জ দেখুন।

কোডের উদাহরণ

GoogleAdsService-এ Google Ads কোয়েরি ল্যাঙ্গুয়েজ ব্যবহার করার উদাহরণ ক্লায়েন্ট লাইব্রেরি-তে আছে। প্রাথমিক অপারেশন ফোল্ডারে এই ধরনের উদাহরণ আছে GetCampaigns, GetKeywords এবং SearchForGoogleAdsFields।