Publisher Query Language(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 キーワードでは大文字と小文字は区別されません。
  • バインド パラメータで使用される文字列は自動的にエスケープされます。他のケースでは次のようになります。
    • 一重引用符(アポストロフィ)で囲まれた文字列の中でアポストロフィを使う場合は、エスケープするために一重引用符を 2 つ続けて入力します。

      例: "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 - 複数の条件を結合します。いずれかが true であれば条件を満たしたことになります。1 つのプロパティで複数あるうちいずれかの値をチェックする場合は、IN 句を使用できます。

    例: WHERE width = 728 OR height = 90

  • AND - 複数の条件を結合します。すべてが true である場合にのみ条件を満たしたことになります。

    例: 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 クエリに対応しているプロパティをご確認ください。たとえば、フィルタリングに使用できるクリエイティブ プロパティには idnamewidthheight があります。
  • <value> - 文字列値は単一引用符(')で囲む必要があります。数値は引用符で囲んでも囲まなくてもかまいません。ワイルドカードはサポートされていません。
  • IN - プロパティの値をリスト内の各項目と比較します。いずれかが一致する場合に true となります。IN 演算子は、= クエリを値ごとに指定してそれらを OR で結合したものと同じ結果を生みます。値は、かっこで囲んだカンマ区切りリスト(例: (a, b, c))として指定します。リスト内のすべての値が評価されます。

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

  • NOT IN - プロパティの値をリスト内の各項目と比較します。一致するものがない場合に true となります。NOT IN 演算子の結果は、!= クエリを値ごとに指定してそれらを OR で結合した場合の結果と同じになります。値は、かっこで囲んだカンマ区切りリスト(例: (a, b, c))として指定します。リスト内のすべての値が評価されます。

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

  • LIKE - 文字列の部分一致やワイルドカード一致を使ってオブジェクトを検索できます。

    : WHERE name LIKE 'startswith%'

  • 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 two mapped parameters: id and status
    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 < '2012-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500");
    statement.setValues(values);

PQL でマッチテーブルを取得する

マッチテーブルは、データ転送ファイル内の値に対する名前と ID の対応表です。マッチテーブルを使用すると、広告配信情報(広告ユニット、広告申込情報など)と事前に割り当てられたデータベース内の値とを照合できます。たとえば、データ転送イベントで、ID 12345678 の広告申込情報が 01-6-2011 の 16:10:10 に配信されたことが記録されたとします。広告申込情報のマッチテーブルを使用すると、この広告申込情報の名前、開始日と終了日、その他の有用な属性を把握できます。

DFP API を使用すると、必要なフィールドとオブジェクトのみを含む独自のマッチテーブルのスクリプトを簡単に作成できます。Python マッチテーブルのスクリプト セットの例を以下に紹介します。各 DFP API のクライアント ライブラリでは、サービスごとの GetAllX の例もご覧いただけます。Python を使用しない場合は、これらの例をファイルやデータベースに出力するように書き換えて、同じニーズに対応できます。

Python


  1. 認証情報を設定する

    googleads.yaml ファイルのテンプレート フィールドに入力した後、DfpClient.LoadFromStorage() を呼び出して Client オブジェクトを初期化します。

      # Initialize client object.
      dfp_client = dfp.DfpClient.LoadFromStorage()
    
  2. DataDownloader オブジェクトを作成する
      # Initialize a report downloader.
      report_downloader = client.GetDataDownloader(version='v201705')
    
  3. クエリ ステートメントとファイル ハンドルを設定する

    クライアントをインスタンス化して Report Downloader を作成したら、マッチテーブルを書き込むファイル ハンドルと、フィルタの基準となるクエリ ステートメントを作成します。

      line_items_file = tempfile.NamedTemporaryFile(
          prefix='line_items_', suffix='.csv', mode='w', delete=False)
      ad_units_file = tempfile.NamedTemporaryFile(
          prefix='ad_units_', suffix='.csv', mode='w', delete=False)
    
      line_items_pql_query = ('SELECT Name, Id, Status FROM Line_Item ORDER BY Id '
                              'ASC')
      ad_units_pql_query = 'SELECT Name, Id FROM Ad_Unit ORDER BY Id ASC'
  4. クエリとファイル ハンドルを DownloadPqlResultToCsv に渡す
    
      # Downloads the response from PQL select statement to the specified file
      report_downloader.DownloadPqlResultToCsv(
          line_items_pql_query, line_items_file)
      report_downloader.DownloadPqlResultToCsv(
          ad_units_pql_query, ad_units_file)
    

フィードバックを送信...

Doubleclick for Publishers
Doubleclick for Publishers
ご不明な点がありましたら、Google のサポートページをご覧ください。