# Facebook Lead Ads インポート統合 CLI

Facebook Lead Ads Connector を Facebook ページまたは広告アカウントに接続して、リードデータを Treasure Data にインポートできます。

## 前提条件

- [TD Toolbelt](https://toolbelt.treasuredata.com/) を含む Treasure Data の基本知識
- リード取得権限を持つ Facebook ページ/広告アカウント
- 認証された Treasure Data アカウントアクセス


## コマンドラインを使用して接続を作成する

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

最新の [TD Toolbelt](https://toolbelt.treasuredata.com/) をインストールします。

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

enable_guess_schema 有効:


```yaml
in:
  type: facebook_leads
  app_secret: app_secret
  access_token: long-lived-access_token
  id: 33056800448180
  time_created: '2020-01-28T15:46:25+0000'
  incremental: false
  enable_guess_schema: true
out:
  mode: append
```

enable_guess_schema 無効:


```yaml
in:
  type: facebook_leads
  app_secret: app_secret
  access_token: long-lived-access_token
  id: 33056800448180
  time_created: '2020-01-28T15:46:25+0000'
  incremental: false
  enable_guess_schema: false
  form_fields:
	- {name: ocupation, type: string}
	- {name: last_name, type: string}
	- {name: cell_Phone, type: string}
	- {name: email, type: string}
	- {name: name, type: string}
	- {name: opt_in_marketing, type: boolean}

out:
  mode: append
```

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

| **設定キー** | **タイプ** | **必須** | **説明** |
|  --- | --- | --- | --- |
| type | string | yes | コネクタータイプ "facebook_leads" |
| app_secret | string | no | Facebook App Secret |
| access_token | string | yes | Facebook の長期有効アクセストークン。手順は[こちら](/ja/int/facebook-ads-insights-import-integration#h2__2004725160)を参照 |
| ad_account_id | string | no | Facebook 広告アカウント ID |
| id | string | yes | リードデータは広告 ID またはフォーム ID でインポートできます。広告 ID とフォーム ID の取得方法の詳細については、[付録](/ja/int/facebook-lead-ads-import-integration-cli#h1__1835053169)を参照してください |
| time_created | string | no | この時刻から現在時刻までに送信されたリードデータをインポートします。このフィールドは ISO 8601 日時形式を受け付けます。例: 2020-01-01T00:00:00+0700 |
| incremental | boolean | no | 毎回新しいデータのみをインポートします。[インクリメンタルの仕組み](http://docs.treasuredata.com/display/PD/Facebook+Lead+Ads+Import+Integration+Beta#How-Incremental-Loading-Works)を参照 |
| form_fields | array | no | enable_guess_schema=false の場合に必須。Facebook リードフォームのフィールド名とそのデータタイプ |
| - name | string | yes | フォームフィールド名。[リードのフォームフィールドの見つけ方](https://tddocs.atlassian.net/wiki/spaces/CW/pages/826835011/Facebook+Lead+Ads+Import+Integration#How-to-get-the-Lead-Form%E2%80%99s-Field-Name)については付録を参照 |
| - type | string | yes | フィールドのデータタイプ |
| - format | string | no | タイムスタンプ形式。例: %Y-%m-%dT%H:%M:%S%z |
| - skip_invalid_records | boolean | no | 無効なリードデータをスキップして、他のデータのインポートを続行します。選択しない場合、無効なデータが検出されるとジョブが失敗します |


利用可能な `out` モードの詳細については、[付録](/ja/int/facebook-lead-ads-import-integration-cli#h1__1835053169)を参照してください。

### フィールドの推測 (load.yml の生成)

`connector:guess` を使用します。このコマンドは、ターゲットデータを自動的に読み取り、データ形式をインテリジェントに推測します。


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

`load.yml` ファイルを開くと、列名、データタイプ、形式を含む推測されたファイル形式定義が表示されます。


```yaml
---
in:
  type: facebook_leads
  app_secret: app_secret
  access_token: long-lived-access_token
  id: 514618966066498
  time_created: '2019-12-01T15:46:25+0000'
  incremental: false
  columns:
  - {name: id, type: long}
  - {name: created_time, type: timestamp, format: "%Y-%m-%dT%H:%M:%S%z"}
  - {name: ad_id, type: string}
  - {name: ad_name, type: string}
  - {name: adset_id, type: string}
  - {name: adset_name, type: string}
  - {name: campaign_id, type: string}
  - {name: campaign_name, type: string}
  - {name: form_id, type: long}
  - {name: platform, type: string}
  - {name: is_organic, type: boolean}
  - {name: name, type: string}
  - {name: surname, type: string}
  - {name: email, type: string}
out: {mode: append}
exec: {}
filters:
- from_value: {mode: upload_time}
  to_column: {name: time}
  type: add_time
```

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


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

システムが列タイプを予期せず検出した場合は、`load.yml` を直接変更して再度プレビューしてください。

データコネクタは、"boolean"、"long"、"double"、"string"、"timestamp" タイプの解析をサポートしています。

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

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


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

上記のコマンドは、すでに *database(td_sample_db)* と *table(td_sample_table)* を作成していることを前提としています。データベースまたはテーブルが TD に存在しない場合、このコマンドは成功しないため、[手動で](https://docs.treasuredata.com/smart/project-product-documentation/data-management)データベースとテーブルを作成するか、次を使用してください:

- `-auto-create-table`


`td connector:issue` コマンドでこのオプションを使用すると、データベースとテーブルが自動的に作成されます:


```bash
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_leads_import \
    "10 0 * * *" \
    td_sample_db \
    td_sample_table \
    load.yml
```

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

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

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


```
in:
 type: facebook_leads
 app_secret: app_secret
 access_token: long-lived-access_token
 id: 33056800448180
 time_created: '2020-01-28T15:46:25+0000'
 incremental: true
out:
 mode: append
```

[スケジュール実行](http://docs.treasuredata.com/display/PD/Facebook+Lead+Ads+Import+Integration+Beta#Scheduled-Execution)を使用している場合、コネクタは最後のインポート時刻 `time_created` 値を自動的に保存し、内部で保持します。その後、次のスケジュール実行時に使用されます。


```
in:
  type: facebook_leads
  ...
out:
  ...

Config Diff
---
in:
  time_created: '2020-02-02T15:46:25Z'
```

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

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


```
td connector:list
```

## Facebook Lead Ads からのインポートに関する FAQ

**このコネクタにはどの Facebook アプリのスコープまたは権限が必要ですか？**

- 以下の権限が必要です:
  - email
  - public_profile
  - leads_retrieval
  - pages_manage_ads、pages_manage_metadata、pages_read_engagement、pages_read_user_content (フォーム ID でインポートする場合)
  - ads_management (広告 ID でインポートする場合)


### インクリメンタルロードの仕組み

`incremental: true` が設定されている場合、このコネクタは **time_created** が設定されている場合は **time_created** 以降に作成されたすべてのレコードをロードし、**time_created** が設定されていない場合は現在時刻まで利用可能なすべてのデータをインポートします。次のジョブ実行では、最後のジョブ実行以降に作成されたレコードのみがインポートされます。このモードは、前回のスケジュール実行以降に作成されたリードのみを取得したい場合に便利です。

たとえば、最初のジョブ実行で次のように設定を指定したとします:


```
in:
 ...
 time_created: '2020-01-28T15:46:25+0000'
 incremental: true
```

バルクデータロードが正常に完了すると、**time_created**: パラメータが出力されます。例: '2020-02-02T15:46:25+0000' が config-diff として出力され、次回の実行で使用されます。
次の実行時に、**time_created**: も設定されている場合、このプラグインは config-diff からの **time_created** を使用し、元の値を無視します。新しいジョブ設定は次のように実行されます:


```
in:
 ...
 time_created: '2020-02-02T15:46:25+0000'
 incremental: true
```

このようにして、ジョブが実行されるたびに、新しいレコードのみがインポートされます。

広告アカウントレベルのリードインポート (ad_account_id を設定することによる) の場合、リード広告 ID のリストとその最新の **time_created** が、次のジョブ実行のために config-diff として保存されます。例:


```
in:
  ...
  incremental: true
  list_time_created: {
	'23845900031': '2020-11-01T02:46:45Z',
	'23845899651': '2020-11-02T21:25:33Z',
	'23846121121': '2020-11-30T05:21:03Z',
	'23845899651': '2020-11-01T12:39:53Z',
	'23845900031': '2020-11-02T04:13:19Z',
	'23845899651': '2020-11-04T01:39:58Z'
}
```