パブリッシャークエリ言語（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 - 複数の条件を結合し、そのすべてが条件と一致する 満足する結果が得られます

  例: 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> - 渡されます。各オブジェクトは、フィルタ条件として使用できるさまざまなプロパティをエクスポーズします。 PQL を使用します。通常は、サポートされているすべての そのため、PQL クエリに対応しているプロパティについては、以下のリストをご確認ください。 たとえば、フィルタできるクリエイティブ プロパティには、id、name、width、height などがあります。
• <value> - 文字列値は単一引用符（'）で囲む必要があります。数値は引用符で囲むことも、引用符で囲まなくてもかまいません。ワイルドカード はサポートされていません。
• IN - プロパティの値を list;いずれかが一致すると、true となります。IN 演算子は、複数の = クエリ（1 つの値に 1 クエリ）の論理和と同等です。値は、カンマ区切りのリストとして指定します。 かっこで囲まれた値: (a, b, c)。リスト内のすべての値が評価されます。

  例: WHERE name IN ('CompanyNameA', 'CompanyNameB')

• NOT IN - プロパティの値をリスト内の各項目と比較します。一致するものがない場合、一致と見なされます。NOT IN 演算子は、値ごとに 1 つずつ、つまり多数の != クエリと同等です。 表示されます値は、カンマ区切りのリストとして指定します。 かっこで囲まれた値: (a, b, c)。リスト内のすべての値は、 評価します。

  例: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

• LIKE - ワイルドカード文字列照合を使用してオブジェクトをクエリできます。パーセント記号（%）は、0、1、複数の文字を表します。一致する検索文字列をペアで囲みます。

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

• IS NULL - 未定義のプロパティ値を持つオブジェクトをクエリできます。典型的な例は、親 ID が 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 または Data Transfer を使用 レポートについては、レポートデータに追加の 表示されます。たとえば、ディメンション LINE_ITEM_ID を含むレポートや、フィールド LineItemId を含むデータ転送イベントを使用すると、各項目の開始日、終了日、タイプ、ステータスなどの有用な属性を含む一致テーブルを作成できます。

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

1. Google Cloud で提供される既製のマッチテーブルを <ph type="x-smartling-placeholder"></ph> 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='v202508')

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