# Salesforce Export Integration CLI

[Salesforce](http://Salesforce.com) 組織にジョブ結果をエクスポートできます。

これに関するサンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td/sfdc) を参照してください。

## 前提条件

- [TD Toolbelt](https://toolbelt.treasuredata.com/) を含む Treasure Data の基本知識
- [Salesforce.com](http://Salesforce.com) 組織、および API 統合用のユーザー名、パスワード、セキュリティトークン
- ユーザーに「API 有効化」権限があること
- 対象となる [Salesforce.com](http://Salesforce.com) オブジェクトがユーザーの読み取り/書き込み権限で存在すること


## サポート

SFDC 出力は以下の認証タイプをサポートします:

- Credential
- Session


### 例1: ランキング: 「X の上位 N」とは？

すべてのソーシャル/モバイルアプリケーションは「X の上位 N」（例: 今日視聴された上位5本の映画）を計算します。Treasure Data はすでに生データのウェアハウジングを処理していますが、「Salesforce.com への書き込み」機能により、Treasure Data で「上位 N」のデータを見つけることもできます。

### 例2: ダッシュボードアプリケーション

データサイエンティストの場合、毎時/毎日/毎月の範囲のメトリクスを追跡し、可視化を通じてアクセス可能にする必要があります。この「[Salesforce.com への書き込み](http://write-to-Salesforce.com)」機能を使用すると、プロセスを効率化し、Salesforce.com 組織のレポートとダッシュボードを通じてクエリ結果の可視化の構築に集中できます。

## Result Output URL フォーマット

### フォーマット

Result Output ターゲットは、以下のフォーマットの URL で表されます:


```url
sfdc://username:passwordsecurity_token@hostname/object_name
```

各パラメータの説明:

| **sfdc** | Salesforce.com への Result Output の識別子 |
|  --- | --- |
| **username** と **password** | Salesforce.com 組織への認証情報 |
| **security_token** | API アクセスのための追加認証情報 |
| **hostname** | Salesforce.com 組織のホスト名。通常、本番環境の場合は 'login.salesforce.com'、サンドボックス環境の場合は 'test.salesforce.com' です。組織にカスタムドメインを設定している場合は、ログインに使用しているホスト名を指定します。 |
| **object_name** | 対象となる Salesforce.com オブジェクトの API 名（例: ResultOutput__c）。データ統合用のオブジェクトと列は事前に定義されている必要があります。 |


例えば、以下の情報の場合:

- **username**: user@treasure-data.com
- **password**: PASSWORD
- **security_token**: 7SMvicR9ojdPz0XLtlWi3Rtw


URL は以下のようになります:


```url
sfdc://user@treasure-data.com:PASSWORD7SMvicR9ojdPz0XLtlWi3Rtw@login.salesforce.com/Account
```

ユーザー名内の '@' を '@' でエスケープするようにしてください。

## オプション

Salesforce.com への Result Output は、オプションの URL パラメータとして指定できる様々なオプションをサポートします。オプションは相互に互換性があり、組み合わせることができます。
該当する場合は、デフォルトの動作が示されています。

### Update の Mode オプション

データベースデータを変更する様々な方法を制御します。

- Append
- Truncate
- Update


mode=append (デフォルト)

append モードは、URL に mode オプションが指定されていない場合に使用されるデフォルトです。このモードでは、クエリ結果がオブジェクトに追加されます。

mode=append はデフォルトの動作であるため、以下の2つの URL は同等です:


```
sfdc://.../Contact
sfdc://.../Contact?mode=append
```

mode=truncate

**truncate** モードでは、システムは最初に Salesforce.com オブジェクト内の既存のレコードを切り捨ててごみ箱に移動し、その後クエリ結果を挿入します。

例:


```
sfdc://.../CustomObject__c?mode=truncate
```

`mode=truncate` に対して `hard_delete=true` オプションを指定すると、レコードをごみ箱に移動する代わりに削除できます。このオプションを使用するには、ユーザーが「Bulk API Hard Delete」権限を持っている必要があります。


```
sfdc://.../CustomObject__c?mode=truncate&hard_delete=true
```

mode=update

**update** モードでは、"unique" パラメータで指定された外部キー列に重複値が発生しない限り、行が挿入されます。重複が発生する場合は、代わりに更新が実行されます。"unique" パラメータはこのモードで必須であり、update モードで使用する場合は外部キーとして定義する必要があります。

例:


```
sfdc://.../Contact?mode=update&unique=CustomerId__c
```

'update' モードのデフォルトの動作は実際には '[upsert](https://www.salesforce.com/developer/docs/api/Content/sforce_api_calls_upsert.htm)' です。"upsert" ではなく "update" のみを実行したい場合は、`upsert=false` オプションを追加できます。これにより、"unique" パラメータの一致に基づいて既存のレコードを更新し、新しいレコードは挿入しません。


```
sfdc://.../Contact?mode=update&unique=CustomerId__c&upsert=false
```

### Upload の Concurrency_Mode オプション

concurrency_mode オプションは、Salesforce.com 組織へのデータのアップロード方法を制御します。デフォルトのモードは parallel で、ほとんどの状況に推奨される方法です。

concurrency_mode=parallel (デフォルト)

parallel メソッドでは、データが並列でアップロードされます。これは最も信頼性が高く効果的な方法であり、ほとんどの状況に推奨されます。

`concurrency_mode=parallel` はデフォルトの動作であるため、以下の2つの URL は同等です:


```
sfdc://.../CustomObject__c
sfdc://.../CustomObject__c?concurrency_mode=parallel
```

- `concurrency_mode=serial`


レコードを並列でアップロードすることが推奨されます。ただし、エラーメッセージに "UNABLE_TO_LOCK_ROW" が表示される場合は、代わりに `concurrency_mode=serial` を試してください。


```
sfdc://.../CustomObject__c?concurrency_mode=serial
```

Salesforce.com オブジェクトを更新すると、オブジェクトと列によって参照される親オブジェクトのロックが取得されます。オブジェクトを並列でアップロードし、複数のオブジェクトが同じ親オブジェクトへの参照を持つ場合、Salesforce.com は挿入/更新のロックを取得できず、'UNABLE_TO_LOCK_ROW' エラーを返します。このような場合は、`concurrency_mode=serial` オプションを指定してください。

### 認証 Session_Id オプション

Salesforce.com セッション ID がある場合、ユーザー名、パスワード、セキュリティトークンの代わりに `session_id` オプションで認証できます（つまり、ユーザー名、パスワード、セキュリティトークンは URL から省略できます）。


```
sfdc://login.salesforce.com/Contact?session_id=3deT2aQjYQbIRN0M...jB1tHBb7UW0K!M
```

### Retry オプション

このオプションは、エラーが発生した場合に、Treasure Data エクスポートワーカーが設定された Salesforce.com 宛先に結果を書き込もうとする試行回数を設定します。設定された再試行回数よりもエクスポートが失敗した場合、クエリは失敗します。
デフォルトの再試行回数は `retry=2` ですが、実質的に任意の数に設定できます。再試行回数はクエリの全体的な期間に影響します。


```
sfdc://.../CustomObject__c?retry=5
```

### Split Records オプション

Treasure Data の Result Export は、クエリ結果のレコードをデフォルトで10000レコードのチャンクに分割し、一度に1つのチャンクを一括アップロードします。`split_records` オプションは、必要に応じてこのチャンクのサイズを設定します。


```
sfdc://.../CustomObject__c?split_records=100
```

## 使用方法

### CLI

単一のクエリの結果を [Salesforce.com](http://Salesforce.com) 組織に出力するには、`td query` コマンドに `-r / —result` オプションを追加します。ジョブが完了すると、結果が [Salesforce.com](http://Salesforce.com) 組織オブジェクトに書き込まれます:


```bash
td query -w -d testdb \
--result 'sfdc://login.salesforce.com/CustomObject__c?session_id=.....' \
"SELECT code as Code__c, COUNT(1) as Count__c FROM www_access GROUP BY code"
```

出力が体系的に [Salesforce.com](http://Salesforce.com) 組織に書き込まれるスケジュールされたクエリを作成するには、`td sched:create` コマンドでスケジュールを作成する際に `-r / —result` オプションを追加します:


```bash
td sched:create hourly_count_example "0 * * * *" -d testdb \
--result 'sfdc://user@treasure-data.com:PASSWORDsecuritytoken@login.salesforce.com/CustomObject__c' \
"SELECT COUNT(*) as Count__c FROM www_access"
```

## トラブルシューティング

SFDC への Result Output ジョブによって以下のタイプのエラーが発生した場合、SFDC 上でジョブのエラーを確認できます。以下の例に示すように、SFDC で "XXXXXXXXXXX" を確認してください。エラーの詳細を把握できます。


```
17/05/01 03:35:05 INFO sfdc.BulkAPIJob: Job XXXXXXXXXXX finished: Total 1, Completed 0, Failed 1 17/05/01 03:35:05 INFO sfdc.BulkAPIClient: Batch jobs failed (1/1)
```