# Amazon S3 Export Integration V2

Amazon Simple Storage Service (Amazon S3)は、スケーラビリティ、データの可用性、セキュリティ、パフォーマンスを提供するオブジェクトストレージサービスです。Amazon S3は、ビジネス、組織、コンプライアンス要件に対応するデータ編成とアクセス制御の構成機能を提供します。

このTD export integrationを使用すると、Treasure Dataからジョブ結果を直接Amazon S3に書き込むことができます。

# この統合で何ができますか?

- **データの保存**: バケットに無制限のデータを保存できます。


# Amazon S3 Export Integration v2とv1の違い

次の表の情報を確認して、v1では利用できないがv2で利用可能な機能を理解してください。

| Feature | Amazon S3 v2 | Amazon S3 v1 |
|  --- | --- | --- |
| AWS Key Management Serviceに保存されているCustomer Master Key (CMK)を使用したServer-side Encryption | **X** |  |
| 出力データ形式のQuote Policyのサポート | **X** |  |
| Assume Role認証方法のサポート | **X** |  |


# 前提条件

- IAM Userの以下のAWS権限:
  - s3:PutObject、s3:AbortMultipartUpload権限
  - sse-kms設定を選択する場合のkms:Decrypt、kms:GenerateDataKey権限
- (オプション) Treasure Dataの基本的な知識（[TD Toolbelt](https://toolbelt.treasuredata.com/)を含む）


# 要件と制限

- S3へのエクスポートのデフォルトのクエリ結果制限は100GBです。パートサイズ設定を最大5000 (MB)まで構成できます。ファイル制限は約5TBになります。
- デフォルトのエクスポート形式は[CSV RFC 4180](http://www.ietf.org/rfc/rfc4180.txt)です。
- TSVおよびJSONL形式での出力もサポートされています。
- TLS v.1.2サポート


## 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/)

# S3 Server-Side Encryptionについて

[AWS S3 Server-Side Encryption](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)を使用してアップロードデータを暗号化できます。暗号化キーを準備する必要はありません。データは、256ビットAdvanced Encryption Standard (AES-256)でサーバー側で暗号化されます。

バケットに保存されているすべてのオブジェクトにサーバー側の暗号化が必要な場合は、Server-Side Encryptionバケットポリシーを使用してください。サーバー側の暗号化が有効になっている場合、SSEオプションをオンにする必要はありません。ただし、暗号化情報なしのHTTPリクエストを拒否するバケットポリシーがある場合、ジョブ結果が失敗する可能性があります。

# KMS Server-Side Encryptionについて

[Amazon S3-managed encryption keys (SSE-S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.md)を使用してアップロードデータを暗号化できます。

Amazon S3でサーバー側の暗号化にAWS KMSを有効にする場合:

- KMS Key IDを入力しない場合、デフォルトのKMSキーを使用(または作成)します。
- KMS Key IDを入力する場合は、対称CMK(非対称CMKではない)を選択する必要があります。
- AWS KMS CMKは、バケットと同じリージョンにある必要があります。


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

Treasure Dataでは、クエリを実行する前にデータ接続を作成して構成する必要があります。データ接続の一部として、統合にアクセスするための認証を提供します。

## 新しい認証を作成する

1. **TD Console**を開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. **S3 v2**を検索し、Amazon S3 (v2)を選択します。
4. **Create Authentication**を選択します。


新しいAuthenticationダイアログが開きます。選択した認証方法に応じて、ダイアログは次の画面のいずれかのように表示される場合があります:

![](/assets/amazon-s3-export-integration-v2-2024-02-15.1d9a8ec404f403a763a2c934f779a513b65d4b3f03cd2e171d79d966d294837d.171c1d35.png)

![](/assets/amazon-s3-export-integration-v2-2024-02-15-1.050a298169ce08caf7c99a16d193856dae5d6cea7efbdd822f041153e3c8ed01.171c1d35.png)

![](/assets/amazon-s3-export-integration-v2-2024-02-15-2.5225461c69eb5f1bc44f167d9a7384558af3c18bb689aeb460c9afcaf0209339.171c1d35.png)

1. 認証フィールドを構成し、**Continue**を選択します。


| Parameter | Description |  |
|  --- | --- | --- |
| **Endpoint** | S3サービスエンドポイントのオーバーライド。リージョンとエンドポイント情報は[AWS service endpoints](http://docs.aws.amazon.com/general/latest/gr/rande.md#s3_region)ドキュメントから確認できます。(例: [*s3.ap-northeast-1.amazonaws.com*](https://s3.ap-northeast-1.amazonaws.com/))   `指定された場合、リージョン設定を上書きします。` |  |
| **Region** | AWSリージョン |  |
| **Authentication Method** | **basic** | - access_key_idとsecret_access_keyを使用して認証します。[AWS Programmatic access](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.md)を参照してください。    - Access Key ID   - Secret access key

 |
| **session (推奨)** |  | - 一時的に生成されたaccess_key_id、secret_access_key、session_tokenを使用します。    - Access Key ID   - Secret access key   - Secret token

 |
| **assume_role** |  | - ロールアクセスを使用します。[See AWS AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.md)    - TD's Instance Profile   - Account ID   - Your Role Name   - External ID   - Duration In Seconds

 |
| **anonymous** | サポートされていません |  |
| **Access Key ID** | AWS S3発行 |  |
| **Secret Access Key** | AWS S3発行 |  |
| **Secret token** |  |  |
| **TD's Instance Profile** | この値はTD Consoleによって提供されます。値の数値部分は、IAMロールを作成するときに使用するAccount IDを構成します。 |  |
| **Account ID** | あなたのAWS Account ID |  |
| **Your Role Name** | あなたのAWS Role Name |  |
| **External ID** | あなたのSecret External ID |  |
| **Duration In Seconds** | 一時的な認証情報の期間 |  |


1. 新しいAWS S3接続に名前を付け、**Done**を選択します。


## assume_role認証方法で認証を作成する

1. assume_role認証方法で新しい認証を作成します。
2. TD's Instance Profileフィールドの値の数値部分をメモします。


![](/assets/amazon-s3-export-integration-v2-2024-02-15-3.ecacbc8dde8f7cebf4314d73857ce604d7d1deeb3e683fbc4407bb65f57f1eb5.171c1d35.png)

1. AWS IAMロールを作成します。


![](/assets/amazon-s3-export-integration-v2-2024-02-15-4.c3318f41679913c611345bbc7835e87ff9765754181deca987f3019d9dc8ce4c.171c1d35.png)

![](/assets/amazon-s3-export-integration-v2-2024-02-15-5.464d3818d7493ffeadab3015d5345f6786e2f43d5e172216fc28e203662d748b.171c1d35.png)

# クエリを定義する

1. **Export Results**を選択します。
2. 既存の認証を選択するか、出力に使用する外部サービスの新しい認証を作成できます。次のいずれかを選択します:


- Use Existing Integration
- Create a New Integration


(オプション) Amazon S3へのエクスポート情報を指定します。

![](/assets/amazons3expresult.61ded1d357d58fa5b1d872915b527101252359eaba88fbdc7723100b754b69cd.171c1d35.png)

| Field | Description |
|  --- | --- |
| Is user directory Root? | 選択した場合、ユーザーディレクトリはルートディレクトリとして扱われます。(例: '/home/treasure-data'を'/'として) |
| Path prefix: | ファイルが保存されるファイルパス |
| Rename file after upload finish | 選択した場合、SFTP result outputは、すべてのデータが転送された後、リモートSFTPサーバー上のファイル名を".xxx.tmp"から".xxx"に変更します。一部のMAツールは、特定の名前のファイルがSFTPサーバーに存在する場合にデータのインポートを試みます。temp nameオプションはそのような場合に便利です。 |
| Format | エクスポートされるファイルの形式:   - csv (comma separated) - tsv (tab separated) - jsonl |
| Compression | エクスポートされるファイルの圧縮形式:   - None - GZ - bzip2 |
| Header line? | 最初の行として列名を含むヘッダー行 |
| Delimiter | 区切り文字:   - Default - , - Tab - |
| Quote policy | 引用符のポリシー:   - ALL - MINIMAL: 区切り文字、引用符、または行終端文字のいずれかを含むフィールドにのみ引用符文字を追加します。 - NONE |
| Null string | クエリ結果のnull値の表示方法:   - Default - empty string - \N - NULL - null |
| End-of-line character | EOL (end-of-line)文字:   - CRLF - LF - CR |
| Temp filesize threshold | ローカル一時ファイルの最大ファイルサイズ(バイト単位)。一時ファイルがしきい値に達すると、ファイルはリモートファイルにフラッシュされます。`channel is broken`エラーが発生した場合は、このオプションの値を減らしてエラーを解決してください。 |


## S3の統合エクスポートパラメータを定義する

1. 追加のExport Resultsの詳細を定義し、コンテンツで統合パラメータを確認します。
例えば、Export Results画面が異なる場合や、記入する追加の詳細がない場合があります。


![](/assets/amazons3expresult.61ded1d357d58fa5b1d872915b527101252359eaba88fbdc7723100b754b69cd.171c1d35.png)

1. **Done**を選択します。
2. クエリを実行します
3. データが指定した宛先に移動したことを検証します。


| Parameter | Data Type | Required? | Supported in V1? | Description |
|  --- | --- | --- | --- | --- |
| Server-side Encryption | String |  | yes、sse-s3のみ | サポート値:   - sse-s3: Server-side Encryption Mode - sse-kms: 新しいSSE Mode |
| Server-side Encryption Algorithm | String |  | yes | サポート値:   - AES256 |
| KMS Key ID | String |  | no | 対称AWS KMS Key ID。KMS Key IDの入力がない場合、デフォルトのKMS Keyを作成/使用します。 |
| Bucket | String | yes | yes | S3バケット名を指定します(例: your_bucket_name)。 |
| Path | String | yes | yes | s3ファイル名(オブジェクトキー)を指定し、拡張子を含めます(例: test.csv)。 |
| Format | String |  | yes | エクスポートされるファイルの形式: *csv*、*tsv、jsonl* |
| Compression | String |  | yes | エクスポートされるファイルの圧縮形式*(例: None or gz)* |
| Header | Boolean |  | yes | エクスポートされるファイルにヘッダーを含めます。 |
| Delimiter | String |  | yes | 区切り文字を指定するために使用*(例: (comma))* |
| String for NULL values | String |  | yes | null値に挿入するプレースホルダー*(例: Empty String)* |
| End-of-line character | String |  | yes | EOL(End-Of-Line)表現を指定*(例: CRLF、LF)* |
| Quote Policy | String |  | no | 引用符で囲むフィールドタイプを決定するために使用します。サポート値:    - ALL    すべてのフィールドを引用符で囲みます - MINIMAL    区切り文字、引用符、または行終端文字のいずれかを含むフィールドのみを引用符で囲みます。 - NONE    フィールドを引用符で囲みません。区切り文字がフィールド内に出現する場合は、エスケープ文字でエスケープします。   デフォルト値: MINIMAL |
| Quote character (オプション) | Char |  | yes | エクスポートされるファイルで引用符に使用される文字(例: ")。区切り文字、引用符、または行終端文字のいずれかを含むフィールドのみを引用符で囲みます。入力が1文字を超える場合、デフォルト値が使用されます。 |
| Escape character(オプション) | Char |  | yes | エクスポートされるファイルで使用されるエスケープ文字。入力が1文字を超える場合、デフォルト値が使用されます。 |
| Part Size (MB) (オプション) | Integer |  | no | マルチパートアップロードのパートサイズ。デフォルト10、最小5、最大5000 |
| JSON Columns | String |  | no | JSONとして送信する文字列列のカンマ区切りリスト |


## クエリ例


```sql
SELECT * FROM www_access
```

### (オプション) Query Export ジョブをスケジュールする

Scheduled Jobs と Result Export を使用して、指定したターゲット宛先に出力結果を定期的に書き込むことができます。

Treasure Data のスケジューラー機能は、高可用性を実現するために定期的なクエリ実行をサポートしています。

2 つの仕様が競合するスケジュール仕様を提供する場合、より頻繁に実行するよう要求する仕様が優先され、もう一方のスケジュール仕様は無視されます。

例えば、cron スケジュールが `'0 0 1 * 1'` の場合、「月の日」の仕様と「週の曜日」が矛盾します。前者の仕様は毎月 1 日の午前 0 時 (00:00) に実行することを要求し、後者の仕様は毎週月曜日の午前 0 時 (00:00) に実行することを要求するためです。後者の仕様が優先されます。

#### TD Console を使用してジョブをスケジュールする

1. **Data Workbench > Queries** に移動します
2. 新しいクエリを作成するか、既存のクエリを選択します。
3. **Schedule** の横にある None を選択します。
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| ドロップダウン値 | 説明 |
|  --- | --- |
| Custom cron... | [Custom cron... の詳細](#custom-cron-details)を参照してください。 |
| @daily (midnight) | 指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。 |
| @hourly (:00) | 毎時 00 分に実行します。 |
| None | スケジュールなし。 |


#### Custom cron... の詳細

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron 値** | **説明** |
|  --- | --- |
| `0 * * * *` | 1 時間に 1 回実行します。 |
| `0 0 * * *` | 1 日 1 回午前 0 時に実行します。 |
| `0 0 1 * *` | 毎月 1 日の午前 0 時に 1 回実行します。 |
| "" | スケジュールされた実行時刻のないジョブを作成します。 |



```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

次の名前付きエントリを使用できます:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


各フィールド間には単一のスペースが必要です。各フィールドの値は、次のもので構成できます:

| フィールド値  | 例  | 例の説明  |
|  --- | --- | --- |
| 各フィールドに対して上記で表示された制限内の単一の値。 |  |  |
| フィールドに基づく制限がないことを示すワイルドカード
`'*'`。 | `'0 0 1 * *'` | 毎月 1 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 範囲 `'2-5'`
フィールドの許可される値の範囲を示します。 | `'0 0 1-10 * *'` | 毎月 1 日から 10 日までの午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| カンマ区切りの値のリスト `'2,3,4,5'`
フィールドの許可される値のリストを示します。 | `0 0 1,11,21 * *'` | 毎月 1 日、11 日、21 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 周期性インジケータ `'*/5'`
フィールドの有効な値の範囲に基づいて、
スケジュールが実行を許可される頻度を表現します。 | `'30 */2 1 * *'` | 毎月 1 日、00:30 から 2 時間ごとに実行するようにスケジュールを設定します。
`'0 0 */5 * *'` は、毎月 5 日から 5 日ごとに午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| `'*'`
ワイルドカードを除く上記の
いずれかのカンマ区切りリストもサポートされています
`'2,*/5,8-10'` | `'0 0 5,*/10,25 * *'` | 毎月 5 日、10 日、20 日、25 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |


1. (オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。


### クエリを実行する

クエリに名前を付けて保存して実行するか、単にクエリを実行します。クエリが正常に完了すると、クエリ結果は指定された宛先に自動的にエクスポートされます。

設定エラーにより継続的に失敗するスケジュールジョブは、複数回通知された後、システム側で無効化される場合があります。

(オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。

# (オプション) Workflowで結果エクスポートを構成する

Treasure Workflow内で、このデータコネクタを使用してデータをエクスポートすることを指定できます。

詳細は[Exporting Data with Parameters](https://docs.treasuredata.com/display/PD/Exporting+Data+with+Parameters)をご覧ください。

## S3 (v2) Configuration Keys

| Name | Type | Required | Description |
|  --- | --- | --- | --- |
| bucket | String | Yes |  |
| path | String | Yes |  |
| sse_type | String |  | sse-s3, sse-kms  `  ` |
| `sse_algorithm` | String |  | `AES256` |
| `kms_key_id` | String |  |  |
| format | String |  | `csv, tsv, jsonl` |
| compression | String |  | none, gz |
| header | Boolean |  | デフォルトtrue |
| delimiter | String |  | default , \t |  |
| null_value | String |  | default, empty, \N, NULL, null |
| newline | String |  | CR, LF, CRLF |
| quote_policy | String |  | ALL, MINIMAL, NONE |
| escape | Char |  |  |
| quote | Char |  |  |
| part_size | Integer |  |  |
| json_columns | String |  |  |


## S3 (v2)のワークフロー例


```yaml
_export:
  td:
  database: td.database

+s3v2_test_export_task:
  td>: export_s3v2_test.sql
  database: ${td.database}
  result_connection: s3v2_conn
  result_settings:
    bucket: my-bucket
    path: /path/to/target.csv
    sse_type: sse-s3
    format: csv
    compression: gz
    header: false
    delimiter: default
    null_value:  empty
    newline: LF
    quote_policy: MINIMAL
    escape: '"'
    quote: '"'
    part_size: 20
    json_columns: col_map,col_array,col_json_string
```

## (オプション) CLIを使用した統合のエクスポート

単一のクエリの結果をS3バケットに出力するには、td queryコマンドに"--result option"を追加します。ジョブが完了すると、結果がS3バケットに書き込まれます。

"--result parameter"を使用してS3をエクスポートするための詳細設定を指定できます。

Assume Roleを使用した認証の作成は、コンソールUIを通じてのみサポートされています。Authentication IDを取得するには、[Reuse the existing Authentication](/ja/int/amazon-s3-import-integration-v2)の手順に従い、CLIで再利用してください

## S3 (v2)のCLIコマンド例


```bash
td query \
--result '{"type":"s3_v2","auth_method":"basic","region":"us-east-2","access_key_id": "************","secret_access_key":"***************","bucket":"bucket_name","path":"path/to/file.csv","format":"csv","compression":"none","header":true,"delimiter":"default","null_value":"default","newline":"CRLF","quote_policy":"NONE","part_size":10}' \
-w -d testdb \
"SELECT 1 as col" -T presto
```

## 既存のAuthentication IDを使用したCLIコマンド例


```bash
td query \
--result '{"type":"s3_v2","td_authentication_id": 77348,"bucket":"bucket_name","path":"path/to/file.csv","format":"csv","compression":"none","header":true,"delimiter":"default","null_value":"default","newline":"CRLF","quote_policy":"NONE","part_size":10}' \
-w -d testdb \
"SELECT 1 as col" -T presto
```