Pages

Blogger news

2015年8月11日火曜日

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

レポートの基礎




はじめに

このガイドでは、レポートのクエリ作成についてをカバーします。レポート処理を動かし、完成したレポートをダウンロードします。

事前の準備

  • 製品版のDFPネットワークにアクセスする
  • DFPのクライアントライブラリ

入門

IDFPのレポートについて詳しくないのであれば、 この記事でどのようにDFPのレポートをUIで表示するのかを学んでください。UIは、ツールチップによりどのカラムとレポートのプレビューを持ちます。複雑なレポートを作成するときには、APIで作成する前にUIでテストすると簡単です。

レポートクエリの作成

 ReportQueryオブジェクトは、レポートの詳細すべてを持ちます。  ここに、レポートのdimensions(範囲), dimension attributes(範囲アトリビュート), カラム, フィルター と取得期間をセットします。 以下のコードは単一のオーダーで返される基本的なレポートを表示します。


    // クエリの作成
    ReportQuery reportQuery = new ReportQuery();
    reportQuery.setDimensions(new Dimension[] {Dimension.DATE, Dimension.ORDER_ID});
    reportQuery.setColumns(new Column[] {Column.AD_SERVER_IMPRESSIONS,
        Column.AD_SERVER_CLICKS, Column.AD_SERVER_CTR,
        Column.AD_SERVER_CPM_AND_CPC_REVENUE});
    reportQuery.setDimensionAttributes(new DimensionAttribute[] {
        DimensionAttribute.ORDER_TRAFFICKER, DimensionAttribute.ORDER_START_DATE_TIME,
        DimensionAttribute.ORDER_END_DATE_TIME});

    // 要求データを絞り込むための宣言の作成
    StatementBuilder statementBuilder = new StatementBuilder()
        .where("ORDER_ID = :orderId")
        .withBindVariableValue("orderId", orderId);

    // 宣言をセット
    reportQuery.setStatement(statementBuilder.toStatement());

    // 開始と終了日時のセット、または、ダイナミックな期間の設定
    reportQuery.setDateRangeType(DateRangeType.CUSTOM_DATE);
    reportQuery.setStartDate(
        DateTimes.toDateTime("2013-05-01T00:00:00", "America/New_York").getDate());
    reportQuery.setEndDate(
        DateTimes.toDateTime("2013-05-31T00:00:00", "America/New_York").getDate());
    

レポート処理の作成

レポートクエリを取得したら、いよいよレポートを処理しましょう。 ReportJobオブジェクトはレポートの状態を持ち、ダウンロード可能になったことを教えてくれます。 そのときには、ReportService.runReportJob メソッドによりレポート処理を走らせます。


    // レポート処理の作成
    ReportJob reportJob = new ReportJob();
    reportJob.setReportQuery(reportQuery);

    // 処理を走らせる
    reportJob = reportService.runReportJob(reportJob);
    

レポートをダウンロード

開始されたレポート処理は、サーバによりIDを付与されます。このIDを、ReportService.getReportJobで使用し、レポートの状態を取得しましょう。

この状態が、 ReportJobStatus.COMPLETEDになればダウンロード準備が整ったことになります。

レポートは様々なフォーマットでダウンロードすることができます。取得したレポートをさらに加工したい場合には、CSV_DUMPフォーマットを選択してください。


    // ダウンローダ作成
    ReportDownloader reportDownloader = new ReportDownloader(reportService, reportJob.getId());

    // レポート準備完了を待つ
    reportDownloader.waitForReportReady();

    // ファイルの場所を変更    File file = File.createTempFile("delivery-report-", ".csv.gz");

    System.out.printf("Downloading report to %s ...", file.toString());

    //レポートをダウンロード    ReportDownloadOptions options = new ReportDownloadOptions();
    options.setExportFormat(ExportFormat.CSV_DUMP);
    options.setUseGzipCompression(true);
    URL url = reportDownloader.getDownloadUrl(options);
    Resources.asByteSource(url).copyTo(Files.asByteSink(file));

    System.out.println("done.");
    

データを読み込み


クライアントライブラリの多くでは、レポートデータを読み込むためのユーティリティーが提供されています。これはレポートデータを、異なる期間のデータを合体したり、さらに加工するときに便利です。


    List rows = CsvFiles.getCsvDataArray(filePath, true);
    for (String[] row : rows) {
      // Additional row processing
      processReportRow(row);
    }
    
他のサンプルは client libraries 

よくある質問


テスト時、レポートが空なのはなぜだろう

テストネットワークは広告を配信しません。配信レポート自体が存在しません。
errorReportError.COLUMNS_NOT_SUPPORTED_FOR_REQUESTED_DIMENSIONSエラーが返されます。
DFPでは、カラムと行のすべての組み合わせがサポートされているわけではありません。複雑なレポート作成のためには、まずはUIで作成しAPIにもってくる方法で行ってください。
 UIでは全期間のクリックとインプレッションの数が合いません。
作成中に数値が変化していることが考えられます。
レポート作成に時間がかかり、時々時間切れになります。どうしたらよいでしょうか?

データの期間と、行数を減らすことで、パフォーマンスを向上させることができます。より少ない期間で複数のレポートを処理するようにしましょう。そして、それが個別の期間のデータを合体させることで希望する全期間のデータを作成するようにしましょう。 
INVENTORY_LEVEL とLINE_ITEM_LEVEL カラムの違いは?
Columns with LINE_ITEM_LEVEL can only be used if you have line item level dynamic allocation enabled on your network. These columns include data from the line item level dynamic allocation to AdSense or Ad Exchange. Similarly, The INVENTORY_LEVEL columns include data from inventory level dynamic allocation. For more information about dynamic allocation, see this help center article.

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

How To ガイド




このページはAPIを使って主な機能を利用する方法を説明します。

ユーザの作成

UserServiceは、ユーザーが自分のネットワーク上で管理者権限を利用してuserディレクトリを作成できるようにします。

例えば、これを利用してすべてをAPIを管理者権限で呼び出すことなくAPIを試すことができます。
  1. 新しいGmailアドレスを作るasmy.name.dfp.salesperson@gmail.com.  Google accountなどでも可能
  2.  createUsersをそのアドレスで呼び出し、Role(役割)を選ぶ。 
  3. このユーザで認証後、アドレスとパスワードで認証トークンを作成できます。

すでに登録済みのユーザーを作成する場合には、新しいネットワークが作成され、そのユーザーは正当なネットワークコードを必要とします。

ルートとなる広告ユニットを取得する方法

広告ユニット情報を取得するためにもっとも効果的なルートを取得するには、, NetworkService.getCurrentNetwork()の戻り値のNeworkオブジェクトのeffectiveRootAdUnitIdフィールドを参照します。
そこから特定の広告ユニットを探し出すには、ルートとなる広告ユニットをクエリしてIDを取得、さらに別のクエリでそのIDを親のIDとする広告ユニットをすべて取得後、イテレートにより目的の広告ユニットを取得します。


注意:アカウントタイプにより階層パターンが異なります。サポートされる階層についてさらに詳しく学んでください。

オブジェクトのクエリ


PQLを使用することにより、IDから特定のオブジェクトを取得できます。

IDからクエリする

 getObject() 

criteriaによるクエリ

多くのサービス提供されるgetObjectsByStatement()を利用して、criteriaによりオブジェクトを探すことができます。
このメソッドはSQLのようにPQLクエリを取得、並び替え、などすることができます。 詳しくは、PQL Guideを参照 
Query results are broken into pages, where a page is a set of up to 500 results, and you can specify an offset value to get to results after the first 500. See the PQL Guide for more details on searching by statement.

 Orderを作成

orderを作成するには、オブジェクト作成したうえで広告主、営業マン、適切なユーザーのトラフィッカーのIDをセットし、さらに、名前をつけてcreateOrder()かcreateOrders()を呼びます。

結果には、もっとも新しく作成されたOrderかエラーが含まれます。
Example

 Line Itemの作成

新しいline item作成のステップ:
  1. 新たに Order オブジェクトを作成するか、既存のものを使用します。
  2.  LineItem オブジェクト作成し、rotationタイプ、creativeサイズ配列.開始日と終了日、その他のプロパティーをセットします。
  3. 新しくInventoryTargetingオブジェクトを作成し、どのプレイスメントまたは広告ユニットがターゲットになるのかを指定します。
  4.  InventoryTargeting オブジェクトを新たに作成したTargeting でラップし, LineItemの targeting プロパティにセットします。
  5. 新しいオブジェクトでlineitemサービスのcreateLineItem() メソッドを呼びます。

 Creativeの作成

別々のタイプのcreativeは、異なるコンポーネントサポートしています。
例えば、画像creativeは,単一の画像ソースファイルをサポートします。

レポート生成

DFPを利用して、配信レポートやセールスレポートなどの標準的なレポートを生成できます。

APIを利用することにより、このレポートをカスタマイズすることができます。以下はその生成方法です。
  1.  ReportQuery オブジェクト作成
  2. 取得する期間をセットする。
  3.  Columnenumeratedの値を使用して、どのカラムを含めるかを指定する。
  4. Optionally specify dimensions (groupings) and dimension filters (filters limiting which results to return).
  5.  ReportQuery を生成した ReportJob インスタンスに割り当てる
  6. ReportService.runReportJob(your_report_job).によりリポートを生成。ReportJobオブジェクトは即座にIDと状態を返しますが、 生成完了までには時間がかかりますので、この時点では状態は完了していないでしょう。
  7. 前述のように、多くの場合では、レポートは最初のコールでは完了しません。ReportService.getReportJob()を取得したIDで何度も呼んで状態は COMPLETED (か FAILED)になるまで待ちましょう。.
  8. 状態COMPLETEDになったら、ReportService.getReportDownloadURL()を呼んでレポートのダウンロード先URLを取得します。 

既存のオブジェクトの編集

getObject()でオブジェクトをクエリし,(またはgetObjectsByStatement()によりセットで取得し), たうえで、値を更新します。その後に、 updateObjects()を呼びます。
注意; アップロードされると元のオブジェクトが完全に置き換わります。値をセットし忘れた場合には、デフォルトに戻り前の値とのマージは行われませんので注意してください。  

オブジェクトの状態を変更

performObjectAction()を呼ぶ。このメソッドには2つの引数がある。 
  • 何をしたいのかを指定したactionオブジェクトのインスタンス          例えば、 orderサービスは幾つかのオプションを提供します。 ApproveOrdersPauseOrders, そしてArchiveOrdersなどです。. Action オブジェクトはすべてあなたのサービスに適切な基底Actionクラスから派生しています。オブジェクトの状態を変更した場合には、メールの送信などの動作が行われることがあります。どの状態の変更がどんな動作を起こすのか詳しくは Object Status 
  • どのオブジェクトを変更するかの PQL クエリ                  これにより同時に複数を変更できます。

広告タグの編集

DFPのダッシュボードでのみ行え、APIでは編集できません。  詳しくはTagging ヘルプを

より詳しいサンプル

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


認証



すべてのDFP API には OAuth 2.0認証が必要です.

OAuth 2.0 とDFP APIをはじめる

OAuth 2.0とclient librariesを併用するには:
  • Client IDと client secretの作成.
  •  client libraryの設定.

Create a Client ID and client secret

To use OAuth 2.0 to authorize the DFP API, you must first create a Client ID and a client secret:
  1. Click CREATE PROJECT to create a new project.
    Create a new project screenshot
  2. Enter the Project Name (and optionally, choose your own Project ID), and click Create.
    New project dialog screenshot
  3. The newly created project should automatically open. Click APIs & auth to expand the menu, and then click Credentials.
    New project dialog screenshot
  4. Click CREATE NEW CLIENT ID to create a new Client ID and client secret.
    Create new Client ID screenshot
  5. Choose Installed Application with type Other. Click CREATE CLIENT ID to complete the registration.
    Create Client ID screenshot
  6. Client ID and client secret will be created and displayed.
    Client ID and client secret screenshot
  7. Make sure all of the required fields are filled and saved for the Consent Screen.
    Consent screen configuration screenshot

Configure and use a client library

Follow these steps for the OAuth 2.0 Installed application flow:
  1. Put the corresponding Client ID and client secret into the client library's configuration file.
  2. Run the client library utility.
  3. The utility will point you to a Google consent page asking you to grant permission to the application.
    OAuth 2.0 consent screen screenshot
  4. Click Accept to grant permission to the application.
  5. Google will provide you an authorization code in the webpage.
    OAuth 2.0 authentication code screenshot
  6. Copy and paste the authorization code back to the client library utility.
  7. After entering the authorization code in the client library utility, it will then print out the refresh token.
  8. Store the offline refresh token in the client library's configuration file.
The following table provides detailed instructions on using OAuth 2.0 in different client libraries:
OAuth 2.0 Usage GuideOAuth 2.0 Utility
JavaJava
PHPPHP
.NET.NET
PythonPython
RubyRuby

Behind the scenes

Our client libraries automatically take care of the details covered below so only read on if you're interested in what's happening behind the scenes. This section is intended for advanced users who are already familiar with the OAuth 2.0 specification and know how to use OAuth 2.0 with Google APIs.

Scope

A single access token can grant varying degrees of access to multiple APIs. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access token request, your application sends one or more values in thescope parameter.
The scope for the DFP API is:
ScopeMeaning
https://www.googleapis.com/auth/dfpRead/write access to DFP API.

Offline access

It is common for a DFP API client application to request offline access. For example, your DFP API client application may want to run batch jobs when your user is not physically online browsing your website.
To request offline access for a Web application type, make sure you set the access_typeparameter to offline. You can find additional information in Google's OAuth 2.0 guide.
For Installed application type, offline access is enabled by default - you don't have to explicitly request offline access.

HTTP request header

The HTTP header in every request to the DFP API server must include the access token in this form:
Authorization: Bearer THE_ACCESS_TOKEN
For example:
POST  HTTP/1.1
Host: 
Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3ZgContent-Type: text/xml;charset=UTF-8
Content-Length: 
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
  
</soap:Envelope>

Access and refresh token

In most DFP API use cases, you will need to store the refresh token securely for future use. To learn more about how to request access and refresh tokens, read the guide that is relevant to your application type:

Access token expiration

An access token has an expiration time (based on the expires_in value) after which the token is no longer valid. You can use the refresh token to refresh an expired access token. By default, our client libraries automatically refresh an expired access token.