دليل مطوِّر لغة طلب بحث الناشر (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 مع قوسَين. جارٍ تنفيذ طلب البحث "" (فارغ) string) كل شيء.

  أمثلة: 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 حيث يكون "أ" هو الحرف الأول) أو تنازلي (DESC حيث يكون "أ" هو الحرف الأخير). إذا لم يكن الاتجاه محددة، يتم تعيينها تلقائيًا على 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 يعادل العديد من طلبات البحث =، طلب واحد لكل قيمة، يتم ربطها معًا باستخدام "أو". يتم تحديد القيم كقائمة مفصولة بفواصل من القيم، ومحاطة بين قوسين: (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. يُرجى العلم أنّ جداول المطابقة هذه لا تحتوي على كلّ حقول الكيانات.
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='v202505')

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)