Pages

2015年8月11日火曜日

DFPリファレンス日本語訳 4


PQLガイド



PQL 構文と使い方

PQL はSQLに似たクエリ用の言語です. 構文もSQLそっくりですが以下のような若干の違いがあります。
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>


Notes:
  • PQLキーワードは大文字小文字を区別しません。
  • Stringはバインド パラメータ内で記述されると自動的にエスケープされます。
  •  それを避けるためには
    • '(シングル)と一緒に使用したい場合には、' (シングル)で挟みます。
      • Example: "WHERE name = 'Company''s name'"
    • ”も同様です
      • Example: 'WHERE name = "The ""all-time best"" Company"'
PQLキーワード (大文字小文字は区別しない)
  • WHERE - 0or1つ以上の条件を指定します。AND と ORが使え、()により優先順位を指定できます。 ""(空文字)を指定すると、無条件となります。
    • 例: WHERE width = 728 ;   WHERE width = 728 AND height = 90 ;  WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)
  • OR - そのまま
    • 例: WHERE width = 728 OR height = 90
  • AND - 指定する複数の条件を満たす場合
    • 例: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')
  • ORDER BY - 並び替えを行います。(ASC where 'A' から順に) (DESC where 'A' が最後 )order.無指定のデフォルはASC.
    • 例: WHERE id IN (5008, 8745, 3487) ORDER BY id
  • LIMIT - 取得データ数の上限.<offset>,を含めることができる。
    •  (結果は同じ): WHERE type = 'AGENCY' LIMIT 50 OFFSET 50 ;   WHERE type = 'AGENCY' LIMIT 50,50
  • OFFSET - ページをめくるように、開始時からの取得数を指定
    • Example ( 51-100を返す): WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.
  • <property> - 各オブジェクトが公開している各々のプロパティを指定できます。プロパティはオブジェクトにより異なります。後述のリストを参照してください。 例えば、creative のプロパティはid,namewidth,  height.のみが公開されます。
  • <value> - String は' か"で挟みます。数字はどちらでも構いません。ワイルドカードはサポートされていません。
  • IN - リスト内のプロパティを比較します。どれか1つが合致すれ条件に合致します。別の見方をすれば、たくさんの= 条件がorで連結されているのと同じです。()内でコンマで区切りリストを作成し、内のすべてが評価されます。
    •  WHERE name IN ('CompanyNameA', 'CompanyNameB')
  • NOT IN - リスト内のどれにも合致しない場合が条件に合致する。これは、 たくさんの!= が orで連結されているのと同じです。 
    •  WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')
  • LIKE - ワイルドカードや一部指定のように使う
    •  WHERE name LIKE 'startswith%'
  • IS NULL - 未定義のオブジェクトを指定可能にします。例えば、parentIDがnullのオブジェクトを指定することでルートとなるAdUnit を取得できます。
    • WHERE parentId IS NULL.
  • <bind variable> - PQLで定数を定義でき、 : (コロン)の後に続けてスペース無しで名前を指定しすることで参照されます。                                    (Creates a query and enters two variables in place of hard-coded id and status property values):
    // 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 fields - バインドパラメーターに日時を指定できます。 ISO 8601準拠のStringフォーマットを使用します。.
    // 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 startDatetTime > :startDateTime LIMIT 500");
    statement.setValues(values);

移行ガイド: PQL 内でGeo Targetsを使用

Original Geo TableChanges
Country(国)CurrencyCode(通貨コード)は廃止 
Region(地域)RegionCode no longer exists in the combined Geo_Target table. CountryCode and CountryName can be pulled via the relationship found through the ParentIds column. What were formerly classified as Regions are listed as more granular sub-types of 'States,' 'Prefectures,' 'Provinces,' 'Cantons,' and so on.
MetroMetros map to DMA_Regions. MetroCode no longer exists in the combined Geo_Target table.
CityMetroCode, RegionCode, and CountryCode no longer exist in the combined Geo_Target table. CountryCode, CountryName, RegionCode, RegionName, MetroCode, and MetroName can be pulled via the relationship found through the ParentIds column. What were formerly classified as Cities are listed as more granular sub-types of 'Municipalities,' 'Airports,' 'Counties,' and so on.
Postal_CodeCountryCode can be pulled via the relationship found through the ParentIds column.
対象地区はまだまだ拡張をしている段階で、you will probably find new entries within the older tables that might not fit that categorization. For example, airports are far more granular than our smallest unit defined, so they'll appear in the City table. This means that while using the specific geo tables will still yield all the same object ids, they will likely be poorly classified with the new set of targetable locations.
The migration of targetable locations should be quite straightforward. If you are pulling down the various tables locally, then there should already be a simple Id/Name mapping available. You can subsequently do a one time update to look at Geo_Target table, querying the same Id field to fetch the new fields of Type / Country Code / Parent Ids. You will, in some cases, notice multiple Geo_Targets with the same name, these are not duplicates, but rather targetable location objects that exist at different type-levels, some cities share names with regions for example. To maintain the behavior currently existing with the legacy tables, matching on ids to build a new list of geo targets should yield the closest level of type approximation from the new Geo_Target table.
To replicate the parent object fields in each of the deprecated legacy tables, you can now build these columns for each respective type by using the ParentIds column. This list of ParentIds will allow you to then query for the parent geo_targets, each of which would yield a name and id.
A best practice suggestion would be to keep a singular mapping of geo_targets locally instead of having a table for each type as we might add new sub-types in the future.

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

マッチテーブルはdata 転送ファイル内の値で name-to-IDの参照を提供し、 ad unit や line itemなどの広告配信情報とのマッチングを可能にします。例えば、For example, a データ転送イベントが、ID 12345678の  line item が 01-6-2011 at 16:10:10に配信されたことを記録した場合、The line item match table lets you know the name of that line item, as well as its start date, end date, and other useful attributes.
You can easily create your own match table scripts that include only the fields and range of objects you need using the DFP API. An example set of Python match table scripts follows. Additionally, each of the DFP API client libraries have examples of GetAllX for each service that can be adjusted to output to files or databases to fulfill this need if you aren't using Python.


  1. 証明書のセットアップ
    Populate the templated fields in the googleads.yaml file, then callDfpClient.LoadFromStorage() to initialize the Client object.
      #  クライアントの初期化
      dfp_client = dfp.DfpClient.LoadFromStorage()
  2. DataDownloaderのコンストラクト
      #  レポートダウンローダの初期化
      report_downloader = client.GetDataDownloader(version='v201505')
  3. Set up your query statements and file handles
      create the file handles to write your match tables to as well as the query statements to filter on.
      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にクエリとファイルの扱いを渡す
      # 指定ファイルにPQL でダウンロード
      report_downloader.DownloadPqlResultToCsv(
          line_items_pql_query, line_items_file)
      report_downloader.DownloadPqlResultToCsv(
          ad_units_pql_query, ad_units_file)

0 コメント:

コメントを投稿