パブリッシャークエリ言語（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>

メモ

  • PQL のキーワードでは、大文字と小文字は区別されません。
  • 文字列をバインド パラメータで使用すると、自動的にエスケープされます。それ以外の場合: <ph type="x-smartling-placeholder">
      </ph>

    • 単一引用符（アポストロフィ）で囲まれた文字列の場合は、 追加のアポストロフィを一対の一重引用符で囲んで記述します。

      例: "WHERE name = 'Company''s name'"

キーワード（大文字と小文字は区別されません）

  • WHERE - 0 個以上の条件のセットを表します。 必要に応じて 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 - 複数の条件を結合します。結合の対象となるのは 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いずれか 1 つでも一致する場合は、true 一致と見なされます。IN 演算子は、値ごとに 1 つずつ、多くの = クエリと同等です。 表示されます値は、カンマ区切りのリストとして指定します。 かっこで囲まれた値: (a, b, c)。リスト内のすべての値は、 評価します。

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

  • NOT IN - プロパティの値を各項目と比較します。 。一致するものがない場合、true 一致と見なされます。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 - 次を含むオブジェクトのクエリを実行できます。 未定義のプロパティ値。典型的な例は、BigQuery から 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 が用意している既製のマッチテーブルを <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='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 で表示
をご覧ください。