マルチデータ書き込み処理

オペレーション名

マルチデータ書き込み

機能概要

[マルチデータファイル生成]処理にて出力されたファイルを読み込み、Salesforceへデータ更新 create()・update()・delete() を行います。

入力データに対するレコードごとの結果や ID は出力スキーマから受け取ることができます。

本オペレーションが使用するAPI仕様については、グローバルリソースで選択したバージョンのAPIドキュメントを以下のリンク先ページより参照してください。

「Salesforce Developer Documentation」-(https://developer.salesforce.com/docs)
- SOAP API Developer's Guide

データモデル

本コンポーネントのデータモデルはテーブルモデル型です。

プロパティ

変数の使用については、「変数」を参照してください。

基本設定

項目名	必須/省略可	変数の使用	説明	備考
名前	必須	使用不可	スクリプトキャンバス上での名前を入力します。

必須設定

項目名	必須/省略可	変数の使用	説明	備考
接続先	必須	使用不可	グローバルリソースを選択します。グローバルリソースの設定方法については、「グローバルリソースのプロパティ」を参照してください。 [追加]: 新規にグローバルリソースを追加します。 [一覧の編集]: 「リソース一覧の編集」画面にて、グローバルリソースの設定を編集することができます。	API 23.0以降のグローバルリソースが選択可能です。
入力ファイル	必須	使用可	[マルチデータファイル生成]処理にて出力されたCSV形式のファイルパスを入力します。 [参照]ボタンを押下するとファイルチューザが起動し、ファイルの選択ができます。	ファイルパスはDataSpider Cloudファイルシステムの絶対パスで指定してください。パス区切り文字「/」以外のDataSpider Cloudファイルシステムの使用禁止文字は使用できません。
オペレーション種類	必須	使用不可	ジョブのオペレーション種類を選択します。 [INSERT]:(デフォルト) createサービスを用いてデータを追加します。 [UPDATE]: updateサービスを用いてデータを更新します。 [DELETE]: deleteサービスを用いてデータを削除します。	API仕様によりUPSERTには対応していません。
更新時Null設定	必須	使用不可	更新対象フィールドに対する入力データがnullであった場合、nullで上書きするか、該当項目の更新をスキップするかを選択します。 [読み込みデータで常に上書き]:(デフォルト) 入力データがnullの場合、更新対象フィールドをnullで上書きします。 [読み込みデータをスキップ]: 入力データがnullの場合、更新対象フィールドの更新をスキップし、更新前の状態を維持します。入力データがnull以外の場合、更新対象フィールドは入力データで上書きします。	[オペレーション種類]に[UPDATE]を選択した場合、有効になります。
入力データ数上限	必須	使用可	入力ファイルに含まれるデータ行の件数上限値を指定します。上限値を超える場合、エラーが発生します。	デフォルト値は「200」です。「1」以上「200」以下の値が指定できます。範囲以外の値が指定された場合、エラーが発生します。

プロパティアクション

項目名	説明	備考
プレビュー	プレビューアを起動して、[入力ファイル]で指定したファイルの内容を表示します。	指定したファイルが存在しない場合、または[ファイル]に変数が設定されている場合は無効になります。 [エンコード]で指定したエンコードで表示されます。ファイル内容の編集はできません。プレビューアで表示できるファイルのサイズは最大1MBです。ファイルサイズが1MBを超える場合、ファイルの先頭から1MB分が表示されます。

オプション設定

項目名	必須/省略可	変数の使用	説明	備考
エンコード	必須	使用可	読み込むファイルのエンコードを選択または入力します。入力する場合は、Java SE Runtime Environment 8でサポートされているエンコードを指定します。詳細については、「Supported Encodings」(http://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html)を参照してください。	デフォルト値については、「デフォルトで選択されるエンコード」を参照してください。
Base64項目入力形式	必須	使用不可	データ型が「base64」である項目への入力形式を選択します。 [Base64データ]:(デフォルト) Base64データ形式として受け取ります。 [ファイルパス]: ファイルパス形式として受け取ります。指定されたファイルを読み取りBase64データに変換します。	[ファイルパス]を選択した場合、DataSpider Cloudファイルシステムの絶対パスで入力してください。 [ファイルパス]を選択した場合、パス区切り文字「/」以外のDataSpider Cloudファイルシステムの使用禁止文字は使用できません。
出力スキーマに追加する入力データ項目数	必須	使用不可	出力スキーマに追加する入力データ項目数を選択します。 [0]:(デフォルト) 入力データのスキーマは表示されません。 [1～30]: 選択した数分のスキーマが追加されます。	1以上を選択した場合、出力スキーマには[input_value_column_index(n)]というスキーマが選択した数分表示されます。入力データ行の先頭の項目の値から順にセットされ、項目数が選択した数以下の場合、残りのスキーマにはnullがセットされます。追加されるスキーマについては、「スキーマ」を参照してください。

データ処理方式

項目名	必須/省略可	変数の使用	説明	備考
データ処理方式	必須	使用不可	データ処理方式を選択します。 [スクリプトの設定を使用する]:(デフォルト) スクリプトプロパティの大容量データ処理の設定をアダプタに使用します。 [大容量データ処理を行わない]: 大容量データ処理を行いません。 [大容量データ処理を行う]: 大容量データ処理を行います。

項目名	必須/省略可	変数の使用	説明	備考
コメント	省略可	使用不可	このアダプタの簡単な説明を記述することができます。説明を記述すると、仕様書に反映させることができます。

スキーマ

出力スキーマ

更新結果の情報に、[出力スキーマに追加する入力データ項目数]で選択した数分のスキーマが付与されます。

<?xml version="1.0" encoding="UTF-8" ?>
<table>
  <row>
    <column>result_id</column>
    <column>result_is_success</column>
    <column>result_error_status_code</column>
    <column>result_error_message</column>
    <column>result_row_number</column>
    <column>target_object</column>
    <column>input_value_column_index1</column>
    ：
    <column>input_value_column_index30</column>
  </row>
  <row>
    :
  </row>
</table>

要素名	列名(ラベル/API)	説明
row	-	入力ファイルに存在したデータ行数分繰り返します。
column	result_id	SalesforceのIDを出力します。
	result_is_success	成功フラグを出力します。 [true]:処理に成功しました。 [false]:処理に失敗しました。[result_error_status_code]および[result_error_message]を確認してください。
	result_error_status_code	SalesforceのAPIが返すステータスコードを出力します。
	result_error_message	SalesforceのAPIが返すメッセージを出力します。
	result_row_number	入力スキーマに渡されたデータ内のノードの位置に基づいて番号を出力します。
	target_object	このレコードの更新対象オブジェクトAPI名を出力します。
	input_value_column_index(n)	入力データ行の先頭の項目の値から順にセットされ、項目数が選択した数以下の場合、残りのスキーマにはnullがセットされます。 [出力スキーマに追加する入力データ項目数]で選択した数分のスキーマが追加されます。

Mapperでのスキーマ読み込み

スキーマは自動で読み込まれます。

詳細については、「スキーマ編集」を参照してください。

大容量データ処理

大容量データ処理に対応しています。

トランザクション

トランザクションはサポートしていません。

PSPでの使用について

PSPでは使用できません。

使用できるコンポーネント変数

コンポーネント変数名	説明	備考
record_count	読み込んだデータ行の件数が格納されます。	デフォルト値はnullです。
success_count	更新処理に成功した件数が格納されます。	デフォルト値はnullです。
error_count	更新処理に失敗した件数が格納されます。	デフォルト値はnullです。
server_url	ログイン後のエンドポイントURLが格納されます。	デフォルト値はnullです。
session_id	セッションIDが格納されます。	デフォルト値はnullです。
message_category	エラー発生時、発生したエラーに対応するメッセージコードのカテゴリが格納されます。	デフォルト値はnullです。
message_code	エラー発生時、発生したエラーに対応するメッセージコードのコードが格納されます。	デフォルト値はnullです。
message_level	エラー発生時、発生したエラーに対応するメッセージコードの重要度が格納されます。	デフォルト値はnullです。
operation_api_exception_code	APIエラー発生時、発生したエラーのExceptionCodeが格納されます。	デフォルト値はnullです。 APIエラー以外のエラー発生時は、値が格納されません。 DataSpider Cloudのバージョンにより、格納される内容が変わる可能性があります。
operation_error_message	エラー発生時、発生したエラーのメッセージが格納されます。	デフォルト値はnullです。 DataSpider Cloudのバージョンにより、格納される内容が変わる可能性があります。
operation_error_trace	エラー発生時、発生したエラーのトレース情報が格納されます。	デフォルト値はnullです。 DataSpider Cloudのバージョンにより、格納される内容が変わる可能性があります。

マルチデータ書き込み使用例

マルチデータ書き込みを行うには、[マルチデータファイル生成]処理と[マルチデータ書き込み]処理を使用します。
[マルチデータファイル生成]処理でローカルファイルに複数のオブジェクトのデータを出力し、[マルチデータ書き込み]処理でファイルの内容を読み込みSalesforceへ更新を行います。

例:「取引先(Account)」「取引先責任者(Contact)」のレコードを1回のINSERTコールでまとめて書き込みします。

例の詳細

種類	説明	備考
要件仕様	1件の「取引先(Account)」のデータと紐付く複数件の「取引先責任者(Contact)」のデータを書き込みます。書き込みに失敗するデータが1件でも存在した場合、すべて失敗として扱いたい。	入力データは200件以下であることとします。
設定方法	[マルチデータファイル生成]処理で「取引先(Account)」データ、「取引先責任者(Contact)」データの順でファイル出力します。出力されたファイルの内容をもとに[マルチデータ書き込み]処理でSalesforceへ更新を行います。グローバルリソースのプロパティ[AllOrNoneヘッダー(allOrNone)]を[チェックあり]とします。	本説明にて使用している項目や一部の設定は使用例となります。使用しているSalesforce組織に必ず存在するものではありません。各種設定を行った上で本機能を使用してください。

連携イメージ

画像内の番号	名称	説明	備考
(1)	入力データイメージ	取引先(Account)へ書き込みをするための入力データイメージです。
(2)	入力データイメージ	取引先責任者(Contact)へ書き込みをするための入力データイメージです。ここでは、[リレーションシップ項目定義]に「Account.AccountCode__c」を指定します。	詳細については、[マルチデータファイル生成]処理の「リレーションシップ項目定義」を参照してください。
(3)	マルチデータファイル生成の設定	(1)入力データ(2)入力データの順で、それぞれ[マルチデータファイル生成]処理にてデータをファイルへ書き込みます。 [出力ファイル]には、ともに「/data/Sample.csv」を指定します。	詳細については、「レコードの順序とチャンク」を参照してください。
(4)	スクリプトイメージ	本説明のスクリプト実装イメージです。
(5)	マルチデータ書き込みの設定	[マルチデータ書き込み]処理にて、データが集積されたファイルをもとにSalesforceへ更新を行います。 [入力ファイル]には、「/data/sample.csv」を指定します。 [出力スキーマに追加する入力データ項目数]には、「3」を指定します。
(6)	結果データ書き込みマッピングイメージ	書き込みした際の結果データをCSVファイルに出力するマッピングイメージです。 (5)にて[出力スキーマに追加する入力データ項目数]に「3」を指定しているため、結果データと共に、入力データ項目の値を先頭から3項目まで扱うことができます。
(7)	結果データイメージ(allOrNoneあり)	グローバルリソースのプロパティ[AllOrNoneヘッダー(allOrNone)]を[チェックあり]の設定で書き込みした際の結果データイメージです。 1回のINSERTコールに含まれるデータの内、1件以上データエラーが発生した場合、同一コール内の全てのレコードがロールバックされます。
(8)	結果データイメージ(allOrNoneなし)	グローバルリソースのプロパティ[AllOrNoneヘッダー(allOrNone)]を[チェックなし]の設定で書き込みした際の結果データイメージです。 1回のINSERTコールに含まれるデータの内、1件以上データエラーが発生してもロールバックされずに成功したレコードは更新が有効となります。

集積したレコードを更新する際には、Salesforceで1つのオブジェクトタイプごとに分割されます。この分割された単位をチャンクと呼びます。
1回の更新処理の呼び出しで、最大10のチャンクを含むことができます。
チャンクが分割されるルールは、[マルチデータファイル生成]処理で出力したレコードの順序に依存します。
また、データはチャンクごとにコミットされます。そのため、リレーション関係を持つレコードを含む場合、親レコードは子レコードより前にする必要があります。
この場合、子レコードは親の外部ID項目(リレーションシップ項目定義)を使用して親レコードとの関係を指定します。

例:次のオブジェクトタイプの順序でデータ集積した場合

取引先1, 取引先2, 取引先責任者1, 取引先責任者2, 取引先責任者3, ケース1, 取引先3, 取引先4, 取引先責任者4

分割されるチャンクは以下となります。
- チャンク1: 取引先1, 取引先2
- チャンク2: 取引先責任者1, 取引先責任者2, 取引先責任者3
- チャンク3: ケース1
- チャンク4: 取引先3, 取引先4
- チャンク5: 取引先責任者4

マルチデータファイルフォーマット

[マルチデータファイル生成]処理では、[マルチデータ書き込み]処理で使用するために定義されたフォーマットでファイルが生成されます。
フォーマットが正しければ、独自に作成したファイルでも[マルチデータ書き込み]処理で扱うことが可能です。

マルチデータ書き込み用のファイルフォーマットは以下です。

ファイル名	拡張子	エンコード	改行コード
任意	CSV	任意	Auto

ファイルの内容は以下の種類の行から構成され、操作するオブジェクト毎に繰り返します。
各行の先頭のカラムには、識別文字を指定します。

行名称	識別文字	説明	カラム数	行位置
テーブル行	*	オブジェクトのAPI名をひとつ指定します。	1カラム（識別文字カラムを除く）	ファイルの先頭行、またはデータ行の次に出力します。
スキーマ行	**	書き込みを行うスキーマのAPI名をカンマ区切りで指定します。外部IDによる参照項目の更新を行う場合、以下のフォーマットで指定します。 "参照項目API名:リレーションシップ名:親オブジェクトAPI名:外部ID項目API名"	書き込み対象スキーマ分のカラム（識別文字カラムを除く）	テーブル行の次に出力します。
データ行	(空白)	書き込むレコードのデータをカンマ区切りで指定します。出力するカラム順は[スキーマ行]で指定した項目の順序と一致させます。	書き込み対象スキーマ分のカラム（識別文字カラムを除く）	スキーマ行の次に出力します。複数のレコードを表現する場合は、続けてデータ行を出力します。

仕様制限

本アダプタによるデータ読み取り・書き込みの操作を行うには、Salesforceの組織がAPIを公開している必要があります。

各テーブルに対するデータ読み取り・書き込みなどの操作権限、およびデータのアクセスコントロールは、すべてSalesforce側のプロファイル、共有ルールの設定、およびAPI仕様に依存します。

API バージョンによって扱うことができるオブジェクトや項目は異なります。詳細はSalesforceのドキュメントをご確認ください。

主な例外

例外名	原因	対策
ResourceNotFoundException リソース定義が見つかりませんでした。名前:[]	[接続先]が指定されていません。	[接続先]を指定してください。
ResourceNotFoundException リソース定義が見つかりませんでした。名前:[<グローバルリソース名>]	[接続先]で選択されたリソース定義が見つかりません。	[接続先]で指定したグローバルリソースを確認してください。
java.net.UnknownHostException	グローバルリソースで指定したPROXYサーバが見つからない例外です。	PROXYサーバの状態を確認して下さい。または、[接続先]で指定したグローバルリソースの[Proxyホスト]を確認してください。
API23.0以前 org.apache.commons.httpclient.HttpConnection$ConnectionTimeoutException API26.0以降 java.net.SocketTimeoutException connect timed out	Salesforceに接続中にタイムアウトが発生しました。	ネットワークの状態、Salesforceのサーバの状態を確認してください。または、[接続先]で指定したグローバルリソースの[Connectionタイムアウト(秒)]を確認してください。
API23.0以前 org.apache.commons.httpclient.HttpRecoverableException java.net.SocketTimeoutException: Read timed out API26.0以降 java.net.SocketTimeoutException Read timed out	Salesforceに接続後、サーバからの応答までにタイムアウトが発生しました。	ネットワークの状態、Salesforceのサーバの状態を確認してください。または、[接続先]で指定したグローバルリソースの[タイムアウト(秒)]を確認してください。
jp.co.headsol.salesforce.adapter.exception.SalesforceAdapterIllegalArgumentException	Salesforceアダプタのプロパティの設定値が不正です。	エラーメッセージを確認し、設定内容をご確認ください。
com.sforce.soap.partner.fault.LoginFault	Salesforceへのログインに失敗しました。	ExceptionCodeまたは、エラーメッセージを確認し、Salesforceの関連ドキュメントなどに対象のエラーに関する情報がないか確認してください。
com.sforce.soap.partner.fault.UnexpectedErrorFault	Salesforceへの処理実行中に、予期しない例外が発生しました。	ExceptionCodeまたは、エラーメッセージを確認し、Salesforceの関連ドキュメントなどに対象のエラーに関する情報がないか確認してください。

注意事項

本オペレーションでは、データベースアダプタなどとは異なり、エラー発生時にロールバックすることができません。そのため、正常データは更新し、エラーデータは更新せずその情報をWARNレベルのログとして出力します。
よって、データ単位でのエラー(制約違反や設定値不正など)が存在する場合、スクリプト内で例外監視処理によるエラーの検出を行なうことはできません。
データ単位でのエラー情報を処理の中でデータとして使用したい場合、後続の処理で結果データをエラーの検出などのハンドリングに使用してください。

リレーションシップ項目定義で指定したリレーション用カラムが数値型である場合、 java の double 型の精度を超える数値を受け渡すと、丸められた値で親レコードの索引が行われます。
値を丸めずに索引を行う場合、テキスト型を指定してください。

次の API バージョンにおいて java の double 型の精度を超える数値を書き込んだ場合、値が丸められて登録されます。
一例として、数値(16,2) の項目に「1,234,567,890,123,456.78」を書き込んだ場合、「1,234,567,890,123,456.80」として登録されます。
- API 7.0
- API 14.0
- API 18.0
- API 23.0
値を丸めずに書き込む場合、上記より新しい API バージョンを使用してください。

オブジェクトの項目にはデータ型が定義されています。APIでは定義されたデータ型の形式ルールに従いデータを送受信しますが、本アダプタでは一部のデータ型においてルールを拡張しています。
詳細については、「データ型の形式」を参照してください。