دليل مطوِّر لغة طلب بحث الناشر (PQL)

بنية PQL واستخدامها

PQL هي لغة تشبه SQL للاستعلام عن الكائنات. بناء جملة PQL هو تشبه لغة SQL، مع بعض الاختلافات الموضحة هنا. هذا القسم بناء جملة PQL وكيفية استخدامها لتصفية أنواع الكائنات المختلفة.

يمكن تلخيص بناء جملة 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>

ملاحظات

• لا تكون الكلمات الرئيسية لجودة المنتج (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 - لمقارنة قيمة خاصية بكل عنصر في list؛ إذا تطابق أي منها، فهذا يعني تطابقًا إيجابيًا. 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> - يمكنك استخدام Value بدلاً من القيمة <value> غير القابلة للتغيير القيم في استعلام PQL لديك. ربط في 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 Data Transfer Service: لاحظ أن جداول المطابقة هذه لا تحتوي على كل حقل من حقول العناصر.
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='v202408')

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)

# 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)
    

# 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)