คู่มือนักพัฒนาซอฟต์แวร์สำหรับ 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>

สำคัญ: ReportService รองรับเฉพาะชุดย่อยของไวยากรณ์ PQL โปรดดูรายละเอียดในเอกสารประกอบ ReportQuery

Notes

• คีย์เวิร์ด PQL ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
• สตริงจะถูก Escape โดยอัตโนมัติเมื่อใช้ในพารามิเตอร์การเชื่อมโยง หรือไม่เช่นนั้น

  • สำหรับสตริงภายในเครื่องหมายคำพูดเดี่ยว (อะพอสทรอฟี) ให้หลีกเลี่ยงเครื่องหมายอะพอสทรอฟีเพิ่มเติมโดยเขียนเป็นเครื่องหมายคำพูดเดี่ยวคู่

    เช่น "WHERE name = 'Company''s name'"

คีย์เวิร์ด (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่)

• WHERE - แสดงชุดเงื่อนไขที่เป็น 0 ขึ้นไป จะรวมเข้าด้วยกันโดยใช้วลี "และ" หรือ "หรือ" หรือไม่ก็ได้ คุณจัดกลุ่มวลี 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 - เปรียบเทียบค่าของที่พักกับแต่ละรายการในลิสต์ หากค่าใดตรงกัน ถือเป็นการจับคู่แบบบวก โอเปอเรเตอร์ 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 - ให้คุณค้นหาออบเจ็กต์โดยใช้การจับคู่สตริงไวลด์การ์ด เครื่องหมายเปอร์เซ็นต์ (%) แทนอักขระศูนย์ 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

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)

ดาวน์โหลดข้อมูลจากตาราง PQL ของ Line_Item

คุณใช้ตาราง PQL ของ Line_Itemเพื่อจับคู่รายงานกับข้อมูลรายการโฆษณาเพิ่มเติมได้

# 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