প্রকাশক ক্যোয়ারী ল্যাঙ্গুয়েজ (PQL) বিকাশকারীর নির্দেশিকা

PQL সিনট্যাক্স এবং ব্যবহার

পিকিউএল হল একটি এসকিউএল-এর মতো ভাষা যা বস্তু অনুসন্ধানের জন্য। PQL সিনট্যাক্স SQL এর অনুরূপ, এখানে বর্ণিত কয়েকটি পার্থক্য সহ। এই বিভাগে PQL সিনট্যাক্স এবং বিভিন্ন অবজেক্ট টাইপ ফিল্টার করার জন্য কীভাবে এটি ব্যবহার করতে হয় তা বর্ণনা করে।

পিকিউএল সিনট্যাক্সকে নিম্নরূপ সংক্ষিপ্ত করা যেতে পারে:

[WHERE <condition> {[AND | OR] <condition> ...}]
[ORDER BY <property> [ASC | DESC]]
[LIMIT {[<offset>,] <count>} | {<count> OFFSET <offset>}]

<condition> := <property> { = | != } <value>
<condition> := <property> { = | != } <bind variable>
<condition> := <property> IN <list>
<condition> := NOT <property> IN <list>
<condition> := <property> LIKE <wildcard%match>
<condition> := <property> IS NULL
<bind variable> := :<name>

গুরুত্বপূর্ণ: ReportService শুধুমাত্র PQL সিনট্যাক্সের একটি উপসেট সমর্থন করে। বিস্তারিত জানার জন্য ReportQuery ডকুমেন্টেশন দেখুন।

মন্তব্য

• PQL কীওয়ার্ডগুলি কেস সংবেদনশীল নয়।
• বাইন্ড প্যারামিটারে ব্যবহৃত হলে স্ট্রিং স্বয়ংক্রিয়ভাবে এস্কেপ হয়। অন্যথায়:

  • একক উদ্ধৃতি (অ্যাপোস্ট্রোফিস) এর মধ্যে একটি স্ট্রিংয়ের জন্য, এটিকে একক উদ্ধৃতিগুলির একটি জোড়া হিসাবে লিখে যেকোন অতিরিক্ত অ্যাপোস্ট্রফিকে এড়িয়ে যান।

    উদাহরণ: "WHERE name = 'Company''s name'"

কীওয়ার্ড (কেস-সংবেদনশীল)

• WHERE - শূন্য বা ততোধিক শর্তের একটি সেট প্রকাশ করে, ঐচ্ছিকভাবে AND বা OR বাক্যাংশ ব্যবহার করে যুক্ত হয়। আপনি বন্ধনী সহ AND বা OR বাক্যাংশগুলিকে বান্ডিল করতে পারেন৷ "" (খালি স্ট্রিং) ক্যোয়ারী নির্বাহ করলে সবকিছু ফেরত আসে।

  উদাহরণ: WHERE width = 728
WHERE width = 728 AND height = 90
WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

• OR - একাধিক শর্তে যোগ দেয়, যার মধ্যে শুধুমাত্র একটি সত্য হতে হবে। আপনি যদি একটি একক সম্পত্তির জন্য একাধিক মান পরীক্ষা করতে চান তবে একটি IN ধারা ব্যবহার করার কথা বিবেচনা করুন।

  উদাহরণ: WHERE width = 728 OR height = 90

• AND - একাধিক শর্তে যোগ দেয় যেগুলিকে অবশ্যই AND ধারা ব্যবহার করে সন্তুষ্ট হতে হবে।

  উদাহরণ: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')

• ORDER BY - প্রত্যাবর্তিত ফলাফলগুলিকে হয় ক্রমবর্ধমান ( ASC যেখানে 'A' প্রথমে) বা অবরোহ ( DESC যেখানে 'A' শেষ) ক্রমে সাজায়। দিকনির্দেশ নির্দিষ্ট না হলে, এটি ASC তে ডিফল্ট হয়। যদি এই ধারাটি অন্তর্ভুক্ত না করা হয় তবে ডিফল্ট প্রথম ক্ষেত্রে ASC হয়।

  উদাহরণ: WHERE id IN (5008, 8745, 3487) ORDER BY id

• LIMIT - ফলাফলের সংখ্যা ফেরত দিতে হবে। LIMIT একটি <offset> ও অন্তর্ভুক্ত থাকতে পারে, যা হল আপনার ফলাফল সেট অফসেট করার জন্য শুরু থেকে কতগুলি সারি।

  উদাহরণ (উভয় উদাহরণ একই ফলাফল সেট প্রদান করে):
  WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
WHERE type = 'AGENCY' LIMIT 50,50

• OFFSET - ফলাফলের অফসেট মান ফেরাতে শুরু করবে। ফলাফলের মাধ্যমে পৃষ্ঠাতে এটি ব্যবহার করুন।

  উদাহরণ (ফলাফল 51-100 প্রদান করে):
  WHERE type = 'AGENCY' LIMIT 50 OFFSET 50 ।

• <property> - বস্তু দ্বারা উন্মুক্ত বৈশিষ্ট্যগুলির মধ্যে একটি। প্রতিটি বস্তু বিভিন্ন বৈশিষ্ট্য প্রকাশ করে যা আপনি PQL ব্যবহার করে ফিল্টার করতে পারেন; আপনি সাধারণত একটি বস্তু দ্বারা সমর্থিত সমস্ত বৈশিষ্ট্য ফিল্টার করতে পারবেন না, তাই কোন বৈশিষ্ট্যগুলি PQL প্রশ্নগুলি সমর্থন করে তা দেখতে নীচের তালিকাটি দেখুন৷ উদাহরণ স্বরূপ, আপনি যে সৃজনশীল বৈশিষ্ট্যগুলি দিয়ে ফিল্টার করতে পারেন তাতে id , name , width এবং height অন্তর্ভুক্ত রয়েছে।
• <value> - স্ট্রিং মান একটি একক (') উদ্ধৃতি চিহ্ন দিয়ে উদ্ধৃত করা উচিত। সংখ্যার মান উদ্ধৃত বা উদ্ধৃত করা যেতে পারে। ওয়াইল্ডকার্ড সমর্থিত নয়।
• IN - একটি তালিকার প্রতিটি আইটেমের সাথে একটি সম্পত্তির মান তুলনা করে; যদি কোনো একটি মিলে যায়, এটি একটি ইতিবাচক ম্যাচ। IN অপারেটরটি অনেকগুলি = প্রশ্নগুলির সমতুল্য, প্রতিটি মানের জন্য একটি, যা একসাথে OR করা হয়৷ মানগুলিকে কমা দ্বারা পৃথক করা মানগুলির তালিকা হিসাবে নির্দিষ্ট করা হয়েছে, বন্ধনীতে আবদ্ধ: (a, b, c)। তালিকার সমস্ত মান মূল্যায়ন করা হয়।

  উদাহরণ: WHERE name IN ('CompanyNameA', 'CompanyNameB')

• NOT IN - একটি তালিকার প্রতিটি আইটেমের সাথে একটি সম্পত্তির মান তুলনা করে; যদি কোনটি মেলে না, এটি একটি ইতিবাচক মিল। NOT IN অপারেটরটি অনেকের সমতুল্য != প্রশ্ন, প্রতিটি মানের জন্য একটি, যা একসাথে OR করা হয়। মানগুলিকে কমা দ্বারা পৃথক করা মানগুলির তালিকা হিসাবে নির্দিষ্ট করা হয়েছে, বন্ধনীতে আবদ্ধ: (a, b, c)। তালিকার সমস্ত মান মূল্যায়ন করা হয়।

  উদাহরণ: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

• LIKE - ওয়াইল্ডকার্ড স্ট্রিং ম্যাচিং ব্যবহার করে বস্তুর জন্য অনুসন্ধান করতে আপনাকে সক্ষম করে। শতাংশ চিহ্ন ( % ) শূন্য, এক বা একাধিক অক্ষর উপস্থাপন করে। মিলিত অনুসন্ধান স্ট্রিং ঘেরাও করতে একটি জোড়া ব্যবহার করুন.

  উদাহরণ: WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'

• IS NULL - আপনাকে একটি অনির্ধারিত সম্পত্তি মান সহ বস্তুর জন্য অনুসন্ধান করতে সক্ষম করে। এর ক্লাসিক উদাহরণ হল একটি নাল প্যারেন্ট আইডি সহ একটি AdUnit এর জন্য অনুসন্ধান করে রুট AdUnit এর জন্য অনুসন্ধান করা।

  উদাহরণ: WHERE parentId IS NULL ।

• <bind variable> - আপনি আপনার PQL ক্যোয়ারীতে হার্ড-কোডেড <value> মানের জায়গায় Value অবজেক্ট ব্যবহার করতে পারেন। একটি বাইন্ড ভেরিয়েবলকে PQL এ স্পেস ছাড়া একটি স্ট্রিং নাম ব্যবহার করে উল্লেখ করা হয়, একটি : (কোলন) দিয়ে শুরু হয়।

  উদাহরণ (একটি ক্যোয়ারী তৈরি করে এবং হার্ড-কোডেড id এবং status সম্পত্তি মানগুলির জায়গায় দুটি ভেরিয়েবল প্রবেশ করায়):

  // Create two mapped parameters: id and status
  String_ValueMapEntry[] values = new String_ValueMapEntry[2];
  values[0] = new String_ValueMapEntry("id", new NumberValue(null, "123"));
  values[1] = new String_ValueMapEntry("status", new TextValue(null, "APPROVED"));
  
  // Create our statement and map our bind variables
  Statement statement = new Statement();
  statement.setQuery("WHERE id = :id AND status = :status LIMIT 500");
  statement.setValues(values);

• DateTime ক্ষেত্র - আপনি একটি বাঁধাই ভেরিয়েবলের জন্য একটি DateTime মান নির্ধারণ করে বা ISO 8601 অনুযায়ী ফর্ম্যাট করা একটি স্ট্রিং ব্যবহার করে তারিখ এবং সময় দ্বারা ফিল্টার করতে পারেন

  // Create a bind variable: startDateTime
  String_ValueMapEntry[] values = new String_ValueMapEntry[1];
  values[0] = new String_ValueMapEntry("startDateTime", new DateTimeValue(null, dateTime));
  
  // Create our statement and map our bind variables
  Statement statement = new Statement();
  statement.setQuery("WHERE endDateTime < '2019-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500");
  statement.setValues(values);

PQL এর সাথে ম্যাচ টেবিল আনা হচ্ছে

ম্যাচ টেবিল ডেটা ট্রান্সফার ফাইলের মধ্যে থাকা কাঁচা মানগুলির জন্য একটি লুকআপ প্রক্রিয়া প্রদান করে, যা আপনাকে বিজ্ঞাপন পরিবেশন তথ্য (যেমন বিজ্ঞাপন ইউনিট বা লাইন আইটেম) ডাটাবেসে সংরক্ষিত প্রাক-অর্পণ করা মানগুলির সাথে মেলাতে দেয়।

আপনি যদি ReportService বা ডেটা ট্রান্সফার রিপোর্টের মাধ্যমে রিপোর্ট চালান, তাহলে আপনি অতিরিক্ত ক্ষেত্রগুলির সাথে আপনার রিপোর্ট ডেটার পরিপূরক করতে চাইতে পারেন। উদাহরণ স্বরূপ, LINE_ITEM_ID মাত্রা আছে এমন একটি প্রতিবেদনের সাথে বা একটি ডেটা স্থানান্তর ইভেন্টের সাথে যেখানে LineItemId ফিল্ড রয়েছে, আপনি একটি মিল টেবিল তৈরি করতে পারেন যাতে প্রতিটি লাইন আইটেমের শুরুর তারিখ, সমাপ্তির তারিখ, প্রকার, স্থিতি এবং অন্যান্য দরকারী বৈশিষ্ট্যগুলি অন্তর্ভুক্ত থাকে৷

এই মিলিত কার্যকারিতা সম্পন্ন করার বিভিন্ন উপায় আছে:

1. BigQuery ডেটা ট্রান্সফার পরিষেবা দ্বারা প্রদত্ত প্রিমমেড ম্যাচ টেবিলগুলি ব্যবহার করুন৷ মনে রাখবেন এই মিল টেবিলে প্রতিটি সত্তা ক্ষেত্র থাকে না।
2. একটি কার্যকর পদ্ধতি হল উপলব্ধ PublisherQueryLanguageService টেবিলের যেকোনো একটি ব্যবহার করা।
3. যদি সত্তার জন্য কোন BigQuery বা PQL টেবিল না থাকে বা টেবিলে আপনার প্রয়োজনীয় ফিল্ড অনুপস্থিত থাকে, তাহলে আপনি সরাসরি সেই সত্তার পরিষেবার মাধ্যমে যেতে পারেন, যেমন OrderService ।

পাইথন

একটি রিপোর্ট ক্যোয়ারী সেট আপ করুন

একটি রিপোর্ট কাজ তৈরি করে শুরু করুন, আপনার রিপোর্টের প্যারামিটার যেমন মাত্রা, কলাম এবং তারিখ পরিসীমা নির্দিষ্ট করে।

# Set the start and end dates of the report to run (past 8 days).
end_date = date.today()
start_date = end_date - timedelta(days=8)

# Create report job.
report_job = {
    'reportQuery': {
        'dimensions': ['LINE_ITEM_ID', 'LINE_ITEM_NAME'],
        'columns': ['AD_SERVER_IMPRESSIONS', 'AD_SERVER_CLICKS',
                    'AD_SERVER_CTR', 'AD_SERVER_CPM_AND_CPC_REVENUE',
                    'AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM'],
        'dateRangeType': 'CUSTOM_DATE',
        'startDate': start_date,
        'endDate': end_date
    }
}

প্রতিবেদনটি ডাউনলোড করুন

# Initialize a DataDownloader.
report_downloader = client.GetDataDownloader(version='v202402')

try:
  # Run the report and wait for it to finish.
  report_job_id = report_downloader.WaitForReport(report_job)
except errors.AdManagerReportError as e:
  print('Failed to generate report. Error was: %s' % e)

with tempfile.NamedTemporaryFile(
    suffix='.csv.gz', mode='wb', delete=False) as report_file:
  # Download report data.
  report_downloader.DownloadReportToFile(
      report_job_id, 'CSV_DUMP', report_file)

লাইন_আইটেম পিকিউএল টেবিল থেকে ডেটা ডাউনলোড করুন

অতিরিক্ত লাইন আইটেম ডেটার সাথে আপনার প্রতিবেদনের মিল করতে, আপনি লাইন_আইটেম PQL টেবিল ব্যবহার করতে পারেন।

# Create a PQL query to fetch the line item data
line_items_pql_query = ('SELECT Id, LineItemType, Status FROM LineItem')

# Download the response from PQL select statement
line_items = report_downloader.DownloadPqlResultToList(line_items_pql_query)
    

লাইন আইটেম ডেটা সহ রিপোর্ট ডেটাতে যোগ দিন

এই উদাহরণটি পান্ডাস লাইব্রেরি ব্যবহার করে কারণ এটি ট্যাবুলার ডেটার সাথে কাজ করা অনেক সহজ করে তোলে। এখানে, এটি একটি ম্যাচ টেবিল তৈরি করতে PQL ডেটার সাথে রিপোর্ট ডেটা যোগ করতে ব্যবহৃত হয়।

# Use pandas to join the two csv files into a match table
report = pandas.read_csv(report_file.name)
line_items = pandas.DataFrame(data=line_items[1:], columns=line_items[0])
merged_result = pandas.merge(report, line_items,
                             left_on='Dimension.LINE_ITEM_ID', right_on='id')
merged_result.to_csv('~/complete_line_items_report.csv', index=False)

গিটহাবে দেখুন