# SendGrid Import Integration

この機能はベータ版です。詳細については、カスタマーサクセス担当者にお問い合わせください。

SendGridは、ユーザーがメールサーバーを維持することなくメールを送信できるクラウドベースのSMTPプロバイダーです。このIntegrationにより、TDユーザーはSendGrid上で作成されたキャンペーンの応答イベントとパフォーマンスメトリクスを収集できます。また、コンタクト、シングルセンド、メッセージなどの他のマーケティングデータの収集も可能です。

## 前提条件

- Treasure Dataの知識
- SendGridの知識


## 要件と制限事項

SendGridのAPIキーが必要です。[API Key](https://app.sendgrid.com/settings/api_keys)を参照してください。

## Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/)

## TD Console経由でSendGridへの接続を確立する

### Authenticationの作成

SendGridへの新しいAuthenticationを作成するには、次の手順に従います。

1. **Integrations Hub**から**Catalog**を開きます。
2. Catalogで**SendGrid**を検索します。
3. **Create Authentication**を選択します。**API Key**を入力して、Authenticationを保存します。


### SendGridからContactsをインポートする

SendGridからContactsをインポートするには、次の手順に従います。

#### AuthenticationからNew Sourceを作成する

1. TD Consoleを開きます。
2. **Integrations Hub** > **Authentications**に移動します。
3. 新しいAuthenticationを見つけて、**New Source**を選択します。


#### Source Table Configuration - Contacts

Contactsのインポートジョブを設定するために、次の設定パラメータを定義します。

![](/assets/contacts.0994d79604a63f84baf95a8ee0bf325e02154c247a0f170aebb8617b75ca17bc.860beb6b.png)

| パラメータ | 説明 |
|  --- | --- |
| Type | インポートするデータのタイプ。**Contacts**を選択します。 |
| Sub-type | インポートするデータのサブタイプ。ユーザーは次のいずれかを選択できます：   - **All Contacts**: すべてのコンタクトをインポートします。 - **Lists**: リスト内のコンタクトのみを取得します。 - **Segments**: セグメント内のコンタクトを取得します。 |
| List Name | Listsの場合のみ。フィルタリングするリストの名前を入力します。 |
| Segment Name | Segmentsの場合のみ。フィルタリングするセグメントの名前を入力します。 |
| Max Wait Time | SendGridがデータファイルを生成するための最大待機時間(分単位)。 |


**Next**を選択します。

#### Define Data Settings

Integrationは、SendGridによって定義された標準コンタクトスキーマのフィールドを表示します。

**Next**を選択します。

#### データのプレビュー

SendGridは、コンタクトファイルの準備と生成のプロセスを処理します。タイムアウトを避けるために、Integrationはダミーデータのみを表示します。

データプレビューはオプションであり、必要に応じて**Next**をクリックしてダイアログの次のページに安全に進むことができます。

1. **Generate Preview**を選択して、インポートを実行する前にデータのプレビューを表示します。


データプレビューに表示されるデータは、ソースから概算されたものです。インポートされる実際のデータではありません。

1. データが期待どおりに見えることを確認します。
![](/assets/snippet-data-preview-2024-02-09.27dc5fd8772fca4f7f44ab28c00476ae1894744fe1e75d06932628929cc7bff1.4e139be3.png)
2. **Next**を選択します。


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

### SendGridから統計情報をインポートする

SendGridから統計情報を取得するためのサンプル設定に従います

![](/assets/global_stats.41ebecbebeac05fd1af9a91ab22eedf7abe9ffb95b8d4e42ffe8edecfc3e7a19.860beb6b.png)

#### Source Table Configuration - Global Email Statistics

| パラメータ | 説明 |
|  --- | --- |
| Type | インポートするデータのタイプ。**Statistic**を選択します。 |
| Sub-type | インポートするデータのサブタイプ。ユーザーは次のいずれかを選択できます：  **Global Email Stats**: 送信されたすべてのメールからの統計をインポートします。  **SingleSend Stats**: シングルセンド別の統計をインポートします。  **Automation Stats**: オートメーション別の統計をインポートします。 |
| Start Date - End Date | **Global Email Stats**の場合のみ利用可能。日付でフィルタリングします。Start Dateは必須です。 |
| Aggregated by | **Global Email Stats**の場合のみ利用可能。データの集計方法を定義します*(Day、Week、Month、None)*。 |
| Incremental | **Global Email Stats**の場合のみ利用可能。繰り返し実行の場合、次の時間枠内のデータのみを検索します。 |


### SendGridからSuppressionsをインポートする

SendGridからSuppressionsイベントを取得するためのサンプル設定に従います。Integrationは次をサポートします：

- Bounces
- Unsubscribes
- Blocks
- Spam Reports
- Invalid


#### Source Table Configuration - Suppressions

![](/assets/suppression.02ec755685e2d1f25d701f82454c9b48491d58e55d6b34f128a87a206d561f42.860beb6b.png)

| パラメータ | 説明 |
|  --- | --- |
| Type | インポートするデータのタイプ。**Suppressions**を選択します。 |
| Start Time - End Time | 検索期間を定義します。Incrementalがオンの場合、Start Timeは必須です。 |
| On behalf of | (オプション)サブユーザーまたは顧客アカウントからデータを取得するために使用します。 |
| Incremental | 繰り返し実行の場合、次の時間枠内のデータのみを検索します。 |


#### Data Schema - Suppressions

SendGridからのデータ定義はSuppressionタイプによって異なるため、以下はTDに取り込まれる際のデータスキーマです。


```
type;created;email;reason;status;ipblock;1714970265;testemail4@email.com;blockreason;blockstatus;nullinvalid;1714970265;testemail5@email.com;dummyreason;null;nullbounce;1714970265;testemail@email.com;550 Inconsistent;550;nullspam_report;1714970265;testemail2@email.com;null;null;192.168.1.1unsubscribe;1714970265;testemail3@email.com;null;null;null
```

### SendGridからSingle SendsをインポートSingle

SendGridからSingle Sendsデータをインポートするには、次の手順に従います。

#### Source Table Configuration - Single Send

![](/assets/singlesend.f4a91c42e189e81cd6b653a5b5465a46858b8203ec0e4bc43b78bbf448fa80e1.860beb6b.png)

### SendGridからMessage Dataをインポートする

SendGridからMessage Dataをインポートするには、次の手順に従います。

#### Source Table Configuration - Message Data

![](/assets/screen-shot-2024-06-25-at-19.25.36.dceb9bc695540dc431a58d290ccf3de235564c67d9f2083cdc3b2abf5b36cf18.860beb6b.png)

| パラメータ | 説明 |
|  --- | --- |
| Type | インポートするデータのタイプ。**Message Data**を選択します。 |
| Query | クエリでフィルタリングします。[クエリ構文](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/getting-started-email-activity-api#query-reference)を参照してください。 |


## Workflow経由でSendGridからインポートする

WorkflowのTD_load>: operatorを使用して、SendGridからデータをインポートできます。すでにSOURCEを作成している場合は実行できます。作成したくない場合は、ymlファイルを使用してインポートできます。

### Sourceを使用する

1. Sourceを特定します。
2. Unique IDを取得するには、SourceリストをSendGridでフィルタリングします。
3. メニューを開き、**Copy Unique ID**を選択します。


![](/assets/26617502.09d9b84b0f1f752c7c95b0bc1c2d8e8b7302e5b91c6a3cb5f01309dadf53a604.25ec5a77.png)

1. td_load > operatorを使用してWorkflowタスクを定義します。



```yaml
+load:
  td_load>: unique_id_of_your_source
  database: ${td.dest_db}
  table: ${td.dest_table}
```

1. Workflowを実行します。


### Yamlファイルを使用する

1. ymlファイルを特定します。ymlファイルを作成する必要がある場合は、参考として[Amazon S3 Import Integration Using CLI](https://docs.treasuredata.com/display/INT/Amazon+S3+Import+Integration+Using+CLI)を確認してください。
2. td_load > operatorを使用してWorkflowタスクを定義します。



```yaml
+load:
  td_load>: config/daily_load.yml
  database: ${td.dest_db}
  table: ${td.dest_table}
```

1. Workflowを実行します。


#### パラメータリファレンス

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | Integrationタイプ | sendgrid | sendgrid | Yes |
| api_key | 接続用のAPIキー | N/A | N/A | Yes |
| data_type | 取得するデータタイプ | statistic  suppressions  contacts  message_data  single_sends | statistic | Yes |
| sub_type_statistic | 統計のサブタイプ | global_email_stats  single_send_stats  automation_stats | global_email_stats | No |
| sub_type_contacts | コンタクトのサブタイプ | all_contacts  lists  segments | all_contacts | No |
| start_date | `all_contacts`の開始日 | String |  | `incremental_statistics`がtrueの場合のみ必須 |
| end_date | `all_contacts`の終了日 | String |  | No |
| aggregated_by | `all_contacts`の集計方法 | day  week  month  year | day | No |
| incremental_statistics | `all_contacts`の増分モード | true  false | true | No |
| start_time | data_type `suppressions`の開始時刻 | ​  String |  | No |
| end_time | data_type `suppressions`の終了時刻 | String |  | No |
| incremental_suppressions | `suppressions`の増分モード | true  false | true | No |
| on_behalf_of | サブユーザーまたは顧客アカウントからデータを取得するために使用します。 | String |  | No |
| sub_type_contacts | コンタクトのサブタイプ | all_contacts  lists  segments | all_contacts | No |
| list_name | コンタクトのリストの名前 | カンマで区切られた文字列のリスト |  | `sub_type_contacts `がlistsの場合は必須 |
| segment_name | コンタクトのセグメントの名前 | カンマで区切られた文字列のリスト |  | `sub_type_contacts `がsegmentsの場合は必須 |
| max_wait_time | コンタクトをエクスポートするための最大待機時間(分単位) | Integer | 5 | No |
| query | `message_data`のクエリ | String |  | No |
| maximum_retries | 最大リトライ回数 | Integer | 5 | No |
| initial_retry_interval_millis | 初回リトライ待機時間(ミリ秒単位) | Integer | 500 | No |
| maximum_retry_interval_millis | 最大リトライ待機時間(ミリ秒単位) | Integer | 30000 | No |
| columns | カラム定義 | Json |  | Yes |


### サンプルWorkflowコード

サンプルWorkflowコードについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/s3)を参照してください。

## CLI(Toolbelt)経由でSendGridからインポートする

Integrationを設定する前に、最新の[TD Toolbelt](https://toolbelt.treasuredata.com/)をインストールしてください。

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


```yaml
in:
 type: sendgrid
 api_key: XXXXXXXXXX
 data_type: contacts
 sub_type_statistic: global_emal_stats
 sub_type_contacts: list
 start_time: '2023-01-19-T00:51:29.937Z'
 end_time: '2023-01-19-T00:51:29.937Z'
 start_date: '2023-01-01'
 end_date: '2023-01-01'
 aggregated_by: day
 query: to_email="dumy@gmail.com"
 list_name: 'abc,def'
 segment_name: 'abc,def'
 incremental_statistic: true
 incremental_suppressions: true
 max_wait_time: 5
 on_behalf_of: xxx
 initial_retry_interval_millis: 500
 maximum_retries: 5
 maximum_retry_interval_millis: 30000
out:
  mode: append
```

### パラメータリファレンス

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | Integrationタイプ | sendgrid | sendgrid | Yes |
| api_key | 接続用のAPIキー | N/A | N/A | Yes |
| data_type | 取得するデータタイプ | statistic  suppressions  contacts  message_data  single_sends | statistic | Yes |
| sub_type_statistic | 統計のサブタイプ | global_email_stats  single_send_stats  automation_stats | global_email_stats | No |
| sub_type_contacts | コンタクトのサブタイプ | all_contacts  lists  segments | all_contacts | No |
| start_date | `all_contacts`の開始日 | String |  | `incremental_statistics`がtrueの場合のみ必須 |
| end_date | `all_contacts`の終了日 | String |  | No |
| aggregated_by | `all_contacts`の集計方法 | day  week  month  year | day | No |
| incremental_statistics | `all_contacts`の増分モード | true  false | true | No |
| start_time | data_type `suppressions`の開始時刻 | String |  | No |
| end_time | data_type `suppressions`の終了時刻 | String |  | No |
| incremental_suppressions | `suppressions`の増分モード | true  false | true | No |
| on_behalf_of | サブユーザーまたは顧客アカウントからデータを取得するために使用します。 | String |  | No |
| sub_type_contacts | コンタクトのサブタイプ | all_contacts  lists  segments | all_contacts | No |
| list_name | コンタクトのリストの名前 | カンマで区切られた文字列のリスト |  | `sub_type_contacts `がlistsの場合は必須 |
| segment_name | コンタクトのセグメントの名前 | カンマで区切られた文字列のリスト |  | `sub_type_contacts `がsegmentsの場合は必須 |
| max_wait_time | コンタクトをエクスポートするための最大待機時間(分単位) | Integer | 5 | No |
| query | `message_data`のクエリ | String |  | No |
| maximum_retries | 最大リトライ回数 | Integer | 5 | No |
| initial_retry_interval_millis | 初回リトライ待機時間(ミリ秒単位) | Integer | 500 | No |
| maximum_retry_interval_millis | 最大リトライ待機時間(ミリ秒単位) | Integer | 30000 | No |


Data Integrationは、指定されたprefixに一致するすべてのファイルをインポートします。

- 例


path_prefix: path/to/sample_ –> path/to/sample_201501.csv.gz, path/to/sample_201502.csv.gz, …, path/to/sample_201505.csv.gz

### load.ymlの生成

*connector:guess*を使用します。このコマンドは自動的にソースファイルを読み取り、ロジックを使用してファイル形式とそのフィールド/カラムを推測します。


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

load.ymlを開いて、ファイル形式、エンコーディング、カラム名、タイプの定義を確認できます。

#### 例


```yaml
in:
  type: sendgrid
  api_key: XXXXXXXXXX
  data_type: contacts
  sub_type_statistic: global_emal_stats
  sub_type_contacts: list
  start_time: '2023-01-19-T00:51:29.937Z'
  end_time: '2023-01-19-T00:51:29.937Z'
  start_date: '2023-01-01'
  end_date: '2023-01-01'
  aggregated_by: day
  query: to_email="dumy@gmail.com"
  list_name: 'abc,def'
  segment_name: 'abc,def'
  incremental_statistic: true
  incremental_suppressions: true
  max_wait_time: 5
  on_behalf_of: xxx
  initial_retry_interval_millis: 500
  maximum_retries: 5
  maximum_retry_interval_millis: 30000
  columns:
    - {name: email, type: string}
    - {name: first_name, type: string}
    - {name: last_name, type: string}
    - {name: created_at, type: timestamp, format: '%Y-%m-%dT%H:%M:%S%z'}
    - {name: date, type: timestamp, format: '%Y-%m-%d'}

  out:
    mode: append
```

データをプレビューするには、*td connector:preview*コマンドを使用します。


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

guessコマンドは、ソースデータファイル内に3行以上と2列以上が必要です。これは、コマンドがソースデータのサンプル行を使用してカラム定義を評価するためです。

システムがカラム名またはカラムタイプを予期せず検出した場合は、load.ymlファイルを変更して再度プレビューしてください。

### Load Jobの実行

1. load jobを送信します。


データサイズによっては数時間かかる場合があります。データを保存するTreasure DataのDatabaseとTableを必ず指定してください。

Treasure Dataのストレージは時間によってパーティション化されているため([data partitioning](http://docs.treasuredata.com/display/PD/Data+Partitioning+in+Treasure+Data)を参照)、Treasure Dataは*-- time-column*オプションの指定も推奨しています。このオプションが提供されない場合、data connectorは最初の*long*または*timestamp*カラムをパーティション化時間として選択します。--time-columnで指定されるカラムのタイプは、longまたはtimestampタイプのいずれかである必要があります。

データに時間カラムがない場合は、*add_time*フィルタオプションを使用して追加できます。詳細については、add_timeフィルタプラグインを参照してください。


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

connector:issueコマンドは、*database(td_sample_db)*と*table(td_sample_table)*がすでに作成されていることを前提としています。DatabaseまたはTableがTDに存在しない場合、このコマンドは失敗します。DatabaseとTableを手動で作成するか、*td connector:issue*コマンドで*--auto-create-table*オプションを使用してDatabaseとTableを自動作成してください。


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

data connectorはサーバー側でレコードをソートしません。時間ベースのパーティション化を効果的に使用するには、事前にファイル内のレコードをソートしてください。

*time*という名前のフィールドがある場合は、*--time-column*オプションを指定する必要はありません。


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

### Import Modes

load.ymlファイルのoutセクションでファイルインポートモードを指定できます。out:セクションは、データがTreasure DataのTableにインポートされる方法を制御します。例えば、データを追加したり、Treasure Data内の既存のTableのデータを置き換えたりすることができます。

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


### 実行のスケジューリング

増分ファイルインポートのために、定期的なData Integration実行をスケジュールできます。Treasure Dataは、高可用性を確保するためにスケジューラを慎重に設定しています。

スケジュールされたインポートでは、指定されたprefixに一致し、条件により次のフィールドのいずれかに該当するすべてのファイルをインポートできます：

- use_modified_timeが無効になっている場合、最後のパスが次の実行のために保存されます。Integrationは、2回目以降の実行では、アルファベット順で最後のパス以降のファイルのみをインポートします。
- それ以外の場合、ジョブの実行時間が次の実行のために保存されます。2回目以降の実行では、Integrationはその実行時間以降に変更されたファイルのみをアルファベット順でインポートします。


#### TD Toolbeltを使用したスケジュールの作成

新しいスケジュールは、*td connector:create*コマンドを使用して作成できます。


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

Treasure Dataのストレージは時間によってパーティション化されているため([data partitioning](http://docs.treasuredata.com/display/PD/Data+Partitioning+in+Treasure+Data)も参照)、Treasure Dataは*--time-column*オプションの指定も推奨しています。


```
$ td connector:create daily_import "10 0 * * *"     td_sample_db td_sample_table load.yml     --time-column created_at
```

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

デフォルトでは、スケジュールはUTCタイムゾーンで設定されます。-tまたは--timezoneオプションを使用して、タイムゾーンでスケジュールを設定できます。`--timezone`オプションは、'Asia/Tokyo'、'America/Los_Angeles'などの拡張タイムゾーン形式のみをサポートしています。PST、CSTなどのタイムゾーンの略語は*サポートされておらず*、予期しないスケジュールにつながる可能性があります。

### 関連記事

SendGrid Export Integration - [SendGrid Output](/ja/int/sendgrid-export-integration)

### 外部参照

SendGrid API - [API Reference](https://www.twilio.com/docs/sendgrid/api-reference)