คู่มือนักพัฒนาซอฟต์แวร์สำหรับ 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 ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
ระบบจะกำหนดสตริงเป็นอักขระหลีกโดยอัตโนมัติเมื่อใช้ในการเชื่อมโยงพารามิเตอร์ กรณีอื่น
- สำหรับสตริงภายในเครื่องหมายคำพูดเดี่ยว (อะพอสทรอฟี) ให้ Escape ใดก็ได้ เครื่องหมายอัญประกาศเดี่ยวเพิ่มเติมโดยเขียนเป็นเครื่องหมายอัญประกาศเดี่ยว
  เช่น "WHERE name = 'Company''s name'"

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

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

ฟังก์ชันการจับคู่นี้ทำได้หลายวิธี ดังนี้

ใช้ตารางการจับคู่ที่สร้างไว้ล่วงหน้าจาก บริการโอนข้อมูล BigQuery โปรดทราบว่าตารางที่ตรงกันเหล่านี้ไม่มีช่องเอนทิตีทุกช่อง
วิธีที่มีประสิทธิภาพคือการใช้ PublisherQueryLanguageService ตาราง
หากไม่มีตาราง 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='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)

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

คุณสามารถใช้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