# KARTE Import Integration [KARTE Export Integrationについて詳しく知る](/ja/int/karte-export-integration)。 KARTE Data Connectorを使用して、Google Cloud Storage (GCS) バケットに保存されている*.tsvおよび*.csvファイルの内容をTreasure Dataにインポートできます。 # 前提条件 - Treasure Dataの基本知識 - 既存のGoogle Service Account - [Google Developers Console](https://console.cloud.google.com/apis/credentials)からJSONキーファイルを生成して取得する必要があります。詳細については、Google Cloud Platformのドキュメントの[サービスアカウント認証情報の生成](https://cloud.google.com/storage/docs/authentication#generating-a-private-key)セクションを参照してください。 # TD Consoleを使用した接続の作成 TD Consoleを使用して接続を設定できます。 ## 新しい接続の作成 **Integrations Hub** > **Catalog**に移動して検索します。KARTEを選択します。 ![](/assets/image-20191002-135955.548637f02320160279902e01534c80bff33d9c46d6aeafd70b1275e532f0228a.028cedc9.png) ## 新しいKARTE Connectorの作成 次のダイアログが開きます。 ![](/assets/image-20191002-140011.c17b6968f44c52e7afef9b09add1e5bf17ce82550831495eb039462783ab109c.028cedc9.png) 必要な認証情報を入力します。TD Consoleでは、JSONキーファイルのみを使用して認証できます。 - **JSON key file:** [Google Developers Console](https://console.developers.google.com/projectselector/apis/dashboard?pli=1&supportedpurview=project&project=&folder=&organizationId=)から生成されたJSONキーファイルの内容をこのフィールドにコピー&ペーストします。 - **Application Name:** *KARTE*がデフォルト値です。KARTEは、このコネクタに対してTreasure Dataが選択した名前です。 **Continue**を選択します。 データコネクタの名前を指定し、**Done**を選択します。 ## Treasure DataへのKARTEデータのインポート Connectionsページが表示されます。**New Transfer**を選択します。 ![](/assets/image-20191002-140058.8c2c0aa361e2430417c046015e0fc83e6b87bfa47834ce0b757a5f530a1f7aa5.028cedc9.png) 以下のセクションでは、フェッチ、プレビュー、転送、スケジュール、および詳細の確認に関する手順を説明します。 ### Fetch from 取り込みたい情報を登録する必要があります。 - **Bucket**. Google Cloud Storageバケット名(例: *your_bucket_name*)。 - **Path Prefix**. ターゲットキーのプレフィックス(例: *logs/data_*)。 - **Path Regex**. ファイルパスにマッチする正規表現を指定します。ファイルパスがこのパターンにマッチしない場合、そのファイルはスキップされます(例: *.csv$* の場合、パスがこのパターンにマッチしないファイルはスキップされます)。 - **Start after path**. last_pathパラメータを挿入して、最初の実行でこのパスより前のファイルをスキップします(例: logs/data_20170101.csv)。 - **Incremental**. インクリメンタルローディングを有効にします。インクリメンタルローディングが有効な場合、次の実行のconfig diffにはlast_pathパラメータが含まれ、次の実行ではそのパスより前のファイルがスキップされます。それ以外の場合、last_pathは含まれません。 **例** 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] ``` この場合、**Fetch from**の設定は次のようになります。 - **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 (このジョブをスケジュールしたい場合) ### Preview データのプレビューが表示されます。データプレビューの仕組みの詳細については、[About Data Preview](https://docs.treasuredata.com/smart/project-product-documentation/about-data-preview)を参照してください。 指定したカラム名の設定などの変更を行う場合は、**Advanced Settings**を選択します。それ以外の場合は、**Next**を選択します。 ![](/assets/image-20191002-140127.8ce28e8252806bedbc3a1e227e7110284f61c67830baff1d7203d2bd6878fb5b.028cedc9.png) ### Advanced Settings Advanced Settingsでは、プロパティを編集できます。以下のプロパティが利用可能です。 - **Default timezone**. 値自体にタイムゾーンが含まれていない場合、timestampカラムのタイムゾーンを変更します。 - **Columns** - **Name**. カラムの名前を変更します。カラム名は小文字のアルファベット、数字、および"_"のみをサポートします。 - **Type**. 指定されたタイプとして値を解析し、TreasureDataスキーマに変換した後でそのタイプを保存します。 - **boolean** - **long** - **timestamp**: TreasureDataではstring型としてインポートされます(例: 2017-04-01 00:00:00.000) - **double** - **string** - **json** - **Total file count limit**. 読み取るファイルの最大数(オプション)。 ### Transfer to インポート用の既存のデータベースとテーブルを選択するか、新しいものを作成します。 - **Mode**: AppendまたはReplace。既存のテーブルにレコードを追加するか、既存のテーブルを置き換えるかを選択します。 - **Partition Key Seed**: パーティショニング時間としてlongまたはtimestampカラムを選択します。デフォルトの時間カラムとして、add_timeフィルタを使用したupload_timeを使用します。 ![](/assets/image-20191002-140144.651aa572e865bc7573686c420447667aed867478fccb900fe2e2a7a7f9f0c1f6.028cedc9.png) ## When 1回限りの転送または自動的に繰り返される転送のスケジュールを指定できます。 以下のパラメータを使用してスケジュールを設定します。 - **Once now**. ジョブを1回実行します。 - **Repeat** - **Schedule**. *@hourly*、*@daily*、*@monthly*の3つのオプション、およびカスタム*cron*でスケジュールできます。 - **Delay Transfer**. 指定された実行時刻に遅延を追加します。 - **Timezone**. 拡張タイムゾーン形式をサポートします(例: Asia/Tokyo)。 ![](/assets/image-20191002-140158.2a798952d67f014f0c0fed2c52ca77642e32826d73528cdd28cc9ca6e2f58c49.028cedc9.png) ## Details ソースの名前を作成し、**DONE**を選択してKARTE connectorを新しいソースとして保存します。 ![](/assets/image-20191002-140209.6b755a05b3d89734c08d69c3347b3068adcd567d403707c3078424d8ddaf88f7.028cedc9.png) ## My Input Transfers My Input Transfersで既存のジョブを編集します。このデータコネクタの以前の転送の詳細を表示するには、ジョブアイコンを選択します。 ![](/assets/image-20191002-140218.f38854126ff8ca4e9bcc4f49571d27ca0e949fc9848a556272a34459949e0261.028cedc9.png) # CLIを使用したコネクタの設定 コネクタをセットアップする前に、[Treasure Data Toolbelt](https://docs.treasuredata.com/smart/project-product-documentation/installing-and-updating-td-toolbelt-and-treasure-agent)をインストールしてください。 ## Seed Config File (seed.yml)の作成 以下の例とJSONキーファイルを使用して*seed.yml*を準備します。バケットとターゲットファイル名（または複数ファイルの場合はプレフィックス）も指定する必要があります。 ``` in: type: karte bucket: sample_bucket path_prefix: path/to/sample_file # path the the *.csv or *.tsv file on your GCS bucket auth_method: json_key json_keyfile: content: | { "private_key_id": "1234567890", "private_key": "-----BEGIN PRIVATE KEY-----\nABCDEF", "client_id": "...", "client_email": "...", "type": "service_account" } out: mode: append ``` Data Connector for KARTEは、指定されたプレフィックスに一致するすべてのファイルをインポートします。例：path_prefix: `path/to/sample_` –> `path/to/sample_201501.csv.gz`, `path/to/sample_201502.csv.gz`, …, `path/to/sample_201505.csv.gz` 利用可能な*out*モードの詳細については、下記の付録を参照してください。 ## フィールドの推測（load.ymlの生成） *connector:guess*を使用します。このコマンドは、ターゲットファイルを自動的に読み取り、ファイル形式をインテリジェントに推測します。 ``` $ td connector:guess seed.yml -o load.yml ``` [*load.yml*](http://load.yml.to)を開いて、ファイル形式、エンコーディング、カラム名、タイプなど、推測されたファイル形式定義を確認します。 ``` in: type: karte bucket: sample_bucket path_prefix: path/to/sample_file auth_method: json_key json_keyfile: content: | { "private_key_id": "1234567890", "private_key": "-----BEGIN PRIVATE KEY-----\nABCDEF", "client_id": "...", "client_email": "...", "type": "service_account" } decoders: - {type: gzip} 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 ``` *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」タイプの解析をサポートしています。 previewコマンドは、指定されたバケットから1つのファイルをダウンロードし、そのファイルの結果を表示します。これにより、previewコマンドとissueコマンドの結果に違いが生じる可能性があります。 ## ロードジョブの実行 最後に、ロードジョブを送信します。データのサイズに応じて、数時間かかる場合があります。ユーザーは、データが格納されるデータベースとテーブルを指定する必要があります。 Treasure Dataのストレージは時間で分割されているため、*--time-column*オプションを指定することをお勧めします（[data partitioning](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)も参照）。このオプションを指定しない場合、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 ``` 上記の例のコマンドは、*database(td_sample_db)*と*table(td_sample_table)*がすでに作成されていることを前提としています。データベースまたはテーブルがTreasure Dataに存在しない場合、このコマンドは成功しません。代わりに、データベースとテーブルを手動で作成するか、*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 ``` # 実行時間のスケジュール設定 高可用性スケジューラを使用すると、増分KARTEファイルインポートのための定期的なData Connectorの実行をスケジュールできます。この機能を使用することで、ローカルデータセンターで*cron*デーモンを使用する必要がなくなります。 スケジュールされたインポートの場合、Data Connector for KARTEは、最初に指定されたプレフィックスに一致するすべてのファイル（例：path_prefix: `path/to/sample_` –> `path/to/sample_201501.csv.gz`, `path/to/sample_201502.csv.gz`, …, `path/to/sample_201505.csv.gz`）をインポートし、次回の実行のために最後のパス（`path/to/sample_201505.csv.gz`）を記憶します。 2回目以降の実行では、アルファベット順（辞書式順序）で最後のパスの後にあるファイルのみをインポートします。例：`path/to/sample_201506.csv.gz`, … ## スケジュールの作成 *td connector:create*コマンドを使用して、新しいスケジュールを作成できます。以下が必要です： - スケジュール名 - cron形式のスケジュール - データが保存されるデータベースとテーブル。 - Data Connector設定ファイル。 ``` $ td connector:create \ daily_import \ "10 0 * * *" \ td_sample_db \ td_sample_table \ load.yml ``` Treasure Dataのストレージは時間で分割されているため、*--time-column*オプションを指定することをお勧めします([アーキテクチャ](https://docs.treasuredata.com/articles/project-product-documentation/about-treasure-data+Architecture)も参照してください)。 ``` $ 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"=>"karte", ... | +--------------+------------+----------+-------+--------------+-----------------+----------------------------+ ``` ### 設定とスケジュール履歴の表示 *td connector:show*は、スケジュールエントリの実行設定を表示します。 ``` % 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: karte bucket: sample_bucket path_prefix: path/to/sample_ auth_method: json_key json_keyfile: content: | { "private_key_id": "1234567890", "private_key": "-----BEGIN PRIVATE KEY-----\nABCDEF", "client_email": "...", "type": "service_account" } decoders: - type: gzip 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 ``` # 付録 ## ファイル名のルール NFC は、[この記事](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms)で説明されているように、[ファイル名のエンコードと相互運用性の問題](https://cloud.google.com/storage/docs/gsutil/addlhelp/Filenameencodingandinteroperabilityproblems.)を軽減するために、ファイル名に必要なユニコード正規化形式のタイプです。そうでない場合、path_match_patternまたはpath_prefixと比較するときに一致エラーが発生する可能性があります。 ## Out Pluginのモード seed.ymlの*out*セクションでファイルインポートモードを指定できます。 ### append (デフォルト) これはデフォルトモードで、レコードがターゲットテーブルに追加されます。 ``` in: ... out: mode: append ``` ### replace (td 0.11.10以降) このモードは、ターゲットテーブルのデータを置き換えます。ターゲットテーブルに対して手動で行われたスキーマ変更は、このモードでもそのまま保持されます。 ``` in: ... out: mode: replace ```