# Amazon S3 Import Integration V1 Amazon S3のimportデータコネクタを使用すると、AWS S3バケットに保存されているJSON、TSV、およびCSVファイルからデータをインポートできます。 ## 異なるAmazon S3 Import Integration - **Integration v1 vs v2**: [Amazon S3 Import Integration v2](/ja/int/amazon-s3-import-integration-v2)とv1の主な違いと利点は、assume_role認証のサポートが追加されていることです。v2とv1の違いと潜在的な利点を理解するには、次の表を参照してください。 | Authentication Method | Amazon S3 v2 | Amazon S3 v1 | | --- | --- | --- | | **basic** | **x** | **x** | | **anonymous** | | **x** | | **session** | **x** | **x** | | **assume_role** | **x** | | - **Amazon S3 - Filename Metadata Enhanced**は、v1の機能に以下の追加機能を提供します - *入力ファイル名を新しいカラムとして取り込む*オプション。ファイル名のみ(ファイルパスではない)が各レコードに追加されます。 ## 前提条件 Treasure Dataの基本的な知識が必要です。 ## S3 Bucket Policy 設定 TD リージョンと同じリージョンにある AWS S3 バケットを使用している場合、TD がバケットにアクセスする IP アドレスはプライベートで動的に変化します。アクセスを制限したい場合は、静的 IP アドレスではなく VPC の ID を指定してください。例えば、US リージョンの場合は vpc-df7066ba 経由でアクセスを設定し、Tokyo リージョンの場合は vpc-e630c182 経由、EU01 リージョンの場合は vpc-f54e6a9e 経由でアクセスを設定してください。 TD Console にログインする URL から TD Console のリージョンを確認し、URL 内のリージョンのデータコネクターを参照してください。 詳細については、[API ドキュメント](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/#s3-bucket-policy-configuration-for-export-and-import-integrations)を参照してください。 ## 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からAWS S3をインポート ## TD Console経由で接続を作成 TD Consoleを使用してデータコネクタを作成できます。 ### 新しい認証を作成 データ接続を構成する際、Integrationにアクセスするための認証を提供します。Treasure Dataでは、認証を構成してからソース情報を指定します。 1. **Integrations Hub** > **Catalog**に移動し、AWS S3を検索します。 2. **Create Authentication**を選択します 1. Amazon S3 Import V1の場合: ![](/assets/amazons3.76925fb4451d1607d39ea898d7e17d50476ebaeb9ef9b2152962f3207b76b9f5.cd73d98d.png) 2. Amazon S3 - Filename Enhance Metadataの場合 ![](/assets/amazons3filenamemetadataenhanced.3b01d21cb0899887eb2803ec7f1e90f8a067909c25a32fb90805ef5db1d6fcf1.cd73d98d.png) 3. New Authenticationダイアログが開きます。認証情報を使用して認証するには、Access key IDとSecret access keyが必要です。 ![](/assets/screenshot-2021-10-28-12.39.00.d77299ace93734d10d9235db0e63c79099f4c29fcac6d23971e9e23efbb5d0f0.cd73d98d.png) 4. 以下のパラメータを設定します。**Continue**を選択します。新しいAWS S3接続に名前を付けます。**Done**を選択します。 | Parameter | Description | | --- | --- | | **Endpoint** | - S3エンドポイントのログインユーザー名。リージョンとエンドポイント情報は[AWSドキュメント](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)*) | | **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 | | **anonymous** | - 匿名アクセスを使用します。この認証方法は公開ファイルにのみアクセスできます。 | | **session (推奨)** | - 一時的に生成されたaccess_key_id、secret_access_key、およびsession_tokenを使用します。(この認証方法はデータインポートでのみ使用できます。現時点ではデータエクスポートには使用できません。) - Access Key ID - Secret access key - Secret token | | **Access Key ID** | AWS S3が発行 | | **Secret Access Key** | AWS S3が発行 | ### AWS S3データをTreasure Dataに転送 認証された接続を作成すると、自動的にAuthenticationsに移動します。 1. 作成した接続を検索します。 2. **New Source**を選択します。 ![](/assets/image-20191014-185537.a673857cd3d7cd4d6249e93718c2c0b501d3da0ab1a5cfef2dd54c1fb6478775.cd73d98d.png) ### Authentication 1. Data Transfer フィールドに**Source**の名前を入力します。 2. **Next** をクリックします。 ![](/assets/s3_new.5fa3911b9f90a38cdf2daddcdf9cb8cebe026cc85658ca1f4da2ba69f80fc138.cd73d98d.png) ### Amazon S3 Import V1のSource Table設定 1. Sourceダイアログが開きます。以下のパラメータを編集します。 ![](/assets/image-20200714-230936.8f5e75b81b4ba3f8922f5ade1c5d5d06284c8f229cde7360b413f9e024fecf27.cd73d98d.png) | **パラメータ** | **説明** | | --- | --- | | **Bucket** | - S3バケット名を指定します（例：*your_bucket_name*） | | **Path Prefix** | - 対象キーのプレフィックスを指定します（例：*logs/data_*） | | **Path Regex** | - ファイルパスにマッチする正規表現を使用します。ファイルパスが指定されたパターンにマッチしない場合、そのファイルはスキップされます。例えば、パターン *.csv$* # を指定した場合、パスがそのパターンにマッチしないファイルはスキップされます。[正規表現](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)の詳細をご覧ください。 | | **Skip Glacier Objects** | - Amazon Glacierストレージクラスに保存されているオブジェクトの処理をスキップする場合に選択します。オブジェクトがGlacierストレージクラスに保存されているにもかかわらず、このオプションがチェックされていない場合、例外がスローされます。 | | **Filter by Modified Time** | - 取り込むファイルをフィルタリングする方法を選択します： | | チェックされていない場合（デフォルト）： | - **Start after path**：last_pathパラメータを挿入し、最初の実行時にそのパスより前のファイルをスキップします（例：logs/data_20170101.csv） - **Incremental**：増分ロードを有効にします。増分ロードが有効になっている場合、次回実行のconfig diffにlast_pathパラメータが含まれ、次回実行時にそのパスより前のファイルがスキップされます。それ以外の場合、last_pathは含まれません。 | | チェックされている場合： | - **Modified after：** last_modified_timeパラメータを挿入し、最初の実行時に指定されたタイムスタンプより前に変更されたファイルをスキップします（例：2019-06-03T10:30:19.806Z） - **Incremental by Modified Time：** 変更時刻による増分ロードを有効にします。増分ロードが有効になっている場合、次回実行のconfig diffにlast_modified_timeパラメータが含まれ、次回実行時にその時刻より前に変更されたファイルがスキップされます。それ以外の場合、last_modified_timeは含まれません。 | **例** Amazon CloudFrontは、静的および動的なWebコンテンツの配信を高速化するWebサービスです。CloudFrontが受信するすべてのユーザーリクエストに関する詳細情報を含むログファイルを作成するようにCloudFrontを設定できます。ロギングを有効にすると、以下のようにCloudFrontログファイルを保存できます： ``` [your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-15.a103fd5a.gz] [your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-15.b2aede4a.gz] [your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-16.594fa8e6.gz] [your_bucket] - [logging] - [E231A697YXWD39.2017-04-23-16.d12f42f9.gz] ``` この場合、Source Tableの設定は以下のようになります： - **Bucket**：your_bucket - **Path Prefix**：logging/ - **Path Regex**：*.gz$*（必須ではありません） - **Start after path**：logging/E231A697YXWD39.2017-04-23-15.b2aede4a.gz（2017-04-23-16からログファイルをインポートしたいと仮定した場合） - **Incremental**：true（このジョブをスケジュールする場合） BZip2 decoderプラグインはデフォルトでサポートされています。[Zip Decoder Function](/products/customer-data-platform/integration-hub/batch/import/decoder/file-decoder-function) ### データ設定 1. **Next** を選択します。 Data Settingsページが開きます。 2. 必要に応じてデータ設定を編集するか、このページをスキップします。 ![](/assets/image-2023-08-17.8f72248b8a2123147b3671f0a212ff7e200c354873c1b9c579efde51319ae1b1.cd73d98d.png) | パラメータ | 説明 | | --- | --- | | Total file count limit | 読み込むファイルの最大数を指定できます | | Minimum task size | このサイズまでのファイルが1つのタスクにグループ化されます。デフォルト値は268435456（バイト）です。 | ### Filters Filters は、S3、FTP、または SFTP コネクターの Create Source または Edit Source インポート設定で使用できます。 Import Integration Filters を使用すると、インポート用の[データ設定の編集](https://docs.treasuredata.com/smart/project-product-documentation/editing-data-settings)を完了した後、インポートされたデータを変更できます。 import integration filters を適用するには: 1. Data Settings で **Next** を選択します。Filters ダイアログが開きます。 2. 追加したいフィルターオプションを選択します。![](/assets/image-20200609-201955.eed6c6da800ba40d1d98b92e767d9a8f7500cad8a9d4079121190b7d34c23294.c7246827.png) 3. **Add Filter** を選択します。そのフィルターのパラメーターダイアログが開きます。 4. パラメーターを編集します。各フィルタータイプの情報については、次のいずれかを参照してください: - Retaining Columns Filter - Adding Columns Filter - Dropping Columns Filter - Expanding JSON Filter - Digesting Filter 1. オプションで、同じタイプの別のフィルターを追加するには、特定の列フィルターダイアログ内で **Add** を選択します。 2. オプションで、別のタイプの別のフィルターを追加するには、リストからフィルターオプションを選択して、同じ手順を繰り返します。 3. 追加したいフィルターを追加した後、**Next** を選択します。Data Preview ダイアログが開きます。 ### 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** で転送の結果を確認できます。 ## データコネクタジョブの検証 ### データインポートの問題をトラブルシューティングするにはどうすればよいですか？ ジョブログを確認してください。警告とエラーは、インポートの成功に関する情報を提供します。たとえば、[インポートエラーに関連するソースファイル名を特定する](/products/customer-data-platform/integration-hub/batch/import/data-import-error-troubleshooting)ことができます。 特定のジョブの詳細を確認するには、そのジョブを選択して詳細を表示できます。ジョブの種類に応じて、結果、クエリ、出力ログ、エンジンログ、詳細、送信先のいずれか、またはすべてを確認できます。 1. TD Consoleを開きます。 2. **Jobs**に移動します。 ![](/assets/viewing-job-information-2024-01-10.de206a7c818167b6a85da2a1b25df77f2adf1f030824ca0a9505dd592d88a52e.c5032e94.png) 3. オプションで、フィルターを使用してジョブのリストを絞り込み、興味のあるものを見つけます。ジョブの所有者、日付、データベース名でのフィルタリングが含まれます 4. ジョブを選択して開き、結果、クエリ定義、ログ、その他の詳細を表示します。 5. 各タブには、ジョブに関する異なる情報が表示されます。 | | 説明 | | --- | --- | | Results | - ジョブからインポートされたデータを表示します。 - ここから、結果をクリップボードにコピーしたり、CSVファイルとしてダウンロードしたりできます。 | | Query | - ジョブのクエリ構文を表示します - クエリエディタを起動します - クエリをコピーして、新しいクエリやワークフローの作成に使用します - クエリを改良して効率を向上させます | | Output Logs | - ログ情報は、実行時間、クエリ結果数、エラーコードについて確認できます - ログ情報はクリップボードにコピーできます | | Engine Logs | - ログ情報は、実行時間、クエリ結果数、エラーコードについて確認できます - ログ情報はクリップボードにコピーできます | | Job Details | 詳細情報を表示します： - クエリ名 - タイプ - ジョブID - ステータス - 期間 - スケジュールされた時間と実際の時間 - 結果のカウントとサイズ - ランナー - クエリされたデータベース - 優先度 | ### S3のデータコネクタジョブが長時間実行されている場合、どうすればよいですか？ コネクタジョブが取り込んでいるS3ファイルの数を確認してください。10,000ファイルを超える場合、パフォーマンスが低下します。この問題を軽減するには、次のことができます： - path_prefixオプションを絞り込み、S3ファイルの数を減らします。 - min_task_sizeオプションに268,435,456（256MB）を設定します。 # WorkflowによるAWS S3からのインポート S3インポート統合用のサンプルワークフローファイルがあります。ymlファイルを使用してインポート設定を定義し、`td\_load>:` workflowオペレータを使用して実行できます。TD consoleのSourceファンクションだけでは使用できない変数定義が、ymlファイルベースの実行では可能です。 サンプルコードは[https://github.com/treasure-data/treasure-boxes/tree/master/td_load/s3](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/s3)から参照できます。 ``` timezone: UTC schedule: daily>: 02:00:00 sla: time: 08:00 +notice: mail>: {data: Treasure Workflow Notification} subject: This workflow is taking long time to finish to: [me@example.com] _export: td: dest_db: dest_db_ganesh dest_table: dest_table_ganesh +prepare_table: td_ddl>: create_databases: ["${td.dest_db}"] create_tables: ["${td.dest_table}"] database: ${td.dest_db} +load: td_load>: config/daily_load.yml database: ${td.dest_db} table: ${td.dest_table} ``` # CLI（Toolbelt）によるAWS S3からのインポート オプションとして、TD Toolbeltを使用して接続を設定し、ジョブを作成し、実行をスケジュールすることができます。 ## CLIを使用してコネクタを設定する コネクタをセットアップする前に、'td'コマンドをインストールします。最新のTD Toolbeltをインストールしてください。 ## Seed Configファイル（seed.yml）を作成する 次の例に示すように、AWSアクセスキーとシークレットアクセスキーを使用して*seed.yml*を準備します。バケット名とソースファイル名（または複数ファイルのプレフィックス）も指定する必要があります。 ``` in: type: s3 access_key_id: XXXXXXXXXX secret_access_key: YYYYYYYYYY bucket: sample_bucket # path to the *.json or *.csv or *.tsv file on your s3 bucket path_prefix: path/to/sample_file path_match_pattern: \.csv$ # a file will be skipped if its path doesn't match with this pattern ## some examples of regexp: #path_match_pattern: /archive/ # match files in .../archive/... directory #path_match_pattern: /data1/|/data2/ # match files in .../data1/... or .../data2/... directory #path_match_pattern: .csv$|.csv.gz$ # match files whose suffix is .csv or .csv.gz out: mode: append ``` Data Connector for Amazon S3は、指定されたプレフィックスに一致するすべてのファイルをインポートします。（例：path_prefix: `path/to/sample_` –> `path/to/sample_201501.csv.gz`、`path/to/sample_201502.csv.gz`、…、`path/to/sample_201505.csv.gz`）。 先頭に'/'を付けたpath_prefixを使用すると、意図しない結果につながる可能性があります。たとえば、「path_prefix: /path/to/sample_file」は、プラグインがs3://sample_bucket//path/to/sample_fileでファイルを探すことになり、意図したs3://sample_bucket/path/to/sample_fileのパスとは異なります。 ## フィールドの推測（load.ymlの生成） *connector:guess*を使用します。このコマンドは自動的にソースファイルを読み込み、ファイル形式とそのフィールド/カラムを評価（ロジックを使用して推測）します。 ``` $ td connector:guess seed.yml -o load.yml ``` load.ymlを開くと、ファイル形式、エンコーディング、カラム名、および型を含む評価されたファイル形式定義が表示されます。 ``` in: type: s3 access_key_id: XXXXXXXXXX secret_access_key: YYYYYYYYYY bucket: sample_bucket path_prefix: path/to/sample_file parser: charset: UTF-8 newline: CRLF type: csv delimiter: ',' quote: '"' escape: '' skip_header_lines: 1 columns: - name: id type: long - name: company type: string - name: customer type: string - name: created_at type: timestamp format: '%Y-%m-%d %H:%M:%S' out: mode: append ``` 次に、*td connector:preview*コマンドを使用してデータのプレビューを確認できます。 ``` $ td connector:preview load.yml +-------+---------+----------+---------------------+ | id | company | customer | created_at | +-------+---------+----------+---------------------+ | 11200 | AA Inc. | David | 2015-03-31 06:12:37 | | 20313 | BB Imc. | Tom | 2015-04-01 01:00:07 | | 32132 | CC Inc. | Fernando | 2015-04-01 10:33:41 | | 40133 | DD Inc. | Cesar | 2015-04-02 05:12:32 | | 93133 | EE Inc. | Jake | 2015-04-02 14:11:13 | +-------+---------+----------+---------------------+ ``` guessコマンドは、ソースデータのサンプル行を使用してカラム定義を評価するため、ソースデータファイルに3行以上、2カラム以上が必要です。 カラム名またはカラムタイプが予期しないものとして検出された場合は、load.ymlを直接修正して再度プレビューしてください。 現在、Data Connectorは「boolean」、「long」、「double」、「string」、および「timestamp」タイプの解析をサポートしています。 ## ロードジョブの実行 ロードジョブを送信します。データのサイズによっては数時間かかる場合があります。データを保存するTreasure Dataのデータベースとテーブルを指定します。 Treasure Dataのストレージは時間でパーティション化されているため（[データパーティショニング](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)を参照）、*--time-column*オプションを指定することをお勧めします。このオプションが指定されていない場合、Data Connectorは最初の*long*または*timestamp*カラムをパーティショニング時間として選択します。*--time-column*で指定されるカラムのタイプは、*long*と*timestamp*タイプのいずれかである必要があります。 データに時間カラムがない場合は、*add_time*フィルターオプションを使用して時間カラムを追加できます。詳細については、[add_time filter plugin](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function)を参照してください。 ``` $ 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)*を作成していることを前提としています。データベースまたはテーブルがTDに存在しない場合、このコマンドは成功しないため、データベースとテーブルを手動で作成するか、*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 ``` Data Connectorはサーバー側でレコードをソートしません。時間ベースのパーティショニングを効果的に使用するには、事前にファイル内のレコードをソートしてください。 *time*というフィールドがある場合は、*--time-column*オプションを指定する必要はありません。 ``` $ td connector:issue load.yml --database td_sample_db --table td_sample_table ``` ### インポートモード データ配置の場合は、データを配置するターゲットのデータベースとテーブルを選択し、インポートを実行する頻度を指定します。 1. **Next**を選択します。Storageの下で、新しいデータベースを作成するか既存のデータベースを選択し、インポートしたデータを配置する新しいテーブルを作成するか既存のテーブルを選択します。 ![](/assets/image2021-9-21_13-51-13.1c4e6a0713064cdb51e8c6c29150a8150f05a14a3b10cc3a3eef1aeff9b95349.891720f6.png) 2. **Database**を選択 > **Select** **an existing**または**Create New Database**を選択します。 3. オプションで、データベース名を入力します。 4. **Table**を選択 > **Select an existing**または**Create New Table**を選択します。 5. オプションで、テーブル名を入力します。 6. データをインポートする方法を選択します。 - **Append**（デフォルト）- データインポートの結果はテーブルに追加されます。 テーブルが存在しない場合は、作成されます。 - **Always Replace** - 既存のテーブルの全コンテンツをクエリの結果出力で置き換えます。テーブルが存在しない場合は、新しいテーブルが作成されます。 - **Replace on New Data** - 新しいデータがある場合のみ、既存のテーブルの全コンテンツをクエリの結果出力で置き換えます。 7. **Timestamp-based Partition Key** カラムを選択します。 デフォルトキーとは異なるパーティションキーシードを設定する場合は、long または timestamp カラムをパーティショニング時刻として指定できます。デフォルトの時刻カラムとしては、add_time フィルタを使用した upload_time が使用されます。 8. データストレージの **Timezone** を選択します。 9. **Schedule** で、このクエリを実行する時期と頻度を選択できます。 - - 一度だけ実行: 1. - 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** で確認できます。 ## スケジュール実行 増分ファイルインポートのために、定期的なデータコネクタ実行をスケジュールできます。高可用性を確保するために、スケジューラは慎重に設定されています。 スケジュールされたインポートでは、指定されたプレフィックスに一致するすべてのファイルと、以下のいずれかのフィールドを条件としてインポートできます: - use_modified_time が無効の場合、次の実行のために最後のパスが保存されます。2回目以降の実行では、コネクタはアルファベット順で最後のパス以降のファイルのみをインポートします。 - それ以外の場合、ジョブが実行された時刻が次の実行のために保存されます。2回目以降の実行では、コネクタはその実行時刻以降にアルファベット順で変更されたファイルのみをインポートします。 ## TD Toolbelt を使用したスケジュールの作成 *td connector:create* コマンドを使用して新しいスケジュールを作成できます。 ``` $ td connector:create daily_import "10 0 * * *" \ td_sample_db td_sample_table load.yml ``` Treasure Data のストレージは時刻でパーティション化されているため、*--time-column* オプションを指定することも推奨されます（[データパーティショニング](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)も参照してください）。 ``` $ 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 などのタイムゾーン略語は*サポートされておらず*、予期しないスケジュールにつながる可能性があります。 ## すべてのスケジュールのリスト表示 *td connector:list* コマンドを実行すると、現在スケジュールされているエントリのリストを確認できます。 ``` $ td connector:list +--------------+--------------+----------+-------+--------------+-----------------+------------------------------------------+ | Name | Cron | Timezone | Delay | Database | Table | Config | +--------------+--------------+----------+-------+--------------+-----------------+------------------------------------------+ | daily_import | 10 0 * * * | UTC | 0 | td_sample_db | td_sample_table | {"in"=>{"type"=>"s3", "access_key_id"... | +--------------+--------------+----------+-------+--------------+-----------------+------------------------------------------+ ``` ## スケジュール設定と履歴の表示 *td connector:show* は、スケジュールエントリの実行設定を表示します。 各項目の説明: | | TD AWS サービスへのアクセスを許可します | | --- | --- | | | TD AWS サービスへのアクセスを許可します | | endpoint | ネットワークと相互に通信するコンピュータ 例: `s3.amazonaws.com` | | bucket | データベース内のコンテナオブジェクト 例: `https://my-bucket.s3.us-west-2.amazonaws.com` | | | ターゲットキーのプレフィックスを指定 例: `logging/` `path/to/sample_201501.csv.gz`、`path/to/sample_201502.csv.gz`、…、`path/to/sample_201505.csv.gz` | ``` % td connector:show daily_import Name : daily_import Cron : 10 0 * * * Timezone : UTC Delay : 0 Database : td_sample_db Table : td_sample_table Config --- in: type: s3 access_key_id: access_key_id secret_access_key: secret_access_key endpoint: endpoint bucket: bucket path_prefix: path_prefix parser: charset: UTF-8 ... ``` *td connector:history* は、スケジュールエントリの実行履歴を表示します。個々の実行結果を調査するには、*td job jobid* を使用します。 ``` % td connector:history daily_import +--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+ | JobID | Status | Records | Database | Table | Priority | Started | Duration | +--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+ | 578066 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-18 00:10:05 +0000 | 160 | | 577968 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-17 00:10:07 +0000 | 161 | | 577914 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-16 00:10:03 +0000 | 152 | | 577872 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-15 00:10:04 +0000 | 163 | | 577810 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-14 00:10:04 +0000 | 164 | | 577766 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-13 00:10:04 +0000 | 155 | | 577710 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-12 00:10:05 +0000 | 156 | | 577610 | success | 10000 | td_sample_db | td_sample_table | 0 | 2015-04-11 00:10:04 +0000 | 157 | +--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+ 8 rows in set ``` ## スケジュールの削除 *td connector:delete* は、スケジュールを削除します。 ``` $ td connector:delete daily_import ``` ## IAM権限 YML設定ファイルで指定され、*connector:guess* および *connector:issue* コマンドで使用されるIAM認証情報には、アクセスする必要があるAWS S3リソースに対する権限が許可されている必要があります。IAMユーザーがこれらの権限を持っていない場合は、事前定義されたポリシー定義の1つでユーザーを設定するか、JSON形式で新しいポリシー定義を作成してください。 以下の例は、[Policy Definition reference](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.md)形式に基づいており、your-bucketに対する*読み取り専用*（GetObjectおよびListBucketアクションを通じて）権限をIAMユーザーに付与します。 ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::your-bucket", "arn:aws:s3:::your-bucket/*" ] } ] } ``` `your-bucket`を実際のバケット名に置き換えてください。 ## 一時的な認証情報プロバイダーとしてのAWS Security Token Service (STS)の使用 特定の場合、access_key_idとsecret_access_keyによるIAM基本認証はリスクが高すぎる可能性があります（ただし、ジョブが実行されるとき、またはセッションが作成された後、secret_access_keyは明確に表示されることはありません）。 S3 data connectorは、AWS Secure Token Service (STS)が提供する[Temporary Security Credentials](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.md)を使用できます。AWS STSを使用すると、任意のIAMユーザーが自身のaccess_key_idとsecret_access_keyを使用して、有効期限が関連付けられた一時的なnew_access_key_id、new_secret_access_key、およびsession_tokenキーのセットを作成でき、その有効期限が過ぎると認証情報は無効になります。 Temporary Security Credentialsには以下のタイプがあります。 - [**Session Token**](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_getsessiontoken.md) 有効期限が関連付けられた最もシンプルなSecurity Credentialsです。一時的な認証情報は、それらを生成するために使用された元のIAM認証情報が持っていたすべてのリソースへのアクセスを提供します。これらの認証情報は、有効期限が切れておらず、元のIAM認証情報の権限が変更されていない限り有効です。 - [**Federation Token**](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_getfederationtoken.md) 上記のSession Tokenに権限制御の追加レイヤーを追加します。Federation Tokenを生成する際、IAMユーザーはPermission Policy定義を指定する必要があります。スコープを使用して、IAMユーザーがアクセス可能なリソースのうち、Federation Tokenの所有者がアクセスすべきリソースをさらに絞り込むことができます。任意の[Permission Policy](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.md)定義を使用できますが、権限のスコープは、トークンを生成するために使用されたIAMユーザーが持っていた権限のすべてまたは一部のサブセットに限定されます。Session Tokenと同様に、Federation Token認証情報は、有効期限が切れておらず、元のIAM認証情報に関連付けられた権限が変更されていない限り有効です。 AWS STS Temporary Security Credentialsは、[AWS CLI](https://aws.amazon.com/cli/)または選択した言語の[AWS SDK](https://aws.amazon.com/tools/)を使用して生成できます。 ### Session Token ``` $ aws sts get-session-token --duration-seconds 900 { "Credentials": { "SecretAccessKey": "YYYYYYYYYY", "SessionToken": "ZZZZZZZZZZ", "Expiration": "2015-12-23T05:11:14Z", "AccessKeyId": "XXXXXXXXXX" } } ``` ### Federation Token ``` $ aws sts get-federation-token --name temp_creds --duration-seconds 900 --policy '{"Statement": [{"Effect": "Allow", "Action": ["s3:GetObject", "s3:ListBucket"], "Resource": "arn:aws:s3:::bucketname"}]}' { "FederatedUser": { "FederatedUserId": "523683666290:temp_creds", "Arn": "arn:aws:sts::523683666290:federated-user/temp_creds" }, "Credentials": { "SecretAccessKey": "YYYYYYYYYY", "SessionToken": "ZZZZZZZZZZ", "Expiration": "2015-12-23T06:06:17Z", "AccessKeyId": "XXXXXXXXXX" }, "PackedPolicySize": 16 } ``` ここで: * `temp_cred` は Federated トークン/ユーザーの名前です * `bucketname` はアクセスを許可するバケットの名前です。詳細については [ARN仕様](http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.md#arn-syntax-s3) を参照してください * `s3:GetObject` と `s3:ListBucket` は AWS S3 バケットの基本的な読み取り操作です。 AWS STS 認証情報は取り消すことができません。有効期限が切れるまで、または認証情報の生成に使用した元の IAM ユーザーの権限を削除するまで有効です。 Temporary Security Credentials が生成されたら、*seed.yml* ファイルに `SecretAccessKey`、`AccessKeyId`、および `SessionToken` を次のようにコピーします。 ```yaml in: type: s3 auth_method: session access_key_id: XXXXXXXXXX secret_access_key: YYYYYYYYYY session_token: ZZZZZZZZZZ bucket: sample_bucket path_prefix: path/to/sample_file ``` そして、通常通り Data Connector for S3 を実行します。 #### 認証情報の有効期限 STS 認証情報は指定された時間が経過すると期限切れになるため、認証情報の有効期限が切れると、その認証情報を使用するデータコネクタジョブは最終的に失敗し始める可能性があります。 現在、STS 認証情報の有効期限切れが報告された場合、データコネクタジョブは最大回数（5回）まで再試行し、最終的に「error」ステータスで完了します。