# Instagram User And Media Insights Import Integration

Instagram Businessを使用すると、Instagramのメディアオブジェクトやユーザーアカウントアクティビティに関するインサイトを取得できます。Treasure Dataのコネクタを使用して、InstagramインサイトデータをTreasure Dataに取り込むことができます。

- email_contacts-day
- follower_count-day
- get_directions_clicks-day
- impressions-day
- impressions-days_28
- impressions-week
- online_followers-lifetime
- phone_call_clicks-day
- profile_views-day
- reach-day
- reach-days_28
- reach-week
- text_message_clicks-day
- website_clicks-day
- engaged_audience_demographics-lifetime
- reached_audience_demographics-lifetime
- follower_demographics-lifetime


#### メディアタイプ

- media_all
- story_metrics
- carousel_album_metrics
- photo_and_videos_metrics


# Facebook Page IDの取得

Instagram BusinessアカウントにリンクされているFacebook Page IDを入力してください。ユーザーがInstagramアカウントを作成またはビジネスアカウントに変換する際、そのInstagramアカウントをFacebookページにリンクする必要があります。

![](/assets/336497.cac8a0f1fc3b4512a0297fa392903780898b4a3f5bc31a5ceb8ada06ee882018.632f0615.png)

# 拡張ユーザーアクセストークン

Facebookユーザーアクセストークンは、デフォルトでは短期間有効なアクセストークンです。

Treasure Dataプラットフォームでスケジュールジョブを実行するには、長期間有効なアクセストークンを取得してください:

- Facebookツールを使用して長期間有効なユーザーアクセストークンを取得するには、[こちらの記事](https://medium.com/@yasithlokuge/how-to-generate-a-never-expiring-facebook-page-access-token-24ac5c1a95f1)の手順に従ってください
- Facebook APIを使用して長期間有効なトークンを取得するには、[こちらの手順](https://developers.facebook.com/docs/facebook-login/access-tokens/refreshing/#long-via-code)に従ってください


TD Consoleを使用してジョブを実行する場合、コネクタはすでに長期間有効なアクセストークンを交換しています。

次の権限(スコープ)が必要です:

- `public_profile`
- `email manage_pages`
- `pages_show_list`
- `instagram_basic`
- `instagram_manage_insights`
- `instagram_manage_comments`
- `ads_management`


# TD Consoleを使用してConnectionを作成する

## 新しいAuthenticationの作成

データ接続を設定する際、統合にアクセスするための認証情報を提供します。Treasure Dataでは、認証を設定してからソース情報を指定します。

1. **TD Console**を開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. Instagram User & Media Insightsを検索して選択します。
![](/assets/346839.ee32ae0da32e939b3c4f56cb895a09f0196480f8440dbc46303efdd4dcb73029.632f0615.png)
4. Instagram Insights用の既存のOAuth connectionを選択するか、OAuth connection下のリンクをクリックして新しいものを作成します。


![](/assets/340124.41ba2178ddc99c2667229ae9b9d27903cab4cd1d99ea49070f366e3355bcb0bc.632f0615.png)

### 新しいOAuth connectionの作成

Instagram OAuthはFacebook OAuthを使用するため、Facebook OAuthページに移動します。

1. Facebookアカウントにログインします:
![](/assets/336496.80059c6423a8d92d27cb49bd300af0d3436814b00b725b9c89379848252cb7aa.632f0615.png)
2. **Continue as**ボタンを選択して、Treasure Dataアプリへのアクセスを許可します。
![](/assets/107151981.6f84dbb50833f1a0d34749bf1e6b3c74a19b784bc4c7c408ba001cb3d66bc3cb.632f0615.png)
3. Catalogページにリダイレクトされます。最初の手順(`Create a new authentication`**)** を繰り返し、新しいOAuth connectionを選択します。
![](/assets/346842.38ecd49598afe0e60d146b958c428d5898d8ca3b016cd75a7066de870ae905f2.632f0615.png)
4. 新しいauthenticationに名前を付けます。**Done**を選択します。


![](/assets/346849.a31ad0b10449c8a5d7510c26666e7dfc9bd5ee063dff96e235ecc59cd20dfcc7.632f0615.png)

## InstagramアカウントデータをTreasure Dataに転送する

認証済み接続を作成すると、自動的に**Authentications**に移動します。

1. 作成したconnectionを検索します。
2. **New Source**を選択します。


![](/assets/336498.14b8458af014163f0a82d4912a4ef9ed05bbd4e8a2b4f94cc18faa3bdc788d39.632f0615.png)

### Connection

1. **Connection** ページが開きます。
2. **Data Transfer** フィールドにソースの名前を入力します。


![](/assets/340128.f8d0eb8bccd8ee1a9dbac475fa37783e5a3328dadc1a30c96d54c322e50bec51.632f0615.png)

### ソーステーブル

1. **Next** を選択します。**Source Table** ページが開きます。
2. ソーステーブルで以下のパラメータを編集します。


![](/assets/340139.022c91f9270bb1b0468979e20a78416cc2dbcdc12ec04650538c8d7280e2abaa.632f0615.png)

| **パラメータ** | **説明** |
|  --- | --- |
| **Facebook Page ID** | 必須。Instagram Business アカウントにリンクされている Facebook ページ ID。 |
| **Data type** | 必須。データタイプのいずれかを選択します |
| **User** | インサイトは、Instagram Business アカウントについて収集されるメトリクスです（impressions、follower_count*、website_clicks、audience_locale など）。 |
| **Media** | インサイトは、Instagram Business アカウントに投稿されたコンテンツから収集されるメトリクスです（engagement、impressions、reach、saved など）。 |
| **Comments** | オーガニックな Instagram コメントを表します。 |
| **Media List** | Instagram の写真、動画、ストーリー、アルバムを表します |
| **Tags** | 別の Instagram ユーザーによって [IG User](https://developers.facebook.com/docs/instagram-api/reference/user) がタグ付けされた [IG Media](https://developers.facebook.com/docs/instagram-api/reference/media) オブジェクトのコレクションを表します。 |
| **Start Date & End Date** | **User** データタイプには必須。開始日と終了日は次の形式に従う必要があります：YYYY-MM-DD。例：2017-11-21   - **Start Date** は包含的で、**End Date** は排他的です。    - 指定されていない場合、終了日は **Instagram Business Account Local Time** の現在時刻がデフォルトになります。   - 指定されていない場合、開始日は終了日の 2 日前がデフォルトになります。デフォルトは Facebook API によって設定されます。   データは毎日の終わりに集計されるため、2017-01-01 のインサイトは end_time = 2017-01-02 00:00:00 になります。 |
| **Use Individual Metrics** | インポートするメトリクスデータを選択する場合に選択します。ドロップダウンには、選択したデータタイプのすべての個別メトリクスが一覧表示されます。複数のメトリクスを選択できます。   - Media メトリクスは [period: lifetime] のみをサポートします - User メトリクスは day、week、days_28、lifetime をサポートします。 - メトリクスのリスト（engaged_audience_demographics、reached_audience_demographics、follower_demographics）には、以下の追加設定が必要です：   - breakdown: 複数の値を入力でき、カンマで区切ります。サポートされる値（age、country、city、gender）   - metric_type: total_value を選択   - Timeframe: 期間の値を選択します。サポートされる値（last_14_days、last_30_days、last_90_days、prev_month、this_month、this_week） |
| **Preset User Metrics** | デフォルトは Week metrics です。以下のプリセット User メトリクスから選択できます：   - Week metrics [period: week] - Days 28 metrics [period: days_28] - Day metrics [period: day] - Lifetime metrics [period: lifetime]、増分インポートをサポートしません |
| **Preset Media metrics** | デフォルトは All media metrics です。以下のプリセット Media メトリクスから選択できます：   - All media metrics. すべての Media メトリクスは、Instagram アカウント内のすべてのコンテンツのメトリクスをインポートします - Story metrics. Instagram Story のメトリクスをインポートします - Carousel metrics. Instagram Carousel のメトリクスをインポートします - Photo and video metrics は Instagram の画像と動画のメトリクスのみをインポートします* |
| **Import media metrics** | メトリクスが複数のメディアオブジェクト（例：IMAGE、VIDEO、STORY など）でサポートされている場合、それらすべてのメディアオブジェクトのメトリクス値がインポートされます。 |
| **Import user metrics** | User メトリクスは day、week、days_28、lifetime をサポートします |
| **Incremental Loading** | 反復的に実行されるジョブをスケジュールできます。ジョブ実行の各反復は開始日と終了日の値に基づいて計算され、ギャップや重複なく毎回新しい値がインポートされます。  次の例では、開始日と終了日の間の 9 日間の範囲を使用します：  `Start Date: 2017-10-01 End Date: 2017-10-11`  各ジョブは、開始日と終了日の間の期間によって決定される同じ時間範囲を持ちます。メトリクスの転送は、前のジョブの完了時から開始され、期間が現在の日付（デフォルトの終了日）を過ぎるまで続きます。さらなる転送は、完全な期間が利用可能になるまで遅延され、その時点でジョブが実行され、次の期間が利用可能になるまで一時停止します。  1回目の実行: 開始 end_time: 2017-10-01 07:00:00 終了 end_time: 2017-10-10 07:00:00  2回目の実行: 開始 end_time: 2017-10-11 07:00:00 終了 end_time: 2017-10-20 07:00:00  3回目の実行: 開始 end_time: 2017-10-21 07:00:00 終了 end_time: 2017-10-30 07 |


*2021年5月9日現在、Facebook API [変更ログ](https://developers.facebook.com/docs/graph-api/changelog/version9.0#instagram)によると、IG `follower_count` は2年間ではなく最大30日間のデータを返すようになりました。User `follower_count` の値は、Instagram アプリに表示される対応する値とより密接に一致します。したがって、User follower_count メトリクスが個別に選択された場合、クエリ時間は30日以内である必要があります。User オブジェクト全体をインポートする場合、クエリ時間が過去30日間（現在の日を除く）より古い場合、User follower_count メトリクスは空の値として返されます。  **online_followers メトリクスを除き、lifetime メトリクスでは、Incremental Loading チェックボックスのチェックを外し、Start Date と End Date フィールドを空にする必要があります。

### データ設定

データ設定では、転送をカスタマイズできます。

1. **Next** を選択します。
Data Settings ページが開きます。
2. 必要に応じてデータ設定を編集するか、このダイアログページをスキップします。


![](/assets/346805.21314f971d9d2103f4d9a50c34dd1f46be132d5583720162d3a5d1954ae8a13a.632f0615.png)

### 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** で転送の結果を確認できます。

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

## 'td' コマンドのインストール

最新の [Treasure Data Toolbelt](http://docs.treasuredata.com/display/PD/TD+Toolbelt+Reference) をインストールします。

## シード設定ファイルの作成（seed.yml）


```yaml
in:
  access_token: EAAZAB0rX...EOdIc5YqAZDZD
  type: instagram_insight
  facebook_page_name: 172411252833693
  data_type: user
  incremental: true
  since: 2020-03-20
  until: 2020-04-10
  use_individual_metrics: true
  incremental_user_metrics:
    - value: email_contacts-day
    - value: impressions-days_28
out:
  mode: append
```

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

| Config key | Type | Required | Description |
|  --- | --- | --- | --- |
| `access_token` | string | yes | Facebook の長期間有効なユーザーアクセストークン。 |
| `facebook_page_name` | string | yes | Instagram Business アカウントにリンクされている Facebook ページ ID。 |
| `data_type` | string | yes | `user, media, comments, media_list or tags` |
| `use_individual_metrics` | boolean | no | インポートするメトリクスデータを手動で選択するオプション。 |
| `incremental_user_preset_metric` | string | no | 増分ロードが `true` に設定されている場合の User プリセットメトリクス |
| `incremental_user_metrics` | array | no | 増分ロードが `true` に設定されている場合にインポートする User メトリクス |
| `non_incremental_user_preset_metric` | string | no | 増分ロードが `false` に設定されている場合にインポートする User プリセットメトリクス |
| `non_incremental_user_metrics` | array | no | 増分ロードが `false` に設定されている場合にインポートする User メトリクス |
| `media_metrics` | array | no | 転送する個別の Media メトリクスを選択 |
| `media_preset_metric` | string | no | 転送する Media プリセットメトリクスを選択 |
| `incremental` | boolean | no | 繰り返し実行される場合、最後のインポート以降のデータのみが収集されます。 |
| `since` | string | no | この日付以降のデータのみをインポートします。Date Range Import を参照してください |
| `until` | string | no | この日付までのデータのみをインポートします |
| `throttle_wait_in_millis` | int | no | API 制限に達すると、Facebook は API 呼び出しをスロットル（ブロック）します。API を再度呼び出す前に、指定された時間だけ待つ必要があります。デフォルト：3600000 |
| `maximum_retries` | int | no | 各 API 呼び出しの最大リトライ回数を指定します。デフォルト：3 |
| `initial_retry_interval_millis` | int | no | 最初のリトライの待機時間を指定します。デフォルト：20000 |
| `maximum_retries_interval_millis` | int | no | リトライ間の最大時間を指定します。デフォルト：120000 |
| `connect_timeout_in_millis` | int | no | API 呼び出しを行う際に接続がタイムアウトするまでの時間を指定します。デフォルト：30000 |
| `idle_timeout_in_millis` | int | not | プール内で接続がアイドル状態を維持できる時間を指定します。デフォルト：60000 |


利用可能な `out` モードの詳細については、[Appendix](/ja/int/instagram-user-and-media-insights-import-integration#InstagramUserandMediaInsightsImportIntegration-ModesfortheOutPlugin) を参照してください。

## フィールドの推測（load.yml の生成）

`connector:guess` を使用します。このコマンドは、対象データを自動的に読み取り、欠落している部分をインテリジェントに推測します。


```bash
$ td connector:guess seed.yml -o load.yml
```

`load.yml` ファイルを開くと、推測された設定が表示されます。


```
---in:  access_token: EAAZA.....dIc5YqAZDZD  type: instagram_insight  facebook_page_name: '172411252833693'  data_type: user  incremental: true  since: '2020-03-20'  until: '2020-04-10'  use_individual_metrics: true  incremental_user_metrics:  - {value: email_contacts-day}  - {value: impressions-days_28}out: {mode: append}exec: {}filters:- from_value: {mode: upload_time}  to_column: {name: time}  type: add_time
```

次に、`preview` コマンドを使用してデータをプレビューできます。


```
$ td connector:preview load.yml
```

## ロードジョブの実行

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


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

上記のコマンドは、すでに *database(td_sample_db)* と *table(td_sample_table)* を作成していることを前提としています。データベースまたはテーブルが TD に存在しない場合、このコマンドは成功しませんので、データベースとテーブルを[手動で](https://support.treasuredata.com/hc/en-us/articles/360001266348-Database-and-Table-Management)作成するか、`td connector:issue` コマンドで `--auto-create-table` オプションを使用してデータベースとテーブルを自動的に作成します。


```
$ td connector:issue load.yml --database td_sample_db --table td_sample_table --time-column created_at --auto-create-table
```

「--time-column」オプションで、時刻フォーマット列を「パーティショニングキー」に割り当てることができます。

# スケジュール実行

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

## スケジュールの作成

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


```
$ td connector:create \    daily_users_import \    "10 0 * * *" \    td_sample_db \    td_sample_table \    load.yml
```

`cron` パラメータは、`@hourly`、`@daily`、`@monthly` の3つの特別なオプションも受け付けます。

## インクリメンタルスケジューリング

`incremental` オプションを設定することで、レコードを段階的にロードできます。


```
in: type: instagram_insight ... incremental: trueout: mode: append
```

スケジュール実行を使用している場合、コネクタは最後のインポート時刻 `time_created` 値を自動的に保存し、内部で保持します。そして、次回のスケジュール実行時に使用されます。


```
in:  type: instagram_insight  ...out:  ...Config Diff---in:  time_created: '2020-02-02T15:46:25Z'
```

## スケジュールの一覧表示

スケジュールされたエントリのリストは、`td connector:list` で確認できます。


```
$ td connector:list
```

## スケジュールの設定と履歴の表示

`td connector:show` は、スケジュールエントリの実行設定を表示します。


```
$ td connector:show daily_leads_import
```

`td connector:history` は、スケジュールエントリの実行履歴を表示します。個々の実行結果を調査するには、`td job jobid` を使用します。

## スケジュールの削除

`td connector:delete` は、スケジュールを削除します。


```
$ td connector:delete daily_users_import
```

# Out プラグインのモード

load.yml ファイルの out セクションでファイルインポートモードを指定できます。

out: セクションは、データが Treasure Data テーブルにどのようにインポートされるかを制御します。
たとえば、Treasure Data の既存のテーブルにデータを追加するか、データを置き換えるかを選択できます。

| **モード** | **説明** | **例** |
|  --- | --- | --- |
| Append | レコードは対象テーブルに追加されます。 | `in:   ... out:   mode: append` |
| Always Replace | 対象テーブルのデータを置き換えます。対象テーブルに対して手動で行われたスキーマ変更はそのまま保持されます。 | `in:   ... out:   mode: replace` |
| Replace on new data | 新しいデータがインポートされる場合にのみ、対象テーブルのデータを置き換えます。 | `in:   ... out:   mode: replace_on_new_data` |