パブリッシャークエリ言語（PQL）デベロッパー ガイド

PQL の構文と使用方法

PQL は、オブジェクトをクエリするための SQL に似た言語です。PQL の構文は SQL の構文と似ていますが、いくつかの違いがあります。このセクションでは、PQL 構文と、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 - 0 個以上の条件のセットを表します。必要に応じて AND フレーズや OR フレーズを使って結合することもできます。AND フレーズまたは OR フレーズを括弧で囲むことができます。クエリ ""（空の文字列）を実行すると、すべてが返されます。

  例: WHERE width = 728
WHERE width = 728 AND height = 90
WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

• OR - 複数の条件を結合し、そのうちの 1 つのみを true にする必要があります。1 つのプロパティに対して複数の値があるかどうかをチェックする場合は、IN 句の使用を検討してください。

  例: WHERE width = 728 OR height = 90

• AND - 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> を含めることもできます。

  例（どちらの例も同じ結果セットを返します）:
  WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
WHERE type = 'AGENCY' LIMIT 50,50

• OFFSET - 戻り値の開始位置を示す結果セットのオフセット。結果をページ分割するために使用します。

  例（結果 51 ～ 100 を返す）:
  WHERE type = 'AGENCY' LIMIT 50 OFFSET 50。

• <property> - オブジェクトによって公開されるプロパティの 1 つ。各オブジェクトは、PQL を使用してフィルタリングできるさまざまなプロパティを公開します。通常、オブジェクトでサポートされているすべてのプロパティをフィルタリングすることはできません。そのため、PQL クエリをサポートするプロパティについては、以下のリストをご覧ください。たとえば、フィルタ条件にできるクリエイティブ プロパティには id、name、width、height があります。
• <value> - 文字列値は単一引用符（'）で囲む必要があります。数値は引用符で囲んでも囲まなくてもかまいません。ワイルドカードはサポートされていません。
• IN - プロパティの値をリスト内の各項目と比較します。いずれかが一致すると、true となります。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 - ワイルドカード文字列の一致を使用してオブジェクトをクエリできます。パーセント記号（%）は、0、1、または複数の文字を表します。ペアを使用して、照合する検索文字列を囲みます。

  例: WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'

• IS NULL - プロパティ値が未定義のオブジェクトを検索できます。この典型的な例は、ルート AdUnit の照会です。親の ID が null の AdUnit を照会します。

  例: WHERE parentId IS NULL

• <bind variable> - PQL クエリでハードコードされた <value> 値の代わりに Value オブジェクトを使用できます。PQL では、:（コロン）で始まるスペースを含まない文字列名を使用してバインド変数を参照します。

  例（クエリを作成し、ハードコードされた id プロパティ値と status プロパティ値の代わりに 2 つの変数を入力する）:

  // 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 を介してレポートを実行する場合、または Data Transfer レポートを使用してレポートを実行する場合、追加のフィールドでレポートデータを補完できます。たとえば、ディメンション LINE_ITEM_ID を含むレポートや、データ移転イベント（LineItemId）を含むレポートでは、各広告申込情報の開始日、終了日、タイプ、ステータス、その他の有用な属性を含むマッチテーブルを作成できます。

この照合機能を実現するには、いくつかの方法があります。

1. BigQuery Data Transfer Service で提供されている既製のマッチテーブルを使用します。なお、これらのマッチテーブルには、すべてのエンティティ フィールドが含まれているわけではありません。
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)

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 で表示