# Sansan インポートインテグレーション

[Sansan](https://www.sansan.com/)に作成した名刺をインポートして分類できます。また、タグ名が付いた名刺もインポートできます。

## 前提条件

- [TD Toolbelt](https://toolbelt.treasuredata.com/)の使用経験を含む、Treasure Dataの基本知識
- Sansan API キー
- 認証された Treasure Data アカウントへのアクセス


## Sansan API キー情報の取得

Sansan API キーを取得するには:

1. Sansanにログインし、Settingsを選択します。![](/assets/image-20191021-140109.d3ea4b5511790f192ecfe064c580d3c80e1d4a3f1e4ecd084ac92e5d31c3765d.b88a27e1.png)
2. 設定ページのナビゲーションバーから**API Key**を選択し、API Keyをコピーします。
![](/assets/image-20191021-140120.a0e50a1b93894dc4312aaca8eacf406dc054f6af3dc50ff6e851d9ca45b738f4.b88a27e1.png)


## TD Consoleを使用した接続の作成

TD ConsoleでSansan接続を作成するには:

1. TD Consoleを開きます。
2. **Integrations Hub** >  **Catalog**に移動します。
3. カタログ画面の右端にある検索アイコンをクリックし、**Sansan**と入力します。
4. Sansanコネクタにカーソルを合わせ、Create Authenticationを選択します。![](/assets/sansan.57d1108388d3e36dedb1af1f13a2762cc1c5eb9ac151d4a03563764947005b4e.b88a27e1.png)
5. **Create Authentication**を選択します。
New Authenticationダイアログが開きます。
![](/assets/sansannewauth.3842debd43d132771f26b9f5ea5c1d5f39c971e03637d91d57d4f19acc031ddb.b88a27e1.png)
6. Sansan API Keyを入力します。
7. **Continue**を選択します。
8. Sansan接続の名前を入力します。
9. **Done**を選択します。


## TD Consoleの使用

### 認証の作成

Sansan接続の認証を作成するには:

1. TD Consoleから、**Integrations Hub** >  **Authentications**に移動します。
2. 画面の右端にある検索アイコンをクリックし、**Sansan**と入力します。


![](/assets/sansanauth.5fbf66e4978a09dfcf84b301046d0d5edad3daf08790ae164fb32fe56a7cfa3b.b88a27e1.png)

1. **New Source**を選択します。
Create Sourceダイアログが表示されます。ダイアログには以下のページがあります:
  - Connection
  - Source Table
  - Data Settings
  - Data Preview
  - Data Placement
各ページでソースの詳細を入力します。


### Connection

- **Data Transfer Name** -  名前を入力します。


### Source Table

- **Data Type** — Business CardまたはTagを選択します。


*Tag*

- **Tag Range** — AllまたはMeを選択します。
- *Business Card*
- **Import a set of business cards based on** — TermまたはConditionを選択します。Termを選択すると、指定した期間内に更新されたカードをインポートします。Conditionを選択すると、指定したタグ名に基づいてカードをインポートします。
  - **Include previous business card information** — 過去の名刺を含めます。同一人物として認識された名刺を個別のカードとしてインポートする場合は、このボックスをチェックします。
  - **Include Tags?** — 割り当てられたタグと共に名刺をインポートします。タグを名刺データに含める場合は、このボックスをチェックします。
  - **Filter by range of holder**:  — 名刺の範囲は「me」(自分が保有するカードのみ)または「all」(自分が閲覧できる範囲内のすべてのカード)として指定できます。


*Term*

- **Data Card Updated From** — この時刻以降に更新された名刺をインポートします。時刻はUTCで設定されます。
  - **Data Card Updated To** — この時刻までに更新された名刺をインポートします。時刻はUTCで設定されます。
  - **Incremental** — スケジュールに基づいてインポートする場合、取得されるデータの時間枠は実行ごとに自動的に前進します。例えば、初期設定が1月1日で期間が10日間の場合、最初の実行は1月1日から1月10日までに変更されたデータを取得し、2回目の実行は1月11日から1月20日まで、というように続きます。


*Condition*

- **Filter by Tag**: タグを含む名刺をインポートします。タグでインポートする場合は、これを選択します。選択した場合は、タグ名を指定する必要があります。タグで名刺をマッチングしない場合は、ボックスをチェックしないでください。
  - **Tag Name**: 指定した添付タグ名を持つ名刺をインポートします。1つの名前のみを入力してください。例: 'Treasure_Data'と入力すると、Treasure_Dataタグ名を含むすべての名刺がインポートされます。
  - **Tag range**: タグホルダーの範囲を指定します。MeまたはAllの範囲内で添付タグを持つ名刺をインポートします。


### Data Settings

- Page size. Sansan REST APIへの各呼び出しで返されるレコード数を決定します。



```
Type: number
Default: 300
```

- Maximum retry times. 各API呼び出しの最大リトライ回数を指定します。



```
Type: number
Default: 3
```


```

- 初回リトライ間隔（ミリ秒）。最初のリトライまでの待機時間を指定します。
```

Type: number
Default: 20000


```
- 最大リトライ間隔（ミリ秒）。リトライ間の最大待機時間を指定します。
```

Type: number
Default: 120000


```

### Data Preview

インポートを実行する前に、Generate Preview を選択してデータの[プレビュー](/products/customer-data-platform/integration-hub/Batch/Import/previewing-your-source-data.md)を表示できます。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** で転送の結果を確認できます。



## コマンドラインを使用したSansan接続の作成

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

1. 最新の[Treasure Data Toolbelt](https://toolbelt.treasuredata.com/)をインストールします。
2. 設定ファイル「load.yml」を作成します。

設定ファイルには、Sansanからコネクタに入力される内容を指定するin:セクションと、コネクタからTreasure Dataのデータベースに出力される内容を指定するout:セクションが含まれます。利用可能なoutモードの詳細については、付録を参照してください。

次の例は、指定されたTermに基づいて、インクリメンタルスケジューリングなしで名刺をインポートする方法を示しています。

```yaml
in:
  type: sansan
  api_key: "api key"
  target: bizcard
  query_by: "term"
  biz_range: "all"
  include_prev_card: true
  include_tags: true
out:
 mode: append
```

次の例は、指定されたTermに基づいて、インクリメンタルスケジューリングありで名刺をインポートする方法を示しています。


```yaml
in:
  type: sansan
  api_key: "api key"
  target: bizcard
  query_by: "term"
  biz_range: "all"
  include_prev_card: true
  include_tags: true
  updated_from: "2018-11-01T00:00:00.000Z"
  updated_to: "2018-11-12T00:00:00.000Z"
  incremental: true
out:
  mode: append
```

次の例は、タグフィルタなしで、指定されたConditionに基づいて名刺をインポートする方法を示しています。


```yaml
in:
  type: sansan
  api_key: "api key"
  target: bizcard
  query_by: "condition"
  biz_range: "all"
  include_prev_card: true
  include_tags: true
out:
 mode: append
```

次の例は、タグフィルタありで、指定されたConditionに基づいて名刺をインポートする方法を示しています。


```yaml
in:
  type: sansan
  api_key: "api key"
  target: bizcard
  query_by: "condition"
  biz_range: "all"
  include_prev_card: true
  include_tags: true
  gbiz_tag_filter: true
  biz_tag_name: "tag name"
  biz_tag_range: "all"
out:
 mode: append
```

次の例は、タグのみをインポートする方法を示しています。


```yaml
in:
  type: sansan api_key: "api key"
 target: tag
 tag_range: "all"
out:
 mode: append
```

### インポートするデータのプレビュー（オプション）

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


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

### ロードジョブの実行

td connector:issue を使用してジョブを実行します。

ロードジョブを実行する前に、データを保存するデータベースとテーブルを指定する必要があります。例：td_sample_db または td_sample_table。


```
$ td connector:issue load.yml \
     --database td_sample_db \
     --table td_sample_table \
     --time-column date_time_column
```

Treasure Data のストレージは時間によってパーティション化されているため、Treasure Data では --time-column オプションを指定することを推奨しています。このオプションを指定しない場合、データコネクタは最初の long 型列、または最初の timestamp 型列をパーティショニング時間として選択します。--time-column で指定する列の型は、long 型または timestamp 型である必要があります。利用可能な列名と型を確認するには、プレビュー結果を使用できます。一般的に、ほとんどのデータ型には「last_modified_date」列があります。

データに時間列がない場合は、add_time フィルターオプションを使用して列を追加できます。詳細は [add_time filter](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function) プラグインを参照してください。

td connector:issue は、データベース（例：sample_db）とテーブル（例：sample_table）が既に作成されていることを前提としています。データベースまたはテーブルが TD に存在しない場合、td connector:issue は失敗します。そのため、データベースとテーブルを手動で作成するか、td connector:issue で --auto-create-table を使用してデータベースとテーブルを自動的に作成する必要があります。


```
 $ td connector:issue load.yml \
      --database td_sample_db \
      --table td_sample_table \
      --time-column date_time_column \
      --auto-create-table
```

最後に、コマンドラインからロードジョブを送信します。データサイズによっては、処理に数時間かかる場合があります。

## スケジュール実行について

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

スケジュール実行は、Sansan からのデータ取得を定期的に試行する際のデータコネクタの動作を制御する設定パラメータをサポートしています：

- `incremental` この設定は、ロードモードを制御するために使用されます。ロードモードは、各オブジェクトに関連付けられたネイティブタイムスタンプフィールドの1つに基づいて、データコネクタが統合からデータを取得する方法を管理します。
- `columns` この設定は、Treasure Data にインポートされるデータのカスタムスキーマを定義するために使用されます。ここでは、興味のある列のみを定義できますが、取得するオブジェクトに存在することを確認してください。そうでない場合、これらの列は結果に含まれません。
- `last_record` この設定は、前回のロードジョブからの最後のレコードを制御するために使用されます。列名の `key` と列の値の `value` を含むオブジェクトが必要です。`key` は Sansan の列名と一致する必要があります。


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

td connector:create コマンドを使用して新しいスケジュールを作成できます。このコマンドには以下が必要です：

- スケジュールの名前
- cron 形式のスケジュール
- データを保存するデータベースの名前
- データを保存するテーブルの名前
- データコネクタ設定ファイル
- cron パラメータは次のオプションを受け付けます：'@hourly'、'@daily'、'@monthly'


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

**例**


```
$ td connector:create \
    daily_import \
    "10 0 * * *" \
    td_sample_db \
    td_sample_table \
    load.yml
```

Treasure Data のストレージは時間によってパーティション化されているため、TD では --time-column オプションを指定することも推奨しています。


```
$ td connector:create \
    daily_import \
    "10 0 * * *" \
    td_sample_db \
    td_sample_table \
    load.yml \
    --time-column created_at
```

### スケジュールの一覧表示

コマンド td connector:list を入力すると、現在スケジュールされているエントリのリストを表示できます。


```
$ td connector:list
```

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

td connector:show はスケジュールの詳細を表示します。


```
td connector:show daily_import
```