# Gigya Import Integration CLI

CLIを使用して接続を設定できます。

## Treasure Data Toolbeltのインストール

ターミナルを開き、以下のコマンドを実行して最新の[Treasure Data Toolbelt](https://toolbelt.treasuredata.com/)をインストールします。

## *load.yml*ファイルの準備

load.ymlを準備します。in:セクションでは、GigyaからコネクタへのデータINPUTを指定し、out:セクションでは、コネクタからTreasure Dataのデータベースへのデータ出力を指定します。

以下のようにGigyaアカウントのアクセス情報を提供します:


```yaml
in:
  type: gigya
  data_center: US1
  authentication_mode: key_secret
  application_key: your_application_user_key
  secret_key: your_application_secret_key
  api_key: your_api_key
  data_source: account
  query: SELECT * FROM accounts
  fields_to_exclude: "XffFirstIp, httpReq"
  batch_size: 1000
```

設定キーと説明は以下の通りです:

| **設定キー** | **タイプ** | **必須** | **説明** |
|  --- | --- | --- | --- |
| type | string | yes | コネクタタイプ |
| data_center | string | yes | データセンターの場所を指定します (利用可能な値は **US1, EU1, AU1, RU1, CN1**) |
| authentication_mode | string | no | 認証方法、現在は **key_secret** のみサポート |
| application_key | string | yes | アプリケーションのユーザーキー |
| secret_key | string | yes | アプリケーションのシークレットキー |
| api_key | string | yes | APIキー |
| data_source | string | no | ターゲットデータソース (利用可能な値は **account**, **profile**, **data_store**, **audit**) |
| query | string | yes | カスタムGigyaクエリ |
| `fields_to_exclude` | string | no | `GigyaのAPI仕様上、SELECT文で取り込む列を指定することができません。このパラメータは不要な列を削除するために使用できます。` |
| batch_size | number | no | 1回のバッチでの最大レコード数 |


## インポートするデータのプレビュー

td connector:previewコマンドを使用して、インポートするデータをプレビューできます。


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

## Load Jobの実行

td connector:issueを使用してジョブを実行します。データサイズによっては、処理に数時間かかる場合があります。以下が必要です:

- スケジュールの名前
- cron形式のスケジュール
- データが保存されるデータベースとテーブル
- Data Connector設定ファイル



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

上記のコマンドは、*database(td_sample_db)*と*table(td_sample_table)*が既に作成されていることを前提としています。データベースまたはテーブルがTDに存在しない場合、このコマンドは成功しません。データベースとテーブルは[手動で](https://docs.treasuredata.com/smart/project-product-documentation/data-management)作成するか、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
```

Treasure Dataのストレージは時間でパーティション分割されているため、--time-columnオプションを指定することをお勧めします。このオプションが指定されていない場合、データコネクタは最初のlong型またはtimestamp型の列をパーティション分割時間として選択します。--time-columnで指定する列の型は、long型またはtimestamp型のいずれかである必要があります。利用可能な列名と型を確認するには、Preview resultsを使用してください。一般的に、ほとんどのデータ型にはlast_modified_date列があります。

出力の最後に時間列が利用可能です。


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

データに時間列がない場合は、add_timeフィルターを使用して追加できます。設定ファイルにadd_timeフィルターを追加することで、"**time**"列を追加できます。


```yaml
in:
  type: xxxxx
  ...
filters:
- type: add_time
  from_value:
    mode: upload_time
  to_column:
    name: time
out:
  type: td
```

詳細については、[add_timeフィルタープラグイン](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function)を参照してください。

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


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

## スケジュール実行

定期的なGigyaインポートのために、定期的なデータコネクタ実行をスケジュールできます。高可用性を確保するため、スケジューラーを慎重に設定しています。この機能を使用することで、ローカルデータセンターにcronデーモンを配置する必要がなくなります。

スケジュールされたインポートでは、Gigya用データコネクタは指定されたターゲットに一致するすべてのオブジェクトをインポートします。

スケジュール実行では、各オブジェクトに関連付けられたネイティブのタイムスタンプまたは数値フィールドのいずれかに基づいて、Gigyaからデータを取得する際のデータコネクタの動作を制御する追加の設定パラメータがサポートされています。

- incremental この設定は、ロードモードを制御するために使用され、各オブジェクトに関連付けられたネイティブのタイムスタンプまたは数値フィールドのいずれかに基づいて、データコネクタがGigyaからデータを取得する方法を管理します
- incremental_columnn この設定は、Treasure Dataにインポートする基準列を定義するために使用されます。このフィールドには1つの列のみを定義できます。推奨値は**created、createdTimestamp、updated、updatedTimestamp**です


以下は、incrementalモードを使用したロードファイルの例です


```yaml
in:

  type: gigya

  data_center: US1

  authentication_mode: key_secret

  application_key: your_application_user_key

  secret_key: your_application_secret_key

  api_key: your_api_key

  data_source: account

  batch_size: 1000

  query: SELECT * FROM accounts

  incremental: true

  incremental_column: created

filters:

- type: add_time

  from_value:

    mode: upload_time

  to_column:

    name: time
```

**スケジュールの作成**

td connector:create コマンドを使用して新しいスケジュールを作成できます。スケジュールの名前、cron形式のスケジュール、データが保存されるデータベースとテーブル、およびデータコネクタ設定ファイルが必要です。

`cron` パラメータは、`@hourly`、`@daily`、`@monthly` のオプションを受け付けます。

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

td connector:create コマンドを使用して、毎日実行するインポート用のスケジュールジョブを作成できます。


```
td connector:create connector_name @daily connector_database connector_table load.yml
```

# プラグインのモード

load.yml ファイルの out セクションでインポートモードを指定できます。

out: セクションは、データが Treasure Data テーブルにどのようにインポートされるかを制御します。
たとえば、Treasure Data の既存のテーブルにデータを追加するか、データを置き換えるかを選択できます。

出力モードは、データが Treasure Data に配置されるときにデータを変更する方法です。

- **Append**（デフォルト）: レコードはターゲットテーブルに追加されます。
- **Replace**（td 0.11.10 以降で利用可能）: ターゲットテーブルのデータを置き換えます。ターゲットテーブルに加えられた手動のスキーマ変更はそのまま残ります。


例:


```yaml
in:

  ...

out:

  mode: append
in:

  ...

out:

  mode: replace
```