কোয়েরি রিপোর্ট ডেটা

reportData.query মেথডটি রিপোর্ট ডেটা পুনরুদ্ধার করার একটি সিনক্রোনাস উপায় প্রদান করে। স্ট্যান্ডার্ড Reports সার্ভিসের মতো নয়, যা ফাইল-ভিত্তিক রিপোর্ট (CSV বা Excel) তৈরি করে, এই মেথডটি সরাসরি রেসপন্সে স্ট্রাকচার্ড JSON ডেটা ফেরত দেয়। এর ফলে আগে থেকে একটি Report রিসোর্স সংজ্ঞায়িত, তৈরি এবং সংরক্ষণ করার প্রয়োজন হয় না, যা এটিকে রিয়েল-টাইম ডেটা পুনরুদ্ধার এবং অনুসন্ধানের জন্য আদর্শ করে তোলে।

সংক্ষিপ্ত বিবরণ

আপনার Campaign Manager 360 রিপোর্টিং ডেটা কোয়েরি করার জন্য এই এন্ডপয়েন্টটি কীভাবে ব্যবহার করতে হয়, তা ভালোভাবে জানতে এই গাইডটি অনুসরণ করুন।

অনুরোধটি প্রস্তুত করুন

ডাইমেনশন, মেট্রিক, তারিখের পরিসর, ফিল্টার এবং সর্টিং ক্রাইটেরিয়া উল্লেখ করে একটি ReportDataQueryRequest তৈরি করুন।

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}

dateRange

একটি DateRange অবজেক্ট যা কোয়েরির জন্য সময়কাল নির্দিষ্ট করে। এটি একটি কাস্টম ডেট রেঞ্জ বা একটি রিলেটিভ ডেট রেঞ্জ হতে পারে।

dimensionNames

গ্রুপ করার জন্য স্ট্যান্ডার্ড ডাইমেনশন নামগুলোর একটি তালিকা।

metricNames

প্রয়োজনীয়। অন্তর্ভুক্ত করার জন্য প্রমিত মেট্রিক নামগুলোর একটি তালিকা।

dimensionFilters

রিপোর্টের ডেটা ফিল্টার করতে ব্যবহৃত DimensionValue অবজেক্টগুলোর একটি তালিকা। কোনো ডাইমেনশনের নির্দিষ্ট মানগুলোতে কোয়েরির ফলাফল সীমাবদ্ধ করতে এটি ব্যবহার করুন।

sortBys

ডাইমেনশন বা মেট্রিক্সের জন্য সর্টিং কনফিগারেশন। প্রতিটি কনফিগারেশনে ফিল্ডের নাম এবং একটি সর্ট অর্ডার অন্তর্ভুক্ত থাকে।

maxResults

প্রতি পৃষ্ঠায় ফেরত দেওয়া সারির সর্বোচ্চ সংখ্যা (ডিফল্ট: 100 , সর্বোচ্চ: 1000 )।

পৃষ্ঠা সংখ্যা

maxResults ফিল্ডটি একটিমাত্র রেসপন্সে কতগুলো রেজাল্ট ফেরত আসবে তা নিয়ন্ত্রণ করে। উদাহরণস্বরূপ, যদি আপনি maxResults কে 10 সেট করেন, তাহলে API সর্বোচ্চ ১০টি রেজাল্ট ফেরত দেবে। যদি আপনার অনুরোধের সাথে মেলে এমন রেজাল্টের সংখ্যা ১০-এর কম হয়, তাহলে API-টি ১০টির চেয়ে কম রেজাল্ট ফেরত দিতে পারে।

অতিরিক্ত ফলাফল উপলব্ধ থাকলে, রেসপন্সে একটি nextPageToken অন্তর্ভুক্ত থাকে। ফলাফলের পরবর্তী পৃষ্ঠাটি পেতে, pageToken ফিল্ডে এই টোকেনটি সেট করে একই রিকোয়েস্টটি আবার পাঠান। রিকোয়েস্টের অন্য সব প্যারামিটার অপরিবর্তিত রাখুন।

অনুরোধ পাঠান

reportdata/query এন্ডপয়েন্টে একটি HTTP POST অনুরোধ পাঠান:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

আপনার অনুরোধটি স্ট্যান্ডার্ড OAuth 2.0 ক্রেডেনশিয়াল এবং প্রয়োজনীয় স্কোপ ব্যবহার করে প্রমাণীকৃত হয়েছে কিনা তা নিশ্চিত করুন। আরও তথ্যের জন্য ‘অনুরোধ অনুমোদন’ দেখুন।

সফল প্রতিক্রিয়া

একটি সফল কোয়েরি একটি HTTP 200 OK প্রতিক্রিয়া প্রদান করে, যার JSON পেলোডে columnHeaders , rows এবং totalRow অন্তর্ভুক্ত থাকে।

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}

columnHeaders

ফেরত আসা ফিল্ডগুলোর নাম এবং প্রকার ( DIMENSION বা METRIC )।

rows

কোয়েরির ফলাফল ধারণকারী ReportDataRow অবজেক্টগুলোর একটি তালিকা। প্রতিটি সারির স্ট্রিং মানগুলো columnHeaders সাথে অবস্থান অনুসারে সারিবদ্ধ থাকে।

totalRow

একটি একক সমষ্টিগত সারি যা সমস্ত মিলে যাওয়া মেট্রিকের যোগফলকে উপস্থাপন করে। যে সমস্ত ডাইমেনশন ফিল্ড এবং মেট্রিকের যোগফল বের করা যায় না (উদাহরণস্বরূপ, uniqueReachTotalReach মতো Reach মেট্রিক), সেগুলি এই সারিতে খালি ( "" ) থাকে।

nextPageToken

অতিরিক্ত সারি থাকলে, পরবর্তী পৃষ্ঠাটি আনার জন্য ব্যবহৃত একটি টোকেন।

লেটেন্সি এবং টাইমআউট

যেহেতু এটি একটি সিনক্রোনাস এন্ডপয়েন্ট, তাই কোয়েরিগুলো তাৎক্ষণিকভাবে এক্সিকিউট হয় এবং ডেটা সরাসরি রেসপন্সে ফেরত আসে ( maxResults পেজিনেশন লিমিট পর্যন্ত)। কোয়েরিগুলোর সর্বোচ্চ এক্সিকিউশন টাইম হলো ৬০ সেকেন্ড । যদি কোনো কোয়েরি এই লিমিট অতিক্রম করে, তাহলে এপিআই অপারেশনটি বন্ধ করে দেয় এবং একটি HTTP 503 Service Unavailable এরর ফেরত দেয়।

আপনি যদি এই ত্রুটির সম্মুখীন হন, তাহলে তারিখের পরিসর সংকুচিত করার, ফিল্টারগুলো সীমিত করার (যেমন নির্দিষ্ট বিজ্ঞাপনদাতা বা ক্যাম্পেইন দ্বারা ফিল্টার করা), অথবা অনুরোধকৃত ডাইমেনশন ও মেট্রিক্সের সংখ্যা কমানোর চেষ্টা করুন। বিকল্পভাবে, অ্যাসিঙ্ক্রোনাসভাবে একটি ডাউনলোডযোগ্য রিপোর্ট ফাইল তৈরি করতে reports.run ব্যবহার করে একটি Report চালান।

কোয়েরি সীমা এবং সীমাবদ্ধতা

reportdata.query এন্ডপয়েন্টটি নির্ভরযোগ্য প্রতিক্রিয়া নিশ্চিত করতে বেশ কিছু সীমাবদ্ধতা আরোপ করে। যে অনুরোধগুলি এই সীমাবদ্ধতাগুলি লঙ্ঘন করে, সেগুলি HTTP 400 Bad Request প্রতিক্রিয়া সহ প্রত্যাখ্যান করা হয়।

তারিখের পরিসরের সীমা

• কাস্টম তারিখের পরিসরের জন্য, startDate অবশ্যই অনুরোধকৃত রিপোর্ট ডেটা টাইপের ডেটা প্রাপ্যতার সময়সীমার মধ্যে হতে হবে। বিস্তারিত জানতে, ডেটা প্রাপ্যতা দেখুন।

মেট্রিক এবং মাত্রিক সীমাবদ্ধতা

• metricNames এ অন্তত একটি মেট্রিক অবশ্যই প্রদান করতে হবে।
• metricNames এবং dimensionNames তালিকার মেট্রিক ও ডাইমেনশনগুলো অবশ্যই অনন্য হতে হবে।
• যেসব মেট্রিক ও ডাইমেনশনকে ‘শুধুমাত্র ডাউনলোড’ হিসেবে চিহ্নিত করা হয়েছে, সেগুলো এই কোয়েরিগুলোতে ব্যবহার করা যাবে না।

কোটার সীমা

এই এন্ডপয়েন্টে পাঠানো অনুরোধগুলো নিম্নলিখিত কোটা ব্যবহার করে:

• ব্যবহারকারীর হার সীমা: প্রতি ব্যবহারকারী প্রতি মিনিটে ১২০টি অনুরোধ (২ কিউপিএস)
• প্রতি প্রকল্পের জন্য দৈনিক সীমা: প্রতিদিন প্রতি প্রকল্পে ১০,০০০ অনুরোধ

এই সীমা অতিক্রমকারী অনুরোধগুলি HTTP 429 Too Many Requests ত্রুটির সাথে ব্যর্থ হয়। আপনি যদি পেজ ব্যবহার করে ফলাফলগুলি দেখেন, তাহলে ( pageToken প্যারামিটার ব্যবহার করে) প্রতিটি নতুন পেজের অনুরোধ একটি পৃথক কোয়েরি হিসাবে গণ্য হয় এবং এই কোটা থেকে ব্যবহৃত হয়।