AdWords クエリ言語(AWQL)

AWQL はほとんどの代表的な AdWords API サービスに対しクエリを実行する SQL と同様の言語です。query() メソッドのあるすべてのサービスで利用できます。

AWQL は SQL ベースの言語ですが、SQL のすべてのボキャブラリに対応しているわけではありません。主に省略されているのは JOIN および GROUP BY 句です。

各サービスでクエリを実行できるフィールドのリストについては、セレクタ フィールドをご覧ください。

また、レポートでも AWQL を使ってクエリを実行することができます。クエリを使えるフィールドの包括的なリストについてはレポートタイプをご覧ください。

サービスの呼び出しで AWQL を使用する

AWQL なら同じ呼び出しでも効率的にコーディングできます。たとえば次のコードは CampaignService.get() で使用できるセレクタです。

<serviceSelector>
    <fields>Id</fields>
    <fields>Name</fields>
    <predicates>
        <field>Status</field>
        <operator>EQUALS</operator>
        <values>ENABLED</values>
    </predicates>
    <ordering>
        <field>Name</field>
        <sortOrder>ASCENDING</sortOrder>
    </ordering>
    <paging>
        <startIndex>0</startIndex>
        <numberResults>50</numberResults>
    </paging>
</serviceSelector>

CampaignService.query() で使える同様の AWQL クエリ文字列なら次のようになります。

SELECT Id, Name
WHERE Status = 'ENABLED'
ORDER BY Name
DESC LIMIT 0,50

AWQL を使ったコードサンプルはこちらのクライアント ライブラリにあります。キャンペーンを取得するコードサンプルは次のリンクからご覧いただけます。

注意事項

  • リクエストの送信先のサービスでデータソースはすでに決まっているため FROM 句は必要ありません。
  • サービスの呼び出しで DURING 句は使用できませんが、レポートの呼び出しでは使用可能です。
  • WHERE などのキーワードは大文字と小文字を区別しませんが、Name などのフィールド(表示項目)名や ENABLED などのリテラルは大文字と小文字を区別します
  • IN および NOT_IN 演算子を WHERE 句で使用する場合、アイテム数は 10,000 が上限となります。

レポートで AWQL を使用する

AWQL はレポートでもよく使われます。レポートでは通常、POST パラメータの「__rdxml」で XML フラグメントを指定しますが、その代わりに次の 2 つのパラメータを指定します。

  1. "__rdquery": AWQL クエリ文字列を指定します。
  2. "__fmt": レポートのダウンロード形式を定義します。

例(POST 本文):

__rdquery=SELECT+Criteria+FROM+KEYWORDS_PERFORMANCE_REPORT+DURING+20150101,20150325&__fmt=CSV

レポートで AWQL を使用する場合は、使い方の違いにご注意ください。

  • クエリでは、次の例のように FROM 句でレポートタイプを指定する必要があります。

    SELECT Id, Criteria, AdGroupName **FROM KEYWORDS_PERFORMANCE_REPORT**

    なお、FROM はサービスの呼び出しでは使用できませんが、レポートのダウンロードでは必須となります。

  • レポートの期間はクエリの DURING 句で定義します。期間は次の 2 通りの方法で指定できます。

    1. 次のような通常の AWQL 構文で期間を指定する。

      SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING 20160101,20160325

    2. 次のように既定の期間を選択する。

      SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING LAST_7_DAYS

  • ALL_TIME を指定した場合のように、全期間のデータを取得するにはクエリで DURING 句を省略します。ただし、こうした省略ができるのはクエリの SELECT 句に DateWeek が含まれていない場合に限られます。

  • ORDER BYLIMIT(並べ替えとページ指定)はレポートでは使用できません。クエリにこうした句を設定するとエラーになります。
  • ゼロ インプレッションの行を省略するには WHERE Impressions > 0 条件を使用します。

正式な文法

AWQL の正式な文法は次のようになっています。

Statement        -> SelectClause FromClause1 WhereClause?
                                 DuringClause2 OrderByClause? LimitClause?
SelectClause     -> SELECT ColumnList
FromClause       -> FROM SourceName
WhereClause      -> WHERE ConditionList
DuringClause     -> DURING DateRange
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT StartIndex , PageSize

ConditionList    -> Condition (AND Condition)*
Condition        -> ColumnName Operator Value
Value            -> ValueLiteral | String | ValueLiteralList | StringList
Ordering         -> ColumnName (DESC | ASC)?
DateRange        -> DateRangeLiteral | Date,Date
ColumnList       -> ColumnName (, ColumnName)*
ColumnName       -> Literal
SourceName       -> Literal
StartIndex       -> Non-negative integer
PageSize         -> Non-negative integer

Operator         -> = | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
                    CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE |
                    CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL
String           -> StringSingleQ | StringDoubleQ
StringSingleQ    -> '(char)'
StringDoubleQ    -> "(char)"
StringList       -> [ String (, String)* ]
ValueLiteral     -> [a-zA-Z0-9_.]*
ValueLiteralList -> **[** ValueLiteral (, ValueLiteral)* **]**3
Literal          -> [a-zA-Z0-9_]*
DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | THIS_WEEK_SUN_TODAY | THIS_WEEK_MON_TODAY | LAST_WEEK |
                    LAST_14_DAYS | LAST_30_DAYS | LAST_BUSINESS_WEEK | LAST_WEEK_SUN_SAT | THIS_MONTH
Date             -> 8-digit integer: YYYYMMDD

注意事項

  • 1FROM はサービスの呼び出しでは使用できませんが、レポートのダウンロードでは必須となります。
  • 2 DURING はサービスの呼び出しでは省略可能です。レポートのダウンロードでは、リクエストの SELECT 句に DateWeek が含まれている場合は必須となります。
  • 3ValueLiteralList では角かっこ [ ] は必須です。それ以外の場所では、角かっこは範囲を示します。
  • ? は省略可能であることを示し、* は 1 つ以上であることを示します。
  • 順序は SELECT...FROM...WHERE...DURING...ORDER BY...LIMIT... となります。
  • すべてのキーワードで大文字と小文字が区別されます。
  • 列名とリテラルでは大文字と小文字を区別します。
  • 空白は関係ありません。
  • 二重引用符と一重引用符はどちらも文字列と見なされます。エスケープ シーケンスは \"\'\\ です。

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

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