發布商查詢語言 (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 - 加入多個條件，只需要加入其中一個條件 正確。如要針對單一值檢查多個值 可以考慮使用 IN 子句。

    範例：WHERE width = 728 OR height = 90

  • 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> - 向 Deployment 中 物件。每個物件都會顯示不同的屬性，您可以依據 使用 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='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)

下載 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 查看