# Facebook Ads Insights インポート連携

Facebook Ads Insights のデータコネクタ(旧称 Facebook Ads Reporting)は、Facebook 広告キャンペーンの結果データをインポートすることができます。

# 前提条件

- Treasure Data の基本知識
- Facebook Marketing API、特に [Ads Insights API](https://developers.facebook.com/docs/marketing-api/reporting) の基本知識
- 管理者権限として Admin または Advertiser が必要


## TD Console を使用する

### 新しい接続を作成する

[Treasure Data Connections](https://console.treasuredata.com/app/connections/my-connections) に移動し、Facebook Ads を検索して選択します。次のダイアログが開きます。

![](/assets/image-20191017-181035.1577cc83f5875887b50ad38a67bdf8a6d5d95d993a4b9e160cc6050c17b8fc52.7ecd5fd4.png)

2つの認証方法をサポートしています:

- OAuth
- Access Token


#### OAuth を使用する

Facebook の既存の OAuth 接続を選択するか、OAuth connection の下にあるリンクを選択して新しい接続を作成します。

![](/assets/image-20191017-181104.d6e7e16dd7f44db42198d496e64bf99984d3766c9505f7705939367defbe8047.7ecd5fd4.png)

- 新しい OAuth 接続を作成する


ポップアップウィンドウで Facebook アカウントにログインします:

![](/assets/image-20191017-181215.84b82feaced3680bb19707fc0476cccb5f24b8dd22ba66375fadc90e070dd4e6.7ecd5fd4.png)

そして、Treasure Data アプリへのアクセスを許可します。

[Treasure Data Connections](https://console.treasuredata.com/app/connections/data-sources) にリダイレクトされます。最初のステップ(新しい接続を作成する)を繰り返し、新しい OAuth 接続を選択します。

![](/assets/image-20191017-181244.a60ae0b7f0aec4926d5bb6e9027725877936e6031873e0ece3d5fffe7045d67e.7ecd5fd4.png)

### Access Token を使用する

Access Token を作成するには、セクション3の「Facebook Token の取得」を参照してください。

### 新しい転送を作成する

接続を作成すると、自動的に [Authentications](https://console.treasuredata.com/app/connections/my-connections) タブに移動します。作成した接続を探して、New Source を選択します。

次のダイアログが開きます。

![](/assets/image-20191017-181852.d2ec4e6047223b7cccc3332d17d8f8a421150cf341c65ffcf559706b30bec298.7ecd5fd4.png)

以下の詳細を編集します:

- Ad Account ID
- Data Level
- Import Metadata for Related Objects
- Import all Insights or Insights Fields
- Breakdowns
- Filtering
- Action Attribution Windows
- Start and End Date or Incremental
- Reporting Period


これらのパラメータの詳細は次のとおりです:

#### Ad Account ID

Ad Account ID を追加します。これは[こちらの説明](https://www.facebook.com/business/help/1492627900875762)に従って見つけることができます。

#### Data Level

Ads オブジェクトレベルです。使用可能なオプションは、[Campaign](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group)、[Ad Set](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign)、[および Ad](https://developers.facebook.com/docs/marketing-api/reference/adgroup) です。

#### Import Metadata for Related Objects

デフォルトでは、Import metadata for related objects はチェックされておらず、コネクタは基本的なメタデータフィールドのみをインポートします: created_time、effective_status、status。

これをチェックすることで、インポートする関連オブジェクトまたは個別のメタデータフィールドを指定できます。

#### Related Edges

すべての関連 edges をインポートするには、All Metadata Fields を選択します。Fetch Metadata に各 edge を追加することで、インポートする edges を選択できます。

![](/assets/image-20191017-181943.0f8662c25dfaa1f79353be528fb0081ae03f2f43c1784f5f48f843c97839d9b0.7ecd5fd4.png)

#### Metadata Fields

Ads オブジェクトに関連付けられたメタデータフィールドです。Individual Metadata Fields を選択すると、必要なフィールドのみをインポートできます。Metadata Fields の下でフィールドを選択します。

![](/assets/image-20191017-182014.d8c6197ead093910d4d366530fdddb591b4ce6f4d99ef6c89786fd5206b6d49b.7ecd5fd4.png)

edge{field1, field2…} を使用して、Ads オブジェクトの edges にアクセスすることもできます。

#### Insights Fields

Insight フィールドは、キャンペーンのパフォーマンスに関するデータを提供します。

デフォルトでは、Import all insights fields がチェックされています。

![](/assets/image-20191017-182145.5f85958eaeb7374abdbeeacce093f8279dfffbce1dd8511fce87603fe0cbdf23.7ecd5fd4.png)

Import all insights fields のチェックを外して、特定のフィールドを選択できます。

![](/assets/image-20191017-182233.abf14a3a7aea654749a46b8a4e89bc52d41bb3cdd36adc1bf7eab279f0553e0e.7ecd5fd4.png)

[Insights](https://developers.facebook.com/docs/marketing-api/insights/parameters#fields) フィールドの date_start と date_stop は、明示的に設定されていない場合、デフォルトで追加されます。Insight の値は、Ads オブジェクトの状態によって空の場合があります。フィールドに値が含まれていない場合でも、エラーは生成されません。

#### Breakdowns

Breakdowns は、異なるセットまたはコホートにグループ化された Ads Insights レスポンスをキャプチャするために使用されます。サポートされている breakdowns は次のとおりです:

- age
- gender
- country
- region
- hourly_stats_aggregated_by_advertiser_time_zone
![](/assets/image-20191017-182602.176baa834f7a5c988fb153840b1f707717ea1aa4bd2e2d5cf56833bb82c43cc9.7ecd5fd4.png)


#### Filtering

報告されたInsightsデータのフィルター。フォーマット: フィールド —> オペレーター —> 値、action_typeはカンマ区切りの値でINオペレーターをサポートします。例: post_like, like

![](/assets/image-20191017-182636.70e3b86ff9bd63c4aebb6d29997f5c20aac293a1785898c2008fad41a77ae1d3.7ecd5fd4.png)

#### Action Attribution Windows

アクションのアトリビューションウィンドウを決定します。サポートされる値は以下の通りです:

- 1d_view
- 7d_view
- 28d_view
- 1d_click
- 7d_click
- 28d_click


明示的に設定されていない場合、デフォルト値は: (["1d_view","28d_click"]) です。

![](/assets/image-20191017-182744.08b30b683726638e208b213f3e8165b5015c618e91133cf1158977685e764000.7ecd5fd4.png)

### Incremental Import and Start Date

**Incremental**インポートと**Start Date**を指定するかどうかを選択します。

incrementalを有効にすることで、各増分ロードの期間(日数)を定義できます。デフォルトは1日です。**Start Date**が指定されていない場合、デフォルトは過去30日間に設定されます。

取得されるデータには、前日の深夜まで利用可能なデータが含まれます。

### Reporting Period

**Start Date**と**End Date**を使用してレポート期間を選択した後、期間全体の結果を取得するか、より小さな時間単位で結果を取得するかを選択できます。**All Days**を選択すると、期間全体で1つの結果セットが取得されます。**monthly**を指定すると、指定された期間内の各暦月ごとに1つの結果セットが取得されます。

![](/assets/image-20191017-182818.b3f389943b38e920575a9742ccabc8647a09c5e7fc4d53df09cba266e5c55653.7ecd5fd4.png)![](/assets/image-20191017-182855.3ce754b59a79079685b577b72b2ea1e57e42d4b1585e06692418734f362cfdcf.7ecd5fd4.png)

または、**In Days**を選択して指定したN日間の期間ごとに1つの結果セットを取得することもできます。1から90までの日数を指定できます。

![](/assets/image-20191017-182922.3ce754b59a79079685b577b72b2ea1e57e42d4b1585e06692418734f362cfdcf.7ecd5fd4.png)

パラメーターの指定が完了したら、**Next**を選択します。以下のダイアログと同様のデータのプレビューが表示されます。**Next**を選択します。プレビューを超えて進めない場合は、[Preview while Importing Data](https://docs.treasuredata.com/smart/project-product-documentation/about-data-preview)を参照してください。

![](/assets/image-20191017-183241.0cc37aaa8b7ebcd6de0c81a800b22ae833fd9e18777c6196fc6a306ec8c4ea45.7ecd5fd4.png)

以下のダイアログに示すように、データを転送するデータベースとテーブルを選択します:

![](/assets/image-20191017-183551.7daa417c4552d8d9afeb062c627880a591e65eb2edac38f029a5fe7f8f85301d.7ecd5fd4.png)

以下のダイアログを使用してデータ転送のスケジュールを指定し、**Start Transfer**を選択します。

![](/assets/image-20191017-183622.02f17beca8df86817524a2635baefb2e2afd3e513414ef6af7cb557ca028dbd9.7ecd5fd4.png)

新しいデータ転送が進行中としてMy Input Transfersタブの下に表示され、対応するジョブがJobsセクションに表示されます。

これで、データの分析を開始する準備が整いました!

## Use Command Line

### Install TD Toolbelt

最新のTD Toolbeltをインストールします。

### Obtain Facebook Token

[Facebookは3種類のトークンを提供しています](https://developers.facebook.com/docs/facebook-login/access-tokens)。期限切れのないPage Access Tokenの使用を推奨します。User Tokenも使用できますが、延長しても2か月後に期限切れになります。バッチ処理には適していません。

期限切れのないPage Access Tokenの取得方法については、[Facebook Long-Lived Access Tokens](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived/)を参照してください。

### Prepare Configuration and Preview Data

facebook_ads_reportingコネクターに対してtd connector:guessを実行する必要はありません。

以下のようにconfig.ymlを準備します:


```yaml
in:
  type: "facebook_ads_reporting"
  ad_account_id: '[your ad account id]'
  access_token: "[your Facebook access token]"
  data_level: ad
  fields:
    - clicks
    - impressions
  metadata_import: all
  metadata_edge:
    - adrules_governed
    - copies
    - keywordstats
    - leads
    - targetingsentencelines
  filtering:
    - {field : "clicks", operator: "GREATER_THAN", value: 10}
    - {field : "impressions", operator: "GREATER_THAN", value: 200}
out:
  mode: append
```

`preview`コマンドを使用してデータのプレビューを表示できます。


```bash
td connector:preview config.yml
```

### Configuration

利用可能なモードの詳細については、以下の表を参照してください。

| **Option name** | **Description** | **Type** | **Required?** | **Default value** |
|  --- | --- | --- | --- | --- |
| ad_account_id | access_tokenのアドアカウントID | string | yes | — |
| access_token | Access Token。期限切れのないトークンの使用を推奨します(次のセクションを参照) | string | yes | — |
| app_secret | 設定されている場合、appsecret_proofパラメーターがAPIへのアクセスに使用されます | string | optional | — |
| metadata_import | 関連エッジまたは個別のメタデータフィールドをインポートしますか? 利用可能なオプションはallとindividualです | string | optional | individual |
| metadata_edge | インポートする関連エッジ。metadata_importがallの場合のみ有効です。関連エッジを参照してください。 | array | optional | — |
| metadata_fields | 指定されたオブジェクトに対して取得したいメタデータフィールド。[利用可能なフィールドを確認してください。](https://developers.facebook.com/docs/marketing-api/reference/v2.9) | array | optional | created_time, status, effective_status |
| fields | Insightsに対して取得したいフィールド。[利用可能なフィールドを確認してください。](https://developers.facebook.com/docs/marketing-api/reference/v2.9) | array | optional | — |
| breakdowns | 詳細についてはbreakdownsを参照してください。 | string | optional | — |
| filtering | 詳細についてはfilterを参照してください。 | array | optional | — |
| action_attribution_windows | アクションのアトリビューションウィンドウを決定します。たとえば、28d_clickは広告がクリックされてから28日以内に発生したすべてのアクションをAPIが返すことを意味します。 | array | optional | — |
| retry_limit | 最大リトライ回数 | integer | optional | 5 |
| retry_initial_wait_sec | エクスポネンシャルバックオフの初期値の待機秒数 | integer | optional | 10 |
| last_fetched_at | この日付以降のデータのみをインポートします。指定されていない場合は、今日から30日前（つまり、today - 30 days）になります。推奨形式: %m/%d/%Y または %Y-%m-%dT%H:%M:%S.%L%Z | string | optional | — |
| incremental | embulk run -c config.diffで "config_diff" を生成する場合はtrue | bool | optional | true |
| duration | 開始日からインサイトデータを取得する日数。詳細は付録Bを参照してください。 | integer | optional | 1 |
| time_increment | 整数の場合、1から90までの日数を指定します。last_fetched_atとlast_fetched_untilを使用してレポート期間を選択した後、期間全体の結果を取得するか、より小さな時間スライスの結果を取得するかを選択できます。"all_days"を使用すると、期間全体の1つの結果セットが得られます。"monthly"を使用すると、指定された期間内の各カレンダー月ごとに1つの結果セットが得られます。または、このパラメータで指定されたN日間ごとに1つの結果セットを取得できます。詳細は付録Bを参照してください。 | string | optional | 1 |
| last_fetched_until | この日付までのデータのみをインポートします。指定されていない場合は今日になります。推奨形式: last_fetched_atを参照してください。詳細は付録Cを参照してください。 | string | optional | — |
| add_time_column | trueの場合、インサイトのdate_stop値に基づいて"time"カラムが自動的に追加されます。それ以外の場合は、upload_timeによって"time"カラムが追加されます | bool | optional | true |
| data_level | データレベルを取得します。Facebookインサイトレベル: Campaign –> Adset –> Ad。使用可能なオプションは "campaign"、"adset"、"ad"、または "ad_creative" です。 | string | optional | "ad" |
| api_version | 使用するFacebook APIのバージョン。デフォルトはv3.2です。指定されたバージョンがv3.1より古い場合（非推奨）、プラグインは "v3.2" を使用します | string | optional | "v3.2" |
| limit_per_page | ページあたりのレコード数。"Please reduce the amount of data you're asking for, then retry your request"というエラーメッセージが表示された場合は、この値を減らしてください | integer | optional | 100000 |


### サポートされている関連エッジ

#### Campaign

- ad_studies
- adrules_governed
- ads
- adsets
- copies


#### AdSet

- activities
- ad_studies
- adrules_governed
- ads
- copies
- targetingsentencelines


#### Ad

- adrules_governed
- copies
- keywordstats
- leads
- targetingsentencelines


### durationとtime_increment

#### durationはいつ使用しますか？

- **duration**は**incremental = true**の場合にのみ有効です
- **duration**は**last_fetched_at**に基づいてリクエストの時間範囲を計算するために使用されます。たとえば、**last_fetched_at = 02/01/2017**で**duration = 2**の場合、リクエストする時間範囲は02/01/2017 → 02/02/2017になります


Facebookリクエストパラメータに直接変換すると:


```
.time_range({"since":"2017-02-01","until":"2017-02-02"})
```

- このパラメータを使用する場合、ブレークダウンの動作はありません。時間範囲全体のインサイト値を返します。
- **注**: **last_fetched_at**が指定されていない場合、今日から30日前（つまり、today – 30 days）になります


#### time_incrementはいつ使用しますか？

- **time_increment**は、インサイトデータを日数で分割したい場合に使用します。結果は、インクリメンタルモードとdurationを使用しない場合に最も認識しやすくなります。


例:


```yaml
incremental: false
last_fetched_at: 03/01/2017
last_fetched_until: 03/31/2017
time_increment: 1
```

上記の設定を使用すると、2017年3月全体を1回の実行でインポートでき、それでも日次で分割できます。

#### durationとtime_incrementの違い

- **duration**は**incremental**モードで使用されます
- **time_increment**は公式のFacebookパラメータです
- **重要な注意事項**: **duration**と**time_increment**の両方が使用可能な場合（デフォルト）、**duration**の値が**time_increment**より小さい場合、**duration**は**time_increment**よりも優先されます。つまり、**duration = 1**の場合、2日ごとのブレークダウンデータ（**time_increment = 2**）は取得できず、結果は1日分のデータになります。一方で、2日間のduration（**duration = 2**）に対して日次でデータを分割（**time_increment = 1**）することは完全に可能です。


#### last_fetched_untilはいつ使用しますか？

- **last_fetched_until**はオプションであり、その唯一の用途はインポートするデータを終了日で制限することです。


例: 2017年3月のデータをインポートするジョブがあり、毎日データを取得するために繰り返し実行するようにスケジュールされています。したがって、次の設定を使用してこれを実現できます:


```yaml
incremental: true
duration: 1
last_fetched_at: 03/01/2017
last_fetched_until: 03/31/2017
```

**注**: ご覧のとおり、**duration**を使用してジョブを繰り返し実行することで**time_increment**の効果をシミュレートできますが、より多くのリクエストが発生します（リクエストレート制限により早く到達します）。

- スケジュールされたジョブが（最終的に）設定された**last_fetched_until**を超えた場合、空の結果が返されます。


## 2018年7月10日リリースでのData Connectorスキーマの変更

Facebook APIの最近の変更により、Data Connectorが更新されました。

**変更前:** 一部のフィールドが追加されましたが、値が空だったため、出力スキーマに一部のカラムが欠落していました。

**変更後:** 一部の新しいカラムが追加されますが、値が含まれていない場合があります。出力スキーマは、入力設定と必須フィールドから組み合わされます。

必須フィールドと暗黙的に追加されるカラムは次のとおりです:

- メタデータフィールド
  - created_time
  - effective_status
  - status
- インサイトフィールド
  - date_start
  - date_stop


以前の更新でスキップされた可能性のある無効な`**fields**`は、更新後にエラーになります。インサイトフィールドとメタデータフィールドの完全なリファレンスについては、次のリンクの`Fields`セクションを参照してください:

- [Campaignレベルのメタデータフィールド](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group#Reading)
- [Ad Setレベルのメタデータフィールド](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign#Reading)
- [Adレベルのメタデータフィールド](https://developers.facebook.com/docs/marketing-api/reference/adgroup#Reading)
- [インサイトフィールド](https://developers.facebook.com/docs/marketing-api/reference/ads-insights/)