# Zendesk Import Integration

Treasure Dataでは、組織のZendeskアカウントから直接データをインポートできます。

## 前提条件

- Treasure Dataの基本的な知識
- Zendeskアカウント
- Chatデータを取得するためのZendesk Zopimアカウント


## 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経由でZendeskからインポート

### 新しい認証の作成

1. TD Consoleを開きます。
2. Integrations Hub > Catalogに移動します。
3. Zendeskを検索して選択します。
![](/assets/image-20190922-195712.51c26fb4ae060d3efff9c32b00cf5c83086b034129b47665e5c072bb866ae309.cbc89e54.png)
4. **Create**をクリックします。認証された接続を作成します。次のダイアログが開きます。
![](/assets/image-20190922-195749.670b71a2bdce1b3fa92100068236fc73ec79be19678999bf82825c9c9c379530.cbc89e54.png)
5. **Auth method**には3つのオプションがあります：basic、token、oauth。
  1. Chatデータをインポートするには、ZendeskのLogin Urlに次のURLを入力します：[https://www.zopim.com](https://www.zopim.com)。ChatではToken認証はサポートされていません。
6. すべての必須フィールドを入力し、**Continue**をクリックします。
7. 新しいZendesk接続に名前を付けます。**Done**をクリックします。
![](/assets/image-20200324-214851.a12b6b30b82a7ba8cbba0ca8d519d664d0225c26677a9c6734da9b9595885c79.cbc89e54.png)


### Treasure Dataへデータを転送

認証された接続を作成すると、自動的にAuthenticationsタブに移動します。

1. 作成した接続を検索し、**New Source**をクリックします。
2. 適切なフィールドを編集します。
![](/assets/screenshot-2023-08-15-at-10.52.05.cf0edd7a535afbbf112e43fd8f3edae3f81f65aba3708c38d25226065e148fc7.cbc89e54.png)


| **Source** | Zendeskから転送するオブジェクトの種類を指定します：tickets、ticket_fields、ticket_forms、ticket_events、ticket_metrics、users、organizations、scores、recipients、object_records、relationship_records、user_events、chat   - object_recordsとrelationship_recordsはZendeskカスタムオブジェクトに関する情報を提供します - scoresとrecipientsはZendesk NPSに関する情報を提供します - Chatの制限事項：    - 管理者または所有者のみがChatデータを取得する権限を持ちます。   - 「Include Subresources」および「De-duplicate records」オプションはサポートされていません |
|  --- | --- |
| **Incremental** | コネクタがインクリメンタルモードで実行できるようにし、**Start time**と**End time**を使用できるようにします。 |
| **Start time** | 'start_time'以降に更新されたオブジェクトのみを選択できるようにします   - **Start time**が指定されていない場合、すべてのオブジェクトが最初から取得されます。 |
| **End time** | 'end_time'まで更新されたオブジェクトのみを選択できるようにします。   - **End time**が指定されていない場合、現在までのすべてのオブジェクトが取得されます。 - **Start time**と**End time**を組み合わせて、'start_time'から'end_time'までの特定の期間内に更新されたオブジェクトのみを選択できます |
| **Enable cursor-based API** | cursor APIフローを使用して100,000件を超えるレコードを取得できるようにします。   - **ticketsとusers source**のみに適用されます - **Start time**のみを使用した**incremental**をサポートします |


### ソースプレビュー

1. データをプレビューします。変更を加えるには、Advanced Settingsをクリックします。
![](/assets/image-20190922-200213.1679d6dbb1d72eef40fd38ea8f3c9ba7ae1f1578c5b30424ed88072b799bb3d0.cbc89e54.png)
2. Nextを選択します。


#### 詳細設定

1. Advanced Settingsを選択すると、次のダイアログが開きます。
![](/assets/image-20190922-200311.3f20706cccaa48c405e79f84c7ca685dfe3737496efa746cc9049d5c89c0ecd2.cbc89e54.png)![](/assets/image-20190922-200338.25048547ccc49a8e0c73026d82440a3bbe3a6f5c06a6b040b435983dea1c6e60.cbc89e54.png)
2. パラメータを編集します。Save and Nextを選択します。


| **Parameter** | **Description** |
|  --- | --- |
| **Include Subresources** | メインオブジェクトと共にサブリソースを取得できるようにします。**Add**をクリックして名前でサブリソースを追加し、対応するカラムも**Add**します。サブリソースはJSONオブジェクトとして扱われ、同じ名前のカラムに表示されます。   - Zendeskでは、このエンドポイントがサポートされています：[GET /api/v2/users/{user_id}/organizations.json](https://developer.zendesk.com/rest_api/docs/support/users#list-users) つまり、organizationsをusersのサブリソースと見なすことができます。ユーザーが所属するorganizationsのすべての情報を取得できます。 - これを設定するには、'organizations'をサブリソースとして追加し、同じ名前のカラムをもう1つ追加する必要があります。データ型はJSONである必要があります。 - Include SubresourcesはChatではサポートされていません。 |
| **De-duplicated Records** | Zendesk APIは重複を防止しないため、インクリメンタルモードで実行する際に重複レコードを回避できるようにします。   - 重複排除はChatではサポートされていません。 |
| **Retry Limit** | エラーが発生したときにジョブが再試行する回数を示します。 |
| **Initial retry interval seconds** | 再試行前の最初の待機時間を示します。秒単位で測定されます。 |


### 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** で転送の結果を確認できます。

## Workflow経由でZendeskからインポート

Zendeskからデータをインポートするサンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/zendesk)を参照してください。

## CLI経由でZendeskからインポート

### 'td'コマンドのインストール

最新の[TD Toolbelt](https://api-docs.treasuredata.com/en/tools/cli/quickstart/#install)をインストールします。

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

次の例に示すように、`login_url`、`username`（メールアドレス）、`token`、および`target`を使用して`seed.yml`を準備します。この例では、"append"モードを使用します。


```yaml
in:
  type: zendesk
  login_url: https://YOUR_DOMAIN_NAME.zendesk.com
  auth_method: token
  username: YOUR_EMAIL_ADDRESS
  token: YOUR_API_TOKEN
  target: tickets
  start_time: "2007-01-01 00:00:00+0000"
  enable_cursor_based_api: true
out:
  mode: append
```

`token`は、`Admin Home` –> `CHANNELS` –> `API` –> `"add new token"`（`https://YOUR_DOMAIN_NAME.zendesk.com/agent/admin/api`）から作成できます。

`target`は、Zendeskからダンプするオブジェクトのタイプを指定します。tickets、ticket_events、ticket_forms、ticket_fields、users、organizations、scores、recipients、object_records、relationship_records、user_eventsがサポートされています。

利用可能な`out`モードの詳細については、付録を参照してください。

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

`connector:guess`を使用します。このコマンドは、ターゲットデータを自動的に読み取り、データフォーマットをインテリジェントに推測します。


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

`load.yml`ファイルを開くと、ファイルフォーマット、エンコーディング、カラム名、タイプなどを含む推測されたファイルフォーマット定義が表示されます。


```yaml
in:
  type: zendesk
  login_url: https://YOUR_DOMAIN_NAME.zendesk.com
  auth_method: token
  username: YOUR_EMAIL_ADDRESS
  token: YOUR_API_TOKEN
  target: tickets
  start_time: '2019-05-15T00:00:00+00:00'
  columns:
   - {name: url, type: string}
   - {name: id, type: long}
   - {name: external_id, type: string}
   - {name: via, type: json}
   - {name: created_at, type: timestamp, format: "%Y-%m-%dT%H:%M:%S%z"}
   - {name: updated_at, type: timestamp, format: "%Y-%m-%dT%H:%M:%S%z"}
   - {name: type, type: string}
   - {name: subject, type: string}
   - {name: raw_subject, type: string}
   - {name: description, type: string}
   - {name: priority, type: string}
   - {name: status, type: string}
   - {name: recipient, type: string}
   - {name: requester_id, type: string}
   - {name: submitter_id, type: string}
   - {name: assignee_id, type: string}
   - {name: organization_id, type: string}
   - {name: group_id, type: string}
   - {name: collaborator_ids, type: json}
   - {name: follower_ids, type: json}
   - {name: email_cc_ids, type: json}
   - {name: forum_topic_id, type: string}
   - {name: problem_id, type: string}
   - {name: has_incidents, type: boolean}
   - {name: is_public, type: boolean}
   - {name: due_at, type: string}
   - {name: tags, type: json}
   - {name: custom_fields, type: json}
   - {name: satisfaction_rating, type: json}
   - {name: sharing_agreement_ids, type: json}
   - {name: fields, type: json}
   - {name: followup_ids, type: json}
   - {name: ticket_form_id, type: string}
   - {name: brand_id, type: string}
   - {name: satisfaction_probability, type: string}
  - {name: allow_channelback, type: boolean}
  - {name: allow_attachments, type: boolean}
  - {name: generated_timestamp, type: long}
out:
  {mode: append}
exec: {}
filters:
  type: add_time
  from_value:
    {mode: upload_time}
    to_column: {name: time}
```

次に、`preview`コマンドを使用して、システムがファイルをどのように解析するかをプレビューできます。


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

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

Data Connectorは、「boolean」、「long」、「double」、「string」、および「timestamp」型の解析をサポートしています。

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

ロードジョブを送信します。データサイズによっては数時間かかる場合があります。ユーザーは、データが保存されるデータベースとテーブルを指定する必要があります。


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

上記のコマンドは、*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`オプションを使用してデータベースとテーブルを自動的に作成してください。


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

「--time-column」オプションを使用して、Time Formatカラムを「Partitioning Key」に割り当てることができます。

### インクリメンタルロード

`incremental`フラグを使用して、Zendeskからレコードをインクリメンタルにロードできます。`False`の場合、next.ymlの`start_time`と`end_time`は更新されません。コネクターは常に静的な条件でZendeskからすべてのデータを取得します。`True`の場合、next.ymlで`start_time`と`end_time`が更新されます。デフォルトは`True`です。


```yaml
in:
  type: zendesk
  login_url: https://YOUR_DOMAIN_NAME.zendesk.com
  auth_method: token
  username: YOUR_EMAIL_ADDRESS
  token: YOUR_API_TOKEN
  target: tickets
  start_time: "2007-01-01 00:00:00+0000"  end_time: "2008-01-01 00:00:00+0000"
  incremental: true
out:
  mode: append
```

### カーソルページネーションを使用したリストのページネーション

Zendeskは、100,000件を超えるレコードを取得できるページネーションエンドポイントをサポートしています。このエンドポイントは、usersとticketsターゲットにのみ適用されます。詳細については、[Introducing Pagination Changes - Zendesk API](https://support.zendesk.com/hc/en-us/articles/4408846180634-Introducing-Pagination-Changes-Zendesk-API)を参照してください。

新しいエンドポイントを使用するには、**Enable cursor-based API**を有効にしてください。

## 詳細情報

- [Zendesk Data Connectorのオプションリスト](https://github.com/treasure-data/embulk-input-zendesk)