# FTP Import Integration CLI

コマンドラインインターフェースからFTPデータコネクタを使用することもできます。以下の手順では、CLIを使用してデータをインポートする方法を説明します。

## 'td' Command v0.11.9以降のインストール

最新の[TD Toolbelt](https://toolbelt.treasuredata.com/)をインストールしてください。


```bash
$ td --version
0.11.10
```

## Seed設定ファイルの作成（seed.yml）

まず、以下の例に示すように、FTPの詳細情報を含む*seed.yml*を準備します。バケット名とターゲットファイル名（または複数ファイルのプレフィックス）も指定する必要があります。


```yaml
in:
  type: ftp
  host: ftp.example.net
  port: 21
  user: anonymous
  password: XXXX
  path_prefix: /ftp/file/path/prefix # FTPサーバー上の*.csvまたは*.tsvファイルのパス
out:
  mode: append
```

Data Connector for FTPは、指定されたプレフィックスに一致するすべてのファイルをインポートします（例：path_prefix: path/to/sample_ > path/to/sample_201501.csv.gz, path/to/sample_201502.csv.gz, …, path/to/sample_201505.csv.gz）。

Active Modeはサポートされていません。

FTPSを使用している場合は、次のように追加の詳細情報を指定します：


```yaml
in:
  type: ftp
  host: ftp.example.net
  port: 21
  user: anonymous
  password: "mypassword"
  path_prefix: /ftp/file/path/prefix
  ssl: true
  ssl_verify: false
out:
  mode: append
```

詳細については、[outプラグインのモード](https://docs.treasuredata.com/articles/project-integrations/ftp-import-integration-cli#FTPImportIntegrationCLI-ModesforOutPlugin)を参照してください。

## フィールドの推測（load.ymlの生成）

*connector:guess*を使用します。このコマンドは、ソースファイルを自動的に読み取り、ファイル形式を評価（ロジックを使用して推測）します。

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


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

load.ymlを開くと、ファイル形式、エンコーディング、列名、型などの評価されたファイル形式定義が表示されます。


```yaml
in:
  type: ftp
  host: ftp.example.net
  port: 21
  user: anonymous
  password: XXXX
  path_prefix: /ftp/file/path/prefix
  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* コマンドを使用して、システムがファイルをどのように解析するかをプレビューできます。


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

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

現在、Data Connector は "boolean"、"long"、"double"、"string"、および "timestamp" タイプの解析をサポートしています。

データロードジョブを実行する前に、データベースとテーブルを作成する必要があります。次の手順に従ってください:


```bash
td database:create td_sample_db
td table:create td_sample_db td_sample_table
```

## ロードジョブの実行

最後に、ロードジョブを送信します。データのサイズによっては数時間かかる場合があります。データを保存する 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 フィルタープラグイン](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function) を参照してください。


```bash
$ 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 に存在しない場合、connector:issue コマンドは失敗するため、データベースとテーブルを手動で作成するか、*td connector:issue* コマンドで *--auto-create-table* オプションを使用してデータベースとテーブルを自動作成してください:


```bash
$ 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* オプションを指定する必要はありません。


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

## スケジュール実行

増分FTPファイルインポートのために、定期的なData Connector実行をスケジュールすることができます。高可用性を実現するため、スケジューラの分散と運用には細心の注意を払っています。この機能を使用することで、ローカルデータセンターの*cron*デーモンは不要になります。

スケジュールインポートでは、FTP用Data Connectorは最初に指定されたプレフィックスに一致するすべてのファイル（例：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回目以降の実行では、connectorはアルファベット順（辞書式順序）で最後のパスより後にあるファイルのみをインポートします。（`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/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
```

## 設定とスケジュール履歴の表示

*td connector:show*は、スケジュールエントリの実行設定を表示します。


```
td connector:show daily_import
```

*td connector:history*は、スケジュールエントリの実行履歴を表示します。個々の実行結果を調査するには、*td job jobid*を使用してください。


```
td connector:history daily_import
```