# Oracle Eloqua Import Integration

このOracle Eloqua用データコネクタを使用すると、コンタクトデータとアクティビティデータをTreasure Dataにインポートできます。

## 前提条件

Treasure Dataの基本的な知識。

## 要件と制限事項

- Treasure Dataアカウント
- Oracle Eloquaアカウント


## 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からOracle Eloquaをインポート

### 認証の作成

最初のステップは、認証情報のセットを使用して新しい認証を作成することです。

1. **Integrations Hub**を選択します。
2. **Catalog**を選択します。


![](/assets/image2021-9-30_14-38-2.ca92fa4ab9277dca95973c6bd413fc662a3f0d04b57d58f7a8c952a29f28bbec.c68a7c88.png)

1. カタログで**Oracle Eloqua**を検索します。アイコンの上にマウスを置き、**Create Authentication**を選択します。


![](/assets/oracleeloqua.c70b013008f28b4d52b898e49719694ae28dbb3b69b3c2f77f1d588a51ab62fd.c68a7c88.png)

1. **Credentials**タブが選択されていることを確認し、統合のための認証情報を入力します。


**認証フィールド**

| Parameter | Description |
|  --- | --- |
| Authentication Method | Basic (デフォルト) |
| Eloqua Site Name | Oracle EloquaサイトのURL |
| Username | Oracle Eloquaアカウントのユーザー名 |
| Password | アカウントのパスワード |


1. **Continue**を選択します。
2. 認証の名前を入力し、**Done**を選択します。


### ソースの作成

1. TD Consoleを開きます。
2. **Integrations Hub** > **Authentications**に移動します。
3. 新しい認証を見つけて、**New Source**を選択します。


### 接続の作成

接続タブで、以下の情報を入力し、**Next**を選択します。

| Parameter | Description |
|  --- | --- |
| Data Transfer Name | 転送の名前を定義できます。 |
| Authentication | 転送に使用される認証名。 |


![](/assets/eloqua_createsource.157580f09145e469ddf19828f7b155751aac1c430452ede5c9ba67349722a285.c68a7c88.png)

### ソーステーブルの識別

Source Tableタブで以下の情報を入力し、**Next**を選択します。

| Parameter | Description |
|  --- | --- |
| Data Type | ContactまたはActivityを選択 |
| Import Fields | インポートするコンタクトフィールドを選択します。Data Type Contactの場合のみサポート。フィールド名はカンマで区切る必要があります。 |
| Start Time | この時刻以降のデータをインポート |
| End Time | この時刻までのデータをインポート |
| Incremental Loading | Incremental loadingオプションがチェックされている場合、新規および更新されたコンタクトを増分的にインポートします。 |
| Update End Time | 終了時刻が増分ジョブの実行時刻よりも大きく、Update End Timeオプションがチェックされている場合、終了時刻はジョブの実行時刻に設定されます。 |


![](/assets/screenshot-2024-06-18-at-16.09.31.c5f0e0d578807e1d343de018e629c5376751fea0d31e23c77c0b2e76594bd3dd.c68a7c88.png)

### データ設定の定義

Data Settingタブで以下の情報を入力し、**Next**を選択します。

| Parameter | Description |
|  --- | --- |
| Max retry count per API call | API呼び出しごとの最大リトライ回数 |
| Initial retry interval per API call | API呼び出しごとの初期リトライ間隔（ミリ秒） |
| Max retry interval per API call | API呼び出しごとの最大リトライ間隔（ミリ秒） |
| HTTP Connect Timeout | ミリ秒単位、デフォルト: 3分 |
| HTTP Read Timeout | ミリ秒単位、デフォルト: 3分 |


![](/assets/eloqua_datasettings.638804e3b0446e2f310105dd4b6e0aead2780db40d814c4c9543c854f2ac8760.c68a7c88.png)

### データのプレビュー

インポートを実行する前に、**Generate Preview**を選択してデータの[プレビュー](https://docs.treasuredata.com/smart/project-product-documentation/previewing-your-source-data)を確認できます。

![](/assets/eloqua_preview.0d058174a44456ec606152d8807dbe774aa6697620a26f01a3db1aa91f2bd7d1.c68a7c88.png)

### データ配置の定義

データ配置では、データを配置するターゲットのデータベースとテーブルを選択し、インポートの実行頻度を指定します。

1. **Database** > **Select** **an existing** または **Create New Database** を選択します。
2. オプションで、データベース名を入力します。
3. **Table** > **Select an existing** または **Create New Table** を選択します。
4. オプションで、テーブル名を入力します。
5. データをインポートする方法を選択します。
  - **Append** (デフォルト) - データインポートの結果がテーブルに追加されます。
テーブルが存在しない場合は、作成されます。
  - **Always Replace** - 既存のテーブルの全コンテンツをクエリの結果出力で置き換えます。テーブルが存在しない場合は、新しいテーブルが作成されます。
  - **Replace on New Data**: 新しいデータが存在する場合のみ、既存のテーブルの全コンテンツを結果出力で置き換えます。
6. **Timestamp-based Partition Key** カラムを選択します。
デフォルトキーとは異なるパーティションキーシードを設定する場合は、パーティション時間として long または timestamp カラムを指定できます。デフォルトの時間カラムとして、add_time フィルターを使用した upload_time が使用されます。
7. データストレージの **Data Storage Timezone** を選択します。
8. **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** を選択します。
9. **Create & Run Now** を選択します。


転送の実行後、**Data Workbench** > **Databases** で転送の結果を確認できます。

![](/assets/eloqua_dataplacement.ae863c8687a19d99313193ab6ad1a74f2bf0faf9f03e8d6b591a3e41f63bd599.c68a7c88.png)

## CLI (Toolbelt) 経由での Oracle Eloqua からのインポート

コネクターをセットアップする前に、最新の [TD Toolbelt](https://toolbelt.treasuredata.com/) をインストールしてください。バージョン 0.11.9 以降が必要です。

バージョンを確認するには:


```
$ td --version
0.16.10
```

### シード設定ファイルの作成 (seed.yml)


```
in:
  type: eloqua
  site_name: "YOUR_ELOQUA_SITE_NAME"
  username: "YOUR_USERNAME"
  password: "YOURPASSWORD"
  target: activity
  data_type: EmailOpen
  start_time: "2018-05-07T00:00:00Z"
  end_time: "2018-05-08T00:00:00Z"
out:
  mode: replace
```

| **オプション名** | **説明** | **型** | **必須?** | **デフォルト値** |
|  --- | --- | --- | --- | --- |
| type |  |  |  |  |
| site_name | Eloqua サイト名 |  |  |  |
| username | ユーザー名 | string | yes | N/A |
| password | パスワード | string | yes | N/A |
| target | contact または activity | string | yes | contact |
| data_type | `EmailOpen, Bounceback, Unsubscribe, EmailSend, Subscribe, EmailClickthrough,WebVisit, PageView, FormSubmit, External Activity` |  | yes, activity target の場合 | EmailOpen |
| import_fields | データタイプ contact に対してインポートされるフィールド名。この値が設定されておらず、contact データタイプが 250 個以上のフィールドを持つ場合、最初の 250 個のフィールドがインポートされます。その他のフィールドはスキップされます。 | string | no |  |
| start_time | レコードの取得を開始する日時を指定します。フォーマット `yyyy-MM-dd'T'hh:mm:ss.SSS'Z'` (例: '2018-05-07T00:00:00Z')。排他的 | string | yes | N/A |
| end_time | レコードを取得する許容期間を指定します。フォーマット `yyyy-MM-dd'T'hh:mm:ss.SSS'Z'` (例: '2018-05-08T00:00:00Z')。包括的 | string | yes | N/A |
| incremental | "mode: append" の場合は `true`、"mode: replace" の場合は `false`。 | bool | no | true |
| incremental_field | このフィールドに基づいて増分処理を行います。サポートされる値: ActivityDate、LinkedToContactDate、CampaignResponseCreatedAt | string | yes, activity データタイプ WebVisit、PageView の場合 | ActivityDate |
| update_end_time | 終了時間がジョブの実行時間より大きい場合、クエリの終了時間を更新します。増分ジョブのみサポートされます。 | bool | no | false |
| mode | ターゲットテーブルのレコードを append または replace します。replace モードでは、ターゲットテーブルに手動で加えられたスキーマ変更はそのまま保持されます。 | string | yes | Append |


### contact フィールド名のリストの取得

Eloqua コンソールでフィールドのリストを読み取ったり取得したりすることができないため、これらは API 経由でのみサポートされています。そのため、インポートジョブでは、import_fields 設定の選択と再利用をサポートするために、すべての contact フィールド名をログ出力しています。

例:

Eloqua インポートジョブコンソールには次のように表示されます


```
2024-06-14 11:29:21.271 +0000 [INFO] (0001:transaction): All contact fields: C_EmailAddress,C_FirstName,C_LastName,C_Company............
```

contact オブジェクトが 250 個以上のフィールドを持ち、Import Fields が空の場合は、次のログが表示されます。


```
Import contact fields: C_EmailAddress,C_FirstName,C_LastName,C_Company...........Skipped contact fields: C_Country1,C_Province1,C_City1
```

インポートフィールドを指定する場合は、すべての contact フィールドログからフィールド名をコピーして、Import Fields に入力できます。

### データのプレビュー (オプション)

データをプレビューするには、*td connector:preview* コマンドを使用します。


```
$ td connector:preview load.yml
+-------------------+00--------------------+--------------------------+----
| activity_id:long  | activity_type:string | activity_date:timestamp  | ...
+---------------------+--------------------+--------------------------+----
| 12345678          | "__"                 | "2018-04-17 13:39:06 UTC"| ...
+-------------------+----------------------+--------------------------+----
```

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

ロードジョブを送信します。データサイズによっては、数時間かかる場合があります。


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

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

Treasure Dataのストレージは時間でパーティション分割されているため、`-time-column`オプションの使用を推奨します。（[データパーティショニング](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)を参照してください。）オプションが指定されていない場合、データコネクタは最初の`long`または`timestamp`カラムをパーティショニング時間として選択します。`-time-column`で指定するカラムのタイプは、`long`型または`timestamp`型である必要があります。

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

`td connector:issue`コマンドは、*データベース(td_sample_db)*と*テーブル(td_sample_table)*がすでに作成されていることを前提としています。データベースまたはテーブルがTDに存在しない場合、このコマンドは成功しません。`td connector:issue`コマンドで`-auto-create-table`オプションを使用して、データベースとテーブルを手動で作成できます：


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

### スケジュール実行

Eloqua Importコネクタの定期的なデータコネクタ実行をスケジュールすることができます。この機能を使用することで、`cron`デーモンを使用する必要がなくなります。ただし、高可用性を確保するために、スケジューラを慎重に設定することを推奨します。

`td connector:create`コマンドを使用して新しいスケジュールを作成できます。以下を指定する必要があります：

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



```
$ td connector:create     daily_eloqua_import     "9 0 * * *"     td_sample_db     td_sample_table     load.yml
```

`cron`パラメータは、`@hourly`、`@daily`、`@monthly`の3つのオプションも受け入れます。

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

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

`td connector:list`コマンドを使用して、スケジュールされたエントリのリストを表示できます。


```
$ td connector:list
+-------------------------+-------------+----------+-------+--------------+-----------------+------------------------------+
| Name                    | Cron        | Timezone | Delay | Database     | Table           | Config                       |
+-------------------------+-------------+----------+-------+--------------+-----------------+------------------------------+
| daily_eloqua_import | 9 0 * * *   | UTC      | 0     | td_sample_db | td_sample_table | {"type"=>"eloqua", ... } |
+-------------------------+-------------+----------+-------+--------------+-----------------+------------------------------+
```

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

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


```
% td connector:show daily_eloqua_import
Name     : daily_eloqua_import
Cron     : 9 0 * * *
Timezone : UTC
Delay    : 0
Database : td_sample_db
Table    : td_sample_table
```

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


```
% td connector:history daily_eloqua_import
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| JobID  | Status  | Records | Database     | Table           | Priority | Started                   | Duration |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| 678066 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-28 00:09:05 +0000 | 160      |
| 677968 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-27 00:09:07 +0000 | 161      |
| 677914 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-26 00:09:03 +0000 | 152      |
| 677872 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-25 00:09:04 +0000 | 163      |
| 677810 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-24 00:09:04 +0000 | 164      |
| 677766 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-23 00:09:04 +0000 | 155      |
| 677710 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-22 00:09:05 +0000 | 156      |
| 677610 | success | 10000   | td_sample_db | td_sample_table | 0        | 2017-07-21 00:09:04 +0000 | 157      |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
8 rows in set
```

### スケジュールの削除

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


```
$ td connector:delete daily_eloqua_import
```