發布商查詢語言 (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 詞組合併。執行查詢 "" (空白) 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 查詢。 舉例來說,您可以篩選的廣告素材屬性包括 idnamewidthheight
  • <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 中使用不含空格的字串名稱, 開頭為 : (冒號)。

    範例 (建立查詢,並輸入兩個變數,取代硬式編碼的 idstatus 屬性值):

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