# Zuora Import Integration

Zuoraのデータソースオブジェクト(アカウントや請求書など)をTreasure Dataにインポートできます。インポートのモードは以下の通りです:

- base
- fetch-related


fetch-relatedインポートでは、事前に結合されたすべてのオブジェクトを含むFullオブジェクトのインポートを指定できます。

## 前提条件

- Treasure Dataの基本知識
- Zuoraの基本知識


## 制限事項

- Zuora Import IntegrationはZuora SOAP APIを内部的に使用しています。このAPIはZuora USデータセンターのお客様が利用可能です。
- Zuora EUデータセンターのお客様でこの統合機能を利用したい場合は、カスタマーサクセス担当者にお問い合わせください。


## TD Consoleを使用する

### 新しい接続を作成する

1. **Integrations Hub > Catalog**に移動し、Zuoraを検索します。
2. Zuoraを選択します。
![](/assets/image-20191022-134041.97acb8ec20146253a30e1d386dc86d613016642bf6751553e2f7176f20e4bd51.b7743126.png)
3. Zuoraのログイン情報を入力し、**Next**を選択して接続名を指定します:
![](/assets/image-20191022-134049.232cabf5285a99606bc9c375568b921235c99ef6e81efd5f3bf0f0df83614a32.b7743126.png)


### 新しい転送を作成する

接続を作成すると、自動的にAuthentications(認証)ページに移動します。作成した接続を探して**New Transfer**を選択します。

![](/assets/image-20191209-222740.9cc97d1340b767b01f487643a5785b34bc309b1aead0a48834382b3653756922.b7743126.png)

情報の詳細を入力し、**Next**を選択します。

![](/assets/image-20191022-134100.e555ee1bfa1b13050efd82aa73399ae5c1fd992f00464a2141302b6ded23ffb8.b7743126.png)

**Fetch related objects**: Zuoraのほとんどのデータソースは関連するビジネスオブジェクトを提供しており、ネストされたクエリを構築する必要がなくなり、パフォーマンスが向上します。関連するビジネスオブジェクトデータが必要な場合は、チェックボックスにチェックを入れてクエリしたいデータソースを選択します。

**API Version (default v85)**: Zuora SOAP APIバージョン。v85以降をサポートしています。

**Duration to import**: このオプションでは、インポートの'start_date'に基づいて'end_date'を選択できます。

- **Start date**が02/07/2017, 12:00 AMに設定され、**Number of Unit**が1 DAYの場合、データ転送には02/08/2017, 12:00 AMまでのすべてのデータが含まれます。


この例では、'end_date'は次のように計算されます:


```
'start_date' + 'number_of_unit' = 'end_date'
02/07/2017, 12:00AM + 1 DAY = 02/08/2017, 12:00AM
```

- 転送がスケジュールされている場合、'start_date'は前回のインポート以降の新しい'end_date'に基づいて常に変化します(前述のように計算されます)。
- incrementalが選択されていない場合、インポートは'start_date'から現在までとなります。
- ユーザーのタイムゾーンが保持されます。


'start_date'を変更したい場合は、転送を再作成することを強くお勧めします。既存の転送を編集しても'start_date'には影響しません。

データをプレビューします。何か変更したい場合は**Advanced Settings**を選択し、そうでなければ**Next**を選択します。

![](/assets/image-20191022-134115.782327cf5066ade2eb255a890e644c71418a397ae8f4507e0d022d0187fcfdb2.b7743126.png)

データを転送するデータベースとテーブルを選択します:

![](/assets/image-20191022-134127.570a6c23e21e341b7de52b942e6622f51aa9747cc2f2da5db1606cf078e054b1.b7743126.png)

データ転送のスケジュールを指定し、Start Transferをクリックします:

![](/assets/image-20191022-134134.39cd15fd204aef50837fe8d503e9b127101d4c412fb2113dfae4aad0eb41a006.b7743126.png)

My Input Transfersタブの下に、進行中の新しいデータ転送が表示され、対応するジョブがJobsセクションに表示されます。

## Command Lineを使用する

### 'td' command v0.11.9以降をインストールする

最新の[TD Toolbelt](https://toolbelt.treasuredata.com/)をインストールできます。


```
$ td --version
0.15.0
```

### 設定ファイルを作成する

Zuoraアカウントのアクセス情報を使用して、次の例のように設定ファイル(例: `load.yml`)を準備します。


```yaml
in:
  type: zuora
  username: xxxxxxxx
  password: xxxxxxxx
  base_object: Account #(required if fetch_related = false, see Appendix B)
  data_source: Account #(required if fetch_related = true, see Appendix C)
  fetch_related: true #(optional, default: false)
  from_timestamp: 12-05-2016T11:00:00.000Z
  incremental: true #(optional, default: true)
  duration: { unit: DAY, num: 1 } #(required if `incremental: true`)
out:
  mode: replace
```

この例では、Zuora Accountデータソースをダンプしています:

- username と password: ログイン情報
- describe_api_verion: Zuora Describe APIバージョン。[Zuora Describe API](https://knowledgecenter.zuora.com/DC_Developers/M_Export_ZOQL/Changes_to_the_Describe_API)を参照してください
- base_object: インポートしたいZuora SOAP(Base)オブジェクトの名前。fetch_related: falseの場合は必須です
  - 利用可能なbaseオブジェクトのリストについては、[Appendix](/ja/int/zuora-import-integration#h1__1835053169)を参照してください。
- data_source: インポートしたいZuoraデータソースの名前。fetch_related: trueの場合は必須です
  - 利用可能なデータソースのリストについては、[Appendix](/ja/int/zuora-import-integration#h1__1835053169)を参照してください。
- fetch_related: **base**または**full**オブジェクト(すべての事前結合されたオブジェクトを含む)のインポートを選択できます。デフォルトはfalseです
- from_timestamp: データがインポートされる開始時刻。フォーマットは: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
- incremental: データインポートを継続的に行うか1回のみ行うか。デフォルトはtrueです。trueの場合、durationが必須です
- duration: データがインポートされる期間。対象オブジェクトのUpdatedDateフィールドによって決定されます。unitには3つのオプションがあります: DAY、HOUR、MIN。デフォルトはDAYです。


ZuoraのいくつかのLimited Availabilityオブジェクトには、追加の設定が必要です。以下はBilling Preview Runの追加設定のリストです:

- from_timestamp : Billing Preview Runで使用する場合、これはプレビュー実行のTarget Dateです。
- include_evergreen_sub : エバーグリーンサブスクリプションを含めるかどうかを示します。デフォルトは'false'です
- batch : このプレビュー実行に含める顧客バッチを指定します
- assume_renewal : アカウントの更新を想定するかどうか。有効な値はAll、None、またはAutorenewです。デフォルトは'None'です。
- charge_type_to_exclude : 予測実行から除外する課金タイプ。可能な値: OneTime、Recurring、Usage、およびこれらの値のカンマ区切りの組み合わせ。


利用可能なoutモードの詳細については、[Appendix](/ja/int/zuora-import-integration#h1__1835053169)を参照してください。

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

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


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

### ロードジョブを実行する

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

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

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


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

connector:issueコマンドは、*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 updated_date --auto-create-table
```

「Partitioning Key」に時刻フォーマット列を割り当てるには、「--time-column」オプションを使用します。

### Scheduled execution

定期的なZuoraインポートのために、定期的なData Connector実行をスケジュールできます。Treasure Dataのスケジューラーの負荷分散と操作は、高可用性を実現するために最適化されています。Treasure Dataのスケジューラーを使用することで、ローカルデータセンターにcronデーモンを配置する必要がなくなります。

### Create the schedule

td connector:createコマンドを使用して新しいスケジュールを作成できます。スケジュールの名前、cron形式のスケジュール、データが保存されるデータベースとテーブル、Data Connector設定ファイルを指定します。これらの値は必須です。


```bash
td connector:create \
daily_zuora_import \
"10 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などのタイムゾーン略語は*サポートされておらず*、予期しないスケジュールにつながる可能性があります。

### List the Schedules

`td connector:list`でスケジュールエントリのリストを確認できます。


```
$ td connector:list
```

### Show the Setting and History of Schedules

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


```
td connector:show daily_zuora_import
```

### Delete the Schedule

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


```
$ td connector:delete daily_zuora_import
```

## Available Base Object

| **Base Object** | **Base Object** | **Base Object** |
|  --- | --- | --- |
| Account | InvoiceItem. | ProductRatePlanChargeTier |
| AccountingCode | InvoiceItemAdjustment | RatePlan |
| AccountingPeriod | InvoicePayment | RatePlanCharge |
| BillingRun | Payment | RatePlanChargeTier |
| BillingPreviewRun | PaymentMethod | Refund |
| ChargeMetrics | PaymentMethodTransactionLog | RefundInvoicePayment |
| Contact | PaymentTransactionLog | RefundTransactionLog |
| CreditBalanceAdjustment | Product | Subscription |
| Feature | ProductFeature | SubscriptionProductFeature |
| Invoice | ProductRatePlan | TaxationItem |
| InvoiceAdjustment | ProductRatePlanCharge | Usage |


## Available Data Source

| **Data Source** | **Data Source** | **Data Source** |
|  --- | --- | --- |
| Account | Payment | RatePlanChargeTier |
| AccountingCode | PaymentGatewayReconciliationEventLog | RevenueChargeSummaryItem |
| BillingRun | PaymentMethod | RevenueEventItem |
| Contact | PaymentMethodTransactionLog | RevenueEventItemCreditMemoItem |
| ChargeMetrics | PaymentPart | RevenueEventItemDebitMemoItem |
| CreditBalanceAdjustment | PaymentPartItem | RevenueEventItemInvoiceItem |
| Invoice | PaymentReconciliationLog | RevenueEventItemInvoiceItemAdjustment |
| InvoiceAdjustment | PaymentTransactionLog | RevenueScheduleItem |
| InvoiceItemAdjustment | ProcessedUsage | RevenueScheduleItemInvoiceItem |
| InvoicePayment | Product | RevenueScheduleItemInvoiceItemAdjustment |
| JournalEntryItem | ProductRatePlanChargeTier | RevenueScheduleItemCreditMemoItem |
| Order | RatePlan | RevenueScheduleItemDebitMemoItem |
| OrderAction | RatePlanCharge | Subscription |
| OrderQuantity | RatePlanChargeTier | SubscriptionProductFeature |
| OrderMrr | Refund | UpdaterDetail (PaymentMethodUpdate) |
| OrderTcb | RefundInvoicePayment | Usage |
| OrderTcv | RefundTransactionLog |  |


## Configure excluded fields for Base Object

Base Objectのデータをインポートする場合、一部の特殊なフィールドはデフォルトで除外されます。これは、Zuoraによって各Base Objectに適用される制限または制約によるものです。

例：RatePlanCharge DiscountAmountは、次のフィールドと一緒にクエリできません：Price、IncludedUnits、DiscountPercentage、OveragePrice。プラグインはデフォルトでこれらのフィールドを除外します。Advanced Configuration UIで除外フィールドのリストを変更できます。Advanced ConfigurationはBase Objectの除外フィールドのリストを自動的に入力します。

除外フィールドを変更する手順：

1. Base Objectプレビュー画面で、**Advanced Settings**を選択します。
2. **Advanced Settings**には、事前定義された除外フィールドのリストが含まれています（存在する場合）。フィールドを置き換えたり変更したりすることもできます。ただし、一部のフィールドは一緒に含めることができないことに注意してください。


![](/assets/image-20191022-134606.3570724ecc39b98a70aa6127bcdbc1adec43bd890f6fa0ac9dba6c813f61f1c0.b7743126.png)

![](/assets/image-20191022-134616.fb4954cffe0b4a7596f74a21eadb15fcf2c3cd1d365f1c58070932ffd79d99a6.b7743126.png)

除外フィールド設定はBase Objectターゲットでのみ機能し、Data Sourceターゲットでは無視されます

## Customize timestamp column

### Timestamp column

Timestamp列は、データコネクタが時間範囲フィルタを適用するために使用するZuoraオブジェクト列です。列はデフォルトでUpdatedDateまたはプラグイン内部設定で事前設定された列になります。

| Zuora Object | Incremental Column |
|  --- | --- |
| PaymentGatewayReconciliationEventLog | CreatedDate |
| PaymentMethodTransactionLog | TransactionDate |
| PaymentReconciliationLog | CreatedDate |
| PaymentTransactionLog | TransactionDate |
| RefundTransactionLog | TransactionDate |


前の表にリストされていない、サポートされているその他すべてのZuoraオブジェクトは、デフォルトの列*UpdatedDate*を使用します。

### Customize timestamp column

異なる列をtimestamp列として使用したい場合があります。**Advanced Configuration**画面のTimestamp列設定を通じて列を指定できます。

![](/assets/image-20191022-134643.6a0401ccf542a5ec558824040b0f8eb174bab2f2288355f4321bc387a245b242.b7743126.png)

パラメータ値は、Zuora ZOQLフィルタと同じ形式で、*ObjectName.ColumnName*の形式になります。例：RatePlanCharge.UpdatedAt、RatePlan.UpdatedAt、RatePlanChargeTier.UpdatedAt。

timestamp列として使用される列は、ZuoraでDateTime型データタイプを持つ必要があります。