คู่มือนักพัฒนาซอฟต์แวร์สำหรับ Publisher Query Language (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 - ผนวกหลายเงื่อนไขต้องตรงตามเงื่อนไขทั้งหมด พึงพอใจกับการใช้วรรคและ

  เช่น 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> ด้วย ซึ่งระบุจํานวนแถวจากจุดเริ่มต้นที่จะลบล้างชุดผลลัพธ์

  ตัวอย่าง (ทั้ง 2 ตัวอย่างแสดงชุดผลลัพธ์เดียวกัน)
  
  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 จะเทียบเท่ากับคำค้นหา = จำนวนมาก โดยใช้ 1 คำสำหรับแต่ละค่า ที่ใช้ OR ร่วมกัน ค่าจะระบุเป็นรายการค่าที่คั่นด้วยคอมมาโดยใส่ไว้ในวงเล็บ เช่น (a, b, c) ระบบจะประเมินค่าทั้งหมดในรายการ

  เช่น WHERE name IN ('CompanyNameA', 'CompanyNameB')

• NOT IN - เปรียบเทียบค่าของพร็อพเพอร์ตี้กับแต่ละรายการในรายการ หากไม่ตรงกัน แสดงว่าตรงกัน โอเปอเรเตอร์ NOT IN จะมีค่าเท่ากับการค้นหา != หลายรายการ โดยแต่ละรายการจะมีค่า 1 ค่า ซึ่งใช้ OR ร่วมกัน ค่าจะระบุเป็นรายการค่าที่คั่นด้วยคอมมาโดยใส่ไว้ในวงเล็บ (a, b, c) ระบบจะประเมินค่าทั้งหมดในรายการ

  เช่น WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

• LIKE - ให้คุณค้นหาออบเจ็กต์ได้โดยใช้การจับคู่สตริงที่เป็นไวลด์การ์ด เครื่องหมายเปอร์เซ็นต์ (%) หมายถึงศูนย์ 1 หรือ มีอักขระหลายตัว ใช้คู่เพื่อจับคู่สตริงการค้นหาที่ตรงกัน

  ตัวอย่าง: WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'

• IS NULL - ช่วยให้คุณสามารถค้นหาออบเจ็กต์ที่มี ที่ไม่ได้กำหนด ตัวอย่างคลาสสิกของกรณีนี้คือการค้นหา รูท AdUnit จากการค้นหา AdUnit ที่มีค่าว่าง รหัสระดับบนสุด

  เช่น WHERE parentId IS NULL

• <bind variable> - คุณสามารถใช้ออบเจ็กต์ Valueแทนค่า <value> ที่กำหนดไว้ล่วงหน้าในการค้นหา PQL การเชื่อมโยง จะมีการอ้างถึงตัวแปรใน PQL โดยใช้ชื่อสตริงที่ไม่มีช่องว่าง โดยเริ่มต้น ด้วย : (โคลอน)

  ตัวอย่าง (สร้างคำค้นหาและป้อนตัวแปร 2 ตัวแทนที่ พร็อพเพอร์ตี้ 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)