# Cvent Import Integration

Treasure Data Customer Data Platformを使用して、人気のあるイベント管理ソフトウェアであるCventからイベント情報を取り込みます。

# 前提条件

- TD ConsoleおよびTD Toolbeltの基本知識
- Cventの基本知識


# TD Consoleの使用

## 新しい接続の作成

1. **TD Console**を開きます。
2. **Integrations Hub > Catalog**に移動します。
3. Catalog画面の右端にある検索アイコンをクリックし、**cvent**と入力します。
4. cventコネクタにカーソルを合わせ、**Create Authentication**を選択します。![](/assets/cvent.b6abade4fadb6d63f11a81ed18cd6b44fd1d377e4a724815f694dacc9e648bc8.5197f004.png)
5. 必要な認証情報を編集します。
API User NameとAPI Passwordは、Cventアプリケーションのユーザー名とパスワードとは異なりますので、API User NameとAPI Passwordの生成については、Cvent管理者に問い合わせてください。
[Cvent Sandbox](https://sandbox-app.cvent.com/)に対してテストAPIアカウントを使用している場合は、Sandboxにチェックを入れてください。
![](/assets/image-20191021-142118.fe0ab3154b27ca3a454ab88b4a883f7ab01931cf625f5c2bdde2287fc980c73d.5197f004.png)
6. **Continue**をクリックします。
7. 接続に名前を付けます。
8. **Done**をクリックします。


## 新しいSourceの作成

認証された接続から**New Source**を選択します。

![](/assets/image-20191021-142141.fb9dd4757fbd5b6f596f546b90755791bd27eee11abc6c92342e37718c3b95d9.5197f004.png)

この転送のデータタイプと取得時間範囲を選択します。

![](/assets/image-20191021-142517.189b959171d711ac782a3b043a71e868e92a3c363e8470bcfb30f0b907cdedea.5197f004.png)

**Data Type**: サポートされているタイプは、Registration、Invitee、Contact、Eventです。

**Start Date**: データ時間ウィンドウの開始時点です。上記の画像の例では、2018-08-01 00:00:00 UTCから変更されたすべてのRegistrationが取得されます。

**Duration**: 時間ウィンドウの長さです。上記の例では、時間の長さは2018-08-01 00:00:00 UTCから2018-09-01 00:00:00 UTCまでの取得に相当します。

**Incremental**: スケジュールで実行する場合、取得されるデータの時間ウィンドウは、各実行ごとに自動的に前方にシフトします。たとえば、初期設定が1月1日で期間が10日の場合、最初の実行では1月1日から1月10日までに変更されたデータが取得され、2回目の実行では1月11日から1月20日までに変更されたデータが取得されます。以降も同様です。

## プレビュー

![](/assets/image-20191021-142538.ae68514764e07a4f348d916facb4c6adba698ba372ae82408de413d297afe4ff.5197f004.png)

これは、指定されたデータ転送設定における実際のデータのプレビューを示しています。列はアルファベット順にソートされていますが、カスタムフィールド列（存在する場合）は末尾に配置されます。この順序は、ターゲットデータベースの最終結果にも適用されます。

## ターゲットデータベースとテーブルの選択

既存のデータベースとテーブルを選択するか、新しく作成します。

![](/assets/image-20191021-142550.b82c90f3b712bad3b721e551f443f980daf576e3dadbd469c6d45dd6f36f1d52.5197f004.png)

このコネクタは、Cvent APIから受信したリテラルの時刻値を挿入します。つまり、時刻値はCventサーバーの暗黙的なタイムゾーンに対して相対的であり、UTCであると*仮定*されます。また、Eventデータタイプの時刻関連フィールドは、そのイベント自体のタイムゾーンに対して相対的です。これは、Data Storage Timezoneがデータの実際のタイムゾーンを示していないことを意味します。

## スケジューリング

必要に応じてスケジュールを設定します。スケジュールされた時刻になるとインポートが開始されます。「Once now」を選択した場合は即座に開始されます。

![](/assets/image-20191021-142236.0b2d7b491adf7fdfc618f568aa3157d9deb307f69b94d9c87323c475fb1e2009.5197f004.png)

**START TRANSFER**を選択し、Jobsページで実行中のジョブを確認します。

# コマンドラインの使用

## 前提条件のインストール

Ruby gemを介して最新の`td`ツールをインストールします：


```
$ gem install td
$ td --version
0.15.8
```

他のインストール方法もあります。詳細については、[Treasure Data Toolbelt](https://toolbelt.treasuredata.com/)を確認してください。

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

設定ファイルを作成します：


```
in:
  type: cvent
  target: registration
  account_name: xxxxxxxxxxxxxxxx
  api_username: xxxxxxxxxxxxxxxx
  api_password: xxxxxxxxxxxxxxxx
  start_time: 2017-08-01
  fetch_days: 31
  parallel: true

  out:
  mode: append
```

## プレビュー


```
$ td connector:preview config.yml
  +---------------------------+---------------+-----------------+---+-----------------+-------------------+---------------------------------+
  | archive_date:timestamp    | capacity:long | category:string |...| currency:string | event_code:string | event_description:string        |
  +---------------------------+---------------+-----------------+---+-----------------+-------------------+---------------------------------+
  | "2018-12-29 21:59:00 UTC" | -1            | "Conference"    |...| "U.S. Dollar"   | "KGNH2JXF45K"     | ""                              |
  | "2019-01-26 21:59:00 UTC" | 500           | "Conference"    |...| "U.S. Dollar"   | "W4NKF4YWY4W"     | "Devcon for Cvent TD Engineers" |
  +---------------------------+---------------+-----------------+---+-----------------+-------------------+---------------------------------+
```

## ロードジョブの実行

データが保存されるデータベースとテーブルを指定する必要があります。

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

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

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


```
$ td connector:issue config.yml \
  --database sample_db \
  --table sample_table
```

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


```
$ td connector:issue load.yml \
  --database sample_db \
  --table sample_table \
  --auto-create-table
```

# スケジュール実行

定期的な Cvent インポートのために、データコネクタの定期実行をスケジュールできます。この機能を使用することで、ローカルデータセンター上で `cron` デーモンを実行する必要がなくなります。

## スケジュールの作成

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


```
$ td connector:create \
  daily_cvent_import \
  "10 0 * * *" \
  sample_db \
  sample_table \
  config.yml
```

|  |
|  --- |
| `cron` パラメータは、`@hourly`、`@daily`、`@monthly` の3つの特別なオプションも受け付けます。詳細については、[Scheduled Jobs](https://docs.treasuredata.com/articles/project-product-documentation/scheduling+Jobs+Using+TD+Console) を参照してください。 |


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

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

`td connector:list` を使用して、現在スケジュールされているエントリの一覧を表示できます。


```
$ td connector:list
  +--------------------+------------+----------+-------+-----------------+--------------+
  | Name               | Cron       | Timezone | Delay | Database        | Table        |
  +--------------------+------------+----------+-------+-----------------+--------------+
  | daily_cvent_import | 10 0 * * * | UTC      | 0     | sample_database | sample_table |
  +--------------------+------------+----------+-------+-----------------+--------------+
```

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

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


```
$ td connector:show daily_cvent_import
  Name     : daily_cvent_import
  Cron     : 10 0 * * *
  Timezone : UTC
  Delay    : 0
  Database : sample_db
  Table    : sample_table
```

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


```
$ td connector:history daily_cvent_import
  +--------+---------+---------+-----------+--------------+----------+---------------------------+----------+
  | JobID  | Status  | Records | Database  | Table        | Priority | Started                   | Duration |
  +--------+---------+---------+-----------+--------------+----------+---------------------------+----------+
  | 578066 | success | 20000   | sample_db | sample_table | 0        | 2015-04-18 00:10:05 +0000 | 160      |
  | 577968 | success | 20000   | sample_db | sample_table | 0        | 2015-04-17 00:10:07 +0000 | 161      |
  | 577914 | success | 20000   | sample_db | sample_table | 0        | 2015-04-16 00:10:03 +0000 | 152      |
  | 577872 | success | 20000   | sample_db | sample_table | 0        | 2015-04-15 00:10:04 +0000 | 163      |
  | 577810 | success | 20000   | sample_db | sample_table | 0        | 2015-04-14 00:10:04 +0000 | 164      |
  | 577766 | success | 20000   | sample_db | sample_table | 0        | 2015-04-13 00:10:04 +0000 | 155      |
  | 577710 | success | 20000   | sample_db | sample_table | 0        | 2015-04-12 00:10:05 +0000 | 156      |
  | 577610 | success | 20000   | sample_db | sample_table | 0        | 2015-04-11 00:10:04 +0000 | 157      |
  +--------+---------+---------+-----------+--------------+----------+---------------------------+----------+
```

## スケジュールの削除

`td connector:delete` は、スケジュールを削除します。


```
$ td connector:delete daily_cvent_import
```

# 制限事項

Cvent Connector には、Cvent API と同じアップストリーム制限があります。これは以下を意味します:

- Contact、Invitee、Event は、同じ秒に変更された25,000件未満のレコードをデータが含む場合にのみ取得可能です。
- Registration は、同じ秒に変更された25,000件未満のレコードをデータが含む場合にのみ取得可能です。
- 1日あたり10,000リクエストの上限があり、これはおおよそ1日あたり200万レコードに相当します。


# 付録A: カラム名のマッピング方法

すべてのカラムは [snake case](https://en.wikipedia.org/wiki/Snake_case) です (例: first_name、last_name)。

Cvent API のアップストリームの問題により、「RSVP By Date」は異常なカラム名にマッピングされます: "rsv_pby_date"

カスタムフィールド名は、以下の手順で snake case にマッピングされます:

1. すべての非英数字をアンダースコア "_" に置き換える
2. ステップ1の後、先頭と末尾のすべてのアンダースコアを削除する
3. 最初の文字が数字の場合、名前の前に "col_" を付ける
4. 連続するすべてのアンダースコア "_" を削除する
5. 前述の手順の後に名前が空の場合、"custom_field" と名付ける (このカラムフィールド名は、TD Console のカラム名とは異なります)
6. すべての文字を小文字にする


例: "Hello @ World" は "hello_world" にマッピングされ、"" (空) は "custom_field" にマッピングされます。
命名の競合がある場合、競合するカスタムフィールド名にはフィールドの ID が追加されます。例えば、Contact タイプに「First Name」というカスタムフィールド名がある場合 (すでにその名前の事前定義フィールドが存在します)、カスタムフィールド名は "first_name_A3E3_ERQNIHOIU_324AE" のようなものにマッピングされます。

# 付録B: Event のタイムゾーン

![](/assets/image-20191021-142409.4944b67473ce3c61fe407a67d0d58d8987608c4a117099d887859b936cac890f.5197f004.png)

他の datetime フィールドとは異なり、上記の4つの event 関連の datetime フィールドはテキストとしてインポートされ、わずかに異なる形式でデータベースで認識できます (例: Start Date は "2018-10-09T17:59:00" としてインポートされ、Start Date がデフォルトの datetime 値の場合は "2018-10-09 17:59:00.000" になります)。Event 関連の datetime フィールドは、それぞれの event タイムゾーンに対して相対的です。したがって、これらの event 関連の datetime フィールドは、他のフィールドのような絶対時刻参照として扱われません。

Event 関連の datetime フィールドは、インポート後に以下のカラムに対応します:

| Target Type | Column |
|  --- | --- |
| Event | `event_start_date` |
| Event | `event_end_date` |
| Event | `archive_date` |
| Event | `rsv_pby_date` |
| Registration | `event_start_date` |
| Invitee | `event_start_date` |