# Facebook Page Insights Import Integration

Facebook Page Insights インテグレーションを接続して、以下の Facebook データを Treasure Data にインポートできます:

- [Page insights](https://developers.facebook.com/docs/graph-api/reference/v6.0/insights)
- [Post insights](https://developers.facebook.com/docs/graph-api/reference/post/insights/)
- [Video Insights](https://developers.facebook.com/docs/graph-api/reference/video/video_insights/)
- [Comments](https://developers.facebook.com/docs/graph-api/reference/v6.0/object/comments)
- [Conversation Participants](https://developers.facebook.com/docs/graph-api/reference/page/conversations/)
- [Conversation Messages](https://developers.facebook.com/docs/graph-api/reference/v6.0/conversation/messages)


## 前提条件

- Treasure Data の基本的な知識
- Facebook Graph API の基本的な知識
- Facebook Page データをダウンロードするために必要な権限
- 認証された Treasure Data アカウントへのアクセス


## TD Console を使用した接続の作成

### 新しい Authentication の作成

Integrations Hub > Catalog に移動します。Facebook Page Insights を検索して選択します。ダイアログが開きます。

![](/assets/image-20191017-210320.45b16b9ff73f9c639627a2c0629db4923ce78ddbcef2f12c0d0c535e580b03e3.4ac59c12.png)

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

![](/assets/image-20191017-210750.ed776521d5e97fa8c5c454f61b78b4f1100c8ef807aedcb130a389964eccdfcf.4ac59c12.png)

### 新しい OAuth 接続の作成

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

![](/assets/image-20191017-210808.88e27aad3041867a9970bdd740cf86fa67c4f15ce47a655fd9eb583051e60260.4ac59c12.png)

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

TD Console にリダイレクトされます。最初のステップ(新しい authentication の作成**)** を繰り返し、新しい OAuth 接続を選択します。

![](/assets/image-20191017-210840.aabffa2d03c7059fe0ea0f6116c9cbe7e0e947cc447e926aa229b965196023c0.4ac59c12.png)

新しい authentication に名前を付けます。**Done** を選択します。

![](/assets/image-20191017-210911.ae4274b1fc1d2af755683e4f58e585882b7abe3715eca3c5537f443b27e95f17.4ac59c12.png)

### Facebook Insights データを Treasure Data に転送する

**Authentications** で、**New Source** を設定します。

![](/assets/image-20191017-210935.bb873f066cd95ded8e17aca1046832603b5773aa17c05ac29678c9d8aa131b12.4ac59c12.png)

このダイアログで Data Transfer Name を編集して Source に名前を付けることができます。

1. Data Transfer フィールドで **Source** に名前を付けます。
2. **Next** を選択します。Source Table ダイアログが開きます。


![](/assets/image-20200330-193201.b416ea4b9c91a08ef18afaa872503538ee3b6bb9f75d12558b5823eab0ae84ff.4ac59c12.png)

### Source Table

Source Table で、パラメータを編集して **Next** を選択します。

![](/assets/image-20200330-193531.a9eadc3ea07f75316f8a63936e463be2d740b65b2ac675f0b2a762e97ddc0e59.4ac59c12.png)

| **Parameter** | **Description** |
|  --- | --- |
| **Data Type** | サポートされているデータタイプ**:**   - Page - Post - Video - Conversation Messages - Conversation Participants - Comments |
| **Folders(s)** | Conversation フォルダ |


データタイプ Video の場合、サポートされている期間は Lifetime のみです。

### Data Settings

このダイアログで、データ設定を編集するか、このステップをスキップできます。

1. Data Settings パラメータを編集します。
2. Next を選択します。


![](/assets/image-20200330-193913.b257f6d711d5944fbb9af4d682d21cb9285d532fc9837511ce272d42a88e1864.4ac59c12.png)

| **Parameters** | **Description** |
|  --- | --- |
| **Retrieve Video insights back to** | Facebook が指定するデータ制限により、ジョブが過去のすべてのデータの取得に失敗する場合があります。デフォルト設定では、Video Insights の過去3ヶ月のデータをインポートします。より多くのデータをインポートするには、この値を更新してください。 |
| **Skip Error POST** | デフォルトは true です。POST Insights のインポート時にエラーが発生した場合、そのエラーをスキップします。 |
| **Retry Limit** | コネクタが接続とデータ取得の試行を停止するまでの再試行回数。 |
| **Retry initial wait in millis** | 回復可能なエラーが発生した場合に再試行する間隔(ミリ秒単位)。 |
| **Max retry wait in millis** | 再試行間の最大待機時間(ミリ秒単位)。 |
| **HTTP connect timeout in millis** | HTTP 接続タイムアウト。 |
| **HTTP idle timeout in millis** | HTTP アイドルタイムアウト。 |


### Data Preview

インポートを実行する前に、Generate Preview を選択してデータの[プレビュー](/products/customer-data-platform/integration-hub/batch/import/previewing-your-source-data)を表示できます。Data preview はオプションであり、選択した場合はダイアログの次のページに安全にスキップできます。

1. **Next** を選択します。Data Preview ページが開きます。
2. データをプレビューする場合は、**Generate Preview** を選択します。
3. データを確認します。


### Data Placement

データの配置について、データを配置したいターゲット database と table を選択し、インポートを実行する頻度を指定します。

1. **Next** を選択します。Storage の下で、インポートされたデータを配置する新しい database を作成するか、既存の database を選択し、新しい table を作成するか、既存の table を選択します。
2. **Database** を選択 > **Select an existing** または **Create New Database** を選択します。
3. オプションで、database 名を入力します。
4. **Table** を選択 > **Select an existing** または **Create New Table** を選択します。
5. オプションで、table 名を入力します。
6. データをインポートする方法を選択します。
  - **Append** (デフォルト) - データインポートの結果は table に追加されます。
table が存在しない場合は作成されます。
  - **Always Replace** - 既存の table の全体の内容をクエリの結果出力で置き換えます。table が存在しない場合は、新しい table が作成されます。
  - **Replace on New Data** - 新しいデータがある場合のみ、既存の table の全体の内容をクエリの結果出力で置き換えます。
7. **Timestamp-based Partition Key** 列を選択します。
デフォルトキーとは異なるパーティションキーシードを設定したい場合は、long または timestamp 列をパーティショニング時刻として指定できます。デフォルトの時刻列として、add_time フィルターで upload_time を使用します。
8. データストレージの **Timezone** を選択します。
9. **Schedule** の下で、このクエリを実行するタイミングと頻度を選択できます。


#### 一度だけ実行

1. **Off** を選択します。
2. **Scheduling Timezone** を選択します。
3. **Create & Run Now** を選択します。


#### 定期的に繰り返す

1. **On** を選択します。
2. **Schedule** を選択します。UI では、*@hourly*、*@daily*、*@monthly*、またはカスタム *cron* の 4 つのオプションが提供されます。
3. **Delay Transfer** を選択して、実行時間の遅延を追加することもできます。
4. **Scheduling Timezone** を選択します。
5. **Create & Run Now** を選択します。


転送が実行された後、**Data Workbench** > **Databases** で転送の結果を確認できます。

## コマンドラインを使用した Facebook 接続の作成

Treasure Data Console を使用して接続を設定できます。

### Treasure Data Toolbelt のインストール

ターミナルを開き、以下のコマンドを実行して最新の [TD Toolbelt](https://toolbelt.treasuredata.com/) をインストールします。

### Facebook Token の取得

[Facebook は3種類のトークンを提供しています](https://developers.facebook.com/docs/facebook-login/access-tokens)。Page Access Token が必要です。有効期限のない Page Access Token を選択することをお勧めします。

有効期限のない Page Access Token を取得するには、こちらの手順に従ってください: [https://www.rocketmarketinginc.com/blog/get-never-expiring-facebook-page-access-token/](https://www.rocketmarketinginc.com/blog/get-never-expiring-facebook-page-access-token/)

### 設定ファイル(config.yml)の準備

テキストエディタを使用して、config.yml というファイルを作成します。以下の情報をコピーして貼り付け、プレースホルダーテキストを Facebook コネクタ情報に置き換えます。

**in** セクションは Facebook からコネクタに入ってくるものを指定し、**out** セクションはコネクタが Treasure Data のデータベースに送信するものを指定します。利用可能な **out** モードの詳細については、付録を参照してください。


```yaml
in:
  type: "facebook_page_insights"
  access_token: "[your Facebook Page token]"
  page_id: [your Facebook Page ID]
  data_type: page
  incremental: true
  select_all_metrics: true
  since: 2017-01-01
  until: 2017-01-31
out:
  mode: append
```

設定キーと説明は以下の通りです:

| Option name | Description | Type | Required? | Default Value |
|  --- | --- | --- | --- | --- |
| access_token | Facebook Page Access Token。 | string | yes | — |
| page_id | Facebook Page ID。付録を参照してください | string | yes | — |
| data_type | - page - post - video - conversation_message - conversation_participant - comment | string | optional | page |
| select_all_metrics | 現在のデータタイプでサポートされているすべての Insight メトリクスをインポートします。この値を設定すると、metric_presets や metrics を設定する必要がありません。Page と Post に適用されます。Available Metrics を参照してください。 | bool | optional |  |
| metric_presets | 事前定義されたメトリクスのカテゴリまたは関連するメトリクスのグループ。Supported Preset Metrics を参照してください。 | array | optional | — |
| metrics | Facebook Graph の Insight メトリクスで、必要なだけ各メトリクスを指定できます。両方が指定されている場合、この設定は metric_preset を上書きします。Supported Metrics | array | optional | — |
| since | 考慮する時間範囲の下限で、サポートされる形式: yyyy-MM-dd または Unix time(例: 1584697547) | string | optional | — |
| until | 考慮する時間範囲の上限で、サポートされる形式: yyyy-MM-dd または Unix time(例: 1584697547) | string | optional | — |
| period | 集計期間。Supported Periods を参照してください。 | enum | optional | — |
| date_preset | 'lastweek' や 'yesterday' のような日付範囲をプリセットします。'since' または 'until' の日付が指定され、date_preset も選択されている場合、データ転送リクエストは失敗します。Supported Date Presets を参照してください。 | enum | optional | — |
| incremental | embulk run -c config.diff で "config_diff" を生成する場合は true | bool | optional | false |
| last_in_months | 指定した月範囲まで遡ってVideoインサイトを取得します。3ヶ月を超える範囲を指定すると、Facebook APIの制限によりジョブエラーが発生します。 | integer | オプション | 3 (months) |
| skip_error_post | POSTインサイトのインポート時にエラーをスキップします | bool | オプション | true |
| retry_limit | コネクターが諦めるまでのエラーリトライ回数 | integer | オプション | 7 |
| retry_initial_wait_millis | 指数バックオフの初期値の待機時間(ミリ秒) | integer | オプション | 500 (0.5 second) |
| max_retry_wait_millis | 各リトライの最大待機時間(ミリ秒) | integer | オプション | 300000 (5 minutes) |
| connect_timeout_millis | HTTP接続タイムアウト(ミリ秒) | integer | オプション | 180000 (3 minutes) |
| idle_timeout_millis | HTTPアイドルタイムアウト(ミリ秒) | integer | オプション | 300000 (5 minutes) |
| conversation_folders | 会話フォルダ: inbox、page_done、other、pending、spam  例: [{"value":"inbox"}] | array | オプション | all folders |


incrementalとPageデータタイプを使用したconfig*.yml*の例


```yaml
in:
  type: "facebook_page_insights"
  access_token: "[your Facebook Page token]"
  page_id: [your Facebook Page ID]
  data_type: page
  page_metric_presets:
  - value: page_impressions
  - value: page_cta_clicks
  - value: page_user_demographics
  - value: page_views
  - value: page_engagement
  incremental: true
  since: 2017-01-01
  until: 2017-01-31
out:
  mode: append
```

Postデータタイプ


```yaml
in:
  type: "facebook_page_insights"
  access_token: "[your Facebook Page token]"
  page_id: [your Facebook Page ID]
  data_type: post
  post_metric_presets:
  - value: page_post_impressions
  - value: page_post_engagement
  - value: page_post_reactions
  - value: page_video_posts
  since: 2017-01-01
  until: 2017-01-31
out:
  mode: append
```

Videoデータタイプ


```yaml
in:
  type: "facebook_page_insights"
  access_token: "[your Facebook Page token]"
  page_id: [your Facebook Page ID]
  data_type: video
  last_in_months: 3
out:
  mode: append
```

### インポートするデータのプレビュー (オプション)

**td connector:preview**コマンドを使用して、インポートするデータをプレビューできます。


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

### ロードジョブの実行

ロードジョブを実行する前に、データを保存するデータベースとテーブルを指定する必要があります。

td connector:issueを使用してジョブを実行します。以下が必要です: スケジュールの名前、cron形式のスケジュール、データが保存されるデータベースとテーブル、およびData Connector設定ファイル。


```bash
td connector:issue config.yml --database td_sample_db --table td_sample_table
```

Treasure Dataのストレージは時間でパーティション分割されているため、--time-columnオプションを指定することをお勧めします。また、--time-columnオプションを使用して、end_timeを時間カラムとして指定することで、自動生成された時間値を上書きできます(data_type**page**にのみ適用されます)。データは毎日蓄積され、end_timeはFacebookページのタイムゾーンを使用した1日の終わりになりますが、UTC形式に変換されます。

データに時間カラムがない場合は、add_timeフィルターオプションを使用して追加できます。詳細は[add_time Filter Plugin for Integrations](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function)を参照してください。

最後に、ロードジョブを送信します。データサイズによっては、数時間かかる場合があります。データが保存されるデータベースとテーブルを指定する必要があります。


```bash
td connector:issue config.yml --database td_sample_db --table
td_sample_table --time-column end_time
```

### スケジュール実行

増分Facebook Insightsデータの定期的なデータコネクター実行をスケジュールできます。高可用性を確保するため、スケジューラーを慎重に設定しています。この機能により、ローカルデータセンターでcronデーモンを使用する必要がなくなります。

スケジュールされたインポートの場合、Data Connector for Facebook Page Insightsは最初の実行時にすべての広告データをインポートします。

2回目以降の実行では、コネクターは最後のロードよりも新しいデータのみをインポートします。

#### スケジュールの作成

td connector:createコマンドを使用して新しいスケジュールを作成できます。以下が必要です: スケジュールの名前、cron形式のスケジュール、データが保存されるデータベースとテーブル、およびData Connector設定ファイル。


```bash
$ td connector:create \
    daily_import \
    "10 0 * * *" \
    td_sample_db \
    td_sample_table \
    config.yml
```

`cron`パラメーターは、`@hourly`、`@daily`、`@monthly`の3つの特別なオプションも受け付けます。デフォルトでは、スケジュールはUTCタイムゾーンで設定されます。—tまたは—-timezoneオプションを使用して、異なるタイムゾーンでスケジュールを設定できます。`--timezone`オプションは、'Asia/Tokyo'、'America/Los_Angeles'などの拡張タイムゾーン形式のみをサポートしていることに注意してください。PSTやCSTなどのタイムゾーンの略語はサポートされておらず、予期しないスケジュールになる可能性があります。

## FAQ

### Q: スケジュールされたジョブが「SUCCESS」と分類されたのに、新しいデータが取り込まれなかったのはなぜですか?


```
2018-05-06 13:00:18.627 +0000 [WARN] (0047:task-0043): Time range does not reach, abort and will retry later. Start Date: '1525330800', End Date: '1528095600', Current Date: '2018-05-06'
```

これは、'Start Date'または'End Date'が現在の日付を超えている(例: 将来の日付が指定されている)ことを意味します。このような警告メッセージの原因は、取得する時間範囲よりも短いcronを設定していることが考えられます。例えば、月次データを取得する日次ジョブなどです。

### Q: 毎回新しいデータを取り込むための日次ジョブを設定するにはどうすればよいですか?

初期ロード(または各ロードの3ヶ月という時間範囲の制限により、複数回のロード)が必要です。今日が2018-05-09で、2018-01-01以降のデータをロードする必要があるとしましょう:

| **Jobs** | **Start Date** | **End Date** |
|  --- | --- | --- |
| 最初のジョブ (1回限り) | 2018-01-01 | 2018-04-01 |
| 2番目のジョブ (1回限り) | 2018-04-01 | 2018-05-08 |
| [増分] 日次ジョブ | 2018-05-08 | 2018-05-09 |


### Q: 突然大量のPosts Insightsデータが表示されるのはなぜですか?

バージョンv0.2.0以降、ページの最初の投稿から**End Date**値までのすべての投稿のインサイトを取得できるようになります。この改善により、日付設定がアップグレードされ、利用可能なすべての投稿の**Start Date**から**End Date**までのInsightsデータを取得できるようになります。バージョンv0.1.16と比較すると、その日付範囲内に作成された投稿の**Start Date**から**End Date**までのインサイトデータのみを取得できました。

## Page ID

コネクターを作成する際にページのユーザー名を使用する代わりに、Page IDを使用できます。Page IDを見つけるには、Facebookページで**About**メニューを選択し、Page IDまで下にスクロールします:

![](/assets/image-20191017-212720.d13ab7557b7f8108626a126329983da7233e2f4c98922fe36ecad09470d100e6.4ac59c12.png)