發布商查詢語言 (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 說明文件。

附註

• 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：彙整多個條件，其中只有一個條件必須為 true。如要針對單一值檢查多個值 可以考慮使用 IN 子句。

  範例：WHERE width = 728 OR height = 90

• AND：使用 AND 子句連結多個必須全部滿足的條件。

  範例：WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')

• ORDER BY - 依 遞增 (「A」第一是 ASC) 或遞減 (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；您通常無法篩選 Search Ads 360 支援的所有屬性 物件，所以請查看下方清單，瞭解哪些屬性支援 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 父項 ID。

  範例：WHERE parentId IS NULL

• <bind variable> - 您可以使用 Value 物件來取代硬式編碼的 <value>值。繫結 在 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」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='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)

從 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 查看