Reminder: v201702 will be sunset on February 28, 2018.

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> - オブジェクトによって公開されるプロパティの 1 つです。各オブジェクトでは、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 でマッチテーブルを取得する

マッチテーブルは、データ転送ファイルに含まれる未処理の値を他の情報と対応付けるときに使用できる仕組みです。マッチテーブルを使用すると、広告配信情報(広告ユニット、広告申込情報など)と事前に割り当てられたデータベース内の値を対応付けることができます。

ReportService でレポートを作成している場合、またはデータ転送レポートを使用している場合、追加フィールドを使ってレポートデータを補いたいことがあります。たとえば、レポートに LINE_ITEM_ID ディメンションが含まれる場合、あるいはデータ転送イベントに LineItemId フィールドが含まれる場合に、各広告申込情報の開始日、終了日、タイプ、ステータス、その他の有用な属性を含むマッチテーブルを作成することができます。

この対応付け機能を設定するには、いくつかの方法があります。

  1. 効果的な方法としては、利用可能な PublisherQueryLanguageService テーブルの 1 つを使用します。
  2. クライアント ライブラリが対応している場合は、組み込みのユーティリティ機能を使って PQL テーブルにアクセスできます。下記の Python の例をご確認ください。
  3. 必要なエンティティの PQL テーブルがない場合は、そのエンティティのサービス(たとえばオーダーであれば OrderService)に直接アクセスします。

Python


  1. レポートクエリを設定します

    まずレポートジョブを作成し、レポートのパラメータ(ディメンション、表示項目、期間など)を指定します。

    # 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
        }
    }
        
  2. レポートをダウンロードします
    # Initialize a DataDownloader.
    report_downloader = client.GetDataDownloader(version='v201708')
    
    try:
      # Run the report and wait for it to finish.
      report_job_id = report_downloader.WaitForReport(report_job)
    except errors.DfpReportError, 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)
        
  3. 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)
        
  4. レポートデータと広告申込情報のデータを統合します

    次の例では、表形式のデータを比較的簡単に扱える pandas ライブラリを使用して、レポートデータを PQL データと統合し、1 つのマッチテーブルを作成しています。

    # 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)
        

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

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