دليل مطوِّر لغة طلب بحث الناشر (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>

Notes

  • الكلمات الرئيسية PQL ليست حساسة لحالة الأحرف.
  • يتم تخطي السلاسل تلقائيًا عند استخدامها في معلَمات الربط. وفي حال عدم حدوث ذلك:
    • بالنسبة إلى سلسلة ضمن علامات اقتباس مفردة (فواصل عليا)، يمكنك إلغاء أي فاصلة عليا إضافية من خلال كتابتها كزوج من علامتي الاقتباس المفردتين.

      مثال: "WHERE name = 'Company''s name'"

الكلمات الرئيسية (غير الحساسة لحالة الأحرف)

  • WHERE - يعبّر عن مجموعة من شروط أو صفر أو أكثر، ويتم دمجه اختياريًا باستخدام عبارات "و" أو "أو". يمكنك تجميع عبارات 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> - يمكنك استخدام كائنات 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.

Python

إعداد طلب بحث في التقرير

ابدأ بإنشاء مهمة تقرير، مع تحديد معلمات التقرير مثل الأبعاد والأعمدة والنطاق الزمني.

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

تنزيل البيانات من جدول Line_Item PQL

لمطابقة تقريرك مع بيانات العنصر الإضافية، يمكنك استخدام جدول Line_Item 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)
    

ربط بيانات التقرير ببيانات العناصر

يستخدم هذا المثال مكتبة pandas لأنّها تجعل التعامل مع البيانات الجدولية أسهل كثيرًا. هنا، يُستخدم لدمج بيانات التقرير مع بيانات 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)
العرض على GitHub