データ書き込み(UPSERT)処理

オペレーション名

データ書き込み(UPSERT)

機能概要

SOAP API の upsert() を使用してデータを追加または更新します。

upsert() では、外部 ID (※)というインデックス付けされたカスタム項目を使用して、新しいレコードを作成するか、既存レコードを更新するかを判別します。
API ドキュメントでは、多くの場合、不要な重複レコードが作成されないようにするために、create() の代わりに upsert() を使用することが推奨されています。
(※事前にSalesforceのカスタマイズ機能を使用して定義します。)

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

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

データモデル

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

プロパティ

変数の使用については、「変数」を参照してください。
基本設定
項目名 必須/省略可 変数の使用 説明 備考
名前 必須 使用不可 スクリプトキャンバス上での名前を入力します。  
入力データ 必須 使用不可 スクリプトキャンバス上にあるコンポーネントを選択します。  
必須設定
項目名 必須/省略可 変数の使用 説明 備考
接続先 必須 使用不可 グローバルリソースを選択します。
グローバルリソースの設定方法については、「グローバルリソースのプロパティ」を参照してください。
  • [追加]:
    新規にグローバルリソースを追加します。
  • [一覧の編集]:
    「リソース一覧の編集」画面にて、グローバルリソースの設定を編集することができます。
  
テーブル名 必須 使用不可 Salesforceのテーブル名を選択します。  
スキーマ定義 必須 - Salesforceに対して書き込みを行う項目を設定します。
  • Salesforceに外部ID(またはID)が未設定の場合、または、外部ID(またはID)と異なる項目を外部キーと指定した場合、本オペレーション実行時にエラーが発生します。
  • Salesforceに対して書き込みが必要な項目に限定(不要な項目をスキーマ定義から除く)することにより、処理効率が向上します。
スキーマ定義/外部キー 必須 使用不可 [テーブル名]で指定したテーブルの該当の列が更新のキー項目かどうかを選択します。
  • [true]:更新のキー項目に指定します。
  • [false]:更新のキー項目に指定しません。
スキーマ定義/ラベル 必須 使用不可 [テーブル名]で指定したテーブルの列のラベル名を表示します。  
スキーマ定義/API 必須 使用不可 [テーブル名]で指定したテーブルの列のAPI名を表示します。  
スキーマ定義/型 必須 使用不可 [テーブル名]で指定したテーブルの列のデータ型を表示します。  
スキーマ定義/Null設定 省略可 使用不可 入力データがnullであった場合、nullで上書きするか、該当項目の更新をスキップするかを項目単位に選択します。
  • [チェックあり]:
    入力データがnullの場合、この項目をnullで上書きします。
  • [チェックなし]:
    入力データがnullの場合、この項目の更新をスキップし、更新前の状態を維持します。
    入力データがnull以外の場合、この項目は入力データで上書きします。
  • [項目単位に設定する]で[チェックあり]にした場合、有効になります。
リレーションシップ項目定義 省略可 - スキーマ定義にリレーション項目が存在する場合、外部キーによる更新を行うための項目を設定します。
リレーション先オブジェクトの外部キー項目を選択することにより、リレーション関係を持たせたデータの受け渡しが可能となります。
リレーションシップ項目定義/元項目API名 必須 使用不可 [テーブル名]で指定したテーブルのリレーション項目の列のAPI名を表示します。  
リレーションシップ項目定義/リレーションシップ名 必須 使用不可 [テーブル名]で指定したテーブルのリレーション項目の列のリレーションシップ名を表示します。  
リレーションシップ項目定義/オブジェクトAPI名 省略可 使用不可 [テーブル名]で指定したテーブルのリレーション項目の列のリレーション先のオブジェクトのAPI名を選択します。  
リレーションシップ項目定義/リレーション用カラムAPI名 省略可 使用不可 [テーブル名]で指定したテーブルのリレーション項目の列のリレーション先オブジェクトの外部キー項目を選択します。
  • 省略した場合、リレーション先オブジェクトの該当レコードのIDを受け渡す仕様となります。
プロパティアクション
項目名 説明 備考
スキーマの作成 Salesforceに対して書き込みを行う項目の追加・削除を行うことができます。
設定方法については、「スキーマの作成」を参照してください。		  
オプション設定
項目名 必須/省略可 変数の使用 説明 備考
カラム名タイプ 必須 使用不可 マッピングでスキーマを表示する際のカラム名の表示タイプを選択します。
  • [ラベル]:
    Salesforceで定義されたラベル名(項目名)で表示します。
  • [API]:(デフォルト)
    Salesforceで定義されたAPI参照名で表示します。
  
バッチサイズ 必須 使用可 Salesforceに対してデータ書き込み処理を行う際のバッチサイズを入力します。
  • デフォルト値は「200」です。
  • 「1」以上「200」以下の値が指定できます。範囲以外の値が指定された場合、エラーが発生します。
  • 使用環境によりますが、一般的にバッチサイズを大きくすることにより、データの書き込み効率は向上します。
  • Salesforceアダプタの仕様として、10,000件のデータを書き込むケースで、バッチサイズを200と設定した場合、書き込み処理を50回に分けて実行します。
更新時Null設定 必須 使用不可 更新対象フィールドに対する入力データがnullであった場合、nullで上書きするか、該当項目の更新をスキップするかを選択します。
  • [読み込みデータで常に上書き]:(デフォルト)
    入力データがnullの場合、更新対象フィールドをnullで上書きします。
  • [読み込みデータをスキップ]:
    入力データがnullの場合、更新対象フィールドの更新をスキップし、更新前の状態を維持します。
    入力データがnull以外の場合、更新対象フィールドは入力データで上書きします。
  
項目単位に設定する 省略可 使用不可 [更新時Null設定]を項目単位に設定するかどうかを選択します。
項目単位の設定は、[スキーマ定義/Null設定]で行います。
  • [チェックあり]:
    項目単位に設定を行います。
  • [チェックなし]:(デフォルト)
    項目単位に設定を行いません。
  • API 53.0以降のグローバルリソースを選択している場合のみ有効になります。
  • [更新時Null設定]で[読み込みデータで常に上書き]を選択した場合、有効になります。
更新結果取得有無 必須 使用不可 Salesforceに対してデータ書き込み処理を行った結果を取得するかどうかを指定します。
  • [取得する]:(デフォルト)
    データ書き込み処理を行った結果を取得します。
  • [取得しない]:
    データ書き込み処理を行った結果を取得しません。
  • [取得する]を選択した場合、スキーマ定義に指定した項目および結果情報の項目をテーブルモデル型のデータとして後続に受け渡すことができます。
  • 取得する情報については、「スキーマ」を参照してください。
  • 使用例については、「結果取得使用例」を参照してください。
Base64項目入力形式 必須 使用不可 データ型がBase64である項目に対しての入力データ形式を指定します。
  • [Base64データ]:(デフォルト)
    Base64データを入力します。
  • [ファイルパス]:
    ファイルパスを入力します。
プロパティアクション
項目名 説明 備考
テーブル情報の表示 操作を行っているオブジェクトのテーブル構造を確認できます。
テーブル構造の参照方法については、「テーブル情報の表示」を参照してください。
  • 他のオブジェクトのテーブル構造を確認したい場合、[全テーブル情報の読み込み]をクリックしてください。
全テーブル情報の読み込み 取得可能なすべてのテーブル構造を取得します。
実行後に、[テーブル情報の表示]から取得した内容を確認することができます。		  
ファイルからスキーマ定義を読み取り ファイルチューザでファイルを選択して、そのファイルの1行目にカンマ区切りで指定された項目(API)を読み取り、スキーマ定義として設定します。
  • 選択するファイルのエンコードは「UTF-8」を指定してください。
スキーマ定義をファイルへ出力 ファイルチューザで指定したファイルの1行目に、[スキーマ定義/API]の項目をカンマ区切りで出力します。
  • API 53.0以降のグローバルリソースを選択している場合のみ有効になります。
  • [スキーマ定義/API]以外の項目は出力しません。
  • 指定したファイルのエンコードは「UTF-8」になります。
  • 指定したファイルが存在する場合、上書きされます。
  • ファイルパスはDataSpiderファイルシステムの絶対パスで指定してください。
  • パス区切り文字「/」以外のDataSpiderファイルシステムの使用禁止文字は使用できません。
  • 本プロパティアクションで出力したファイルを[ファイルからスキーマ定義を読み取り]で読み取ることができます。
データ処理方式
項目名 必須/省略可 変数の使用 説明 備考
データ処理方式 必須 使用不可 データ処理方式を選択します。
  • [スクリプトの設定を使用する]:(デフォルト)
    スクリプトプロパティの大容量データ処理の設定をアダプタに使用します。
  • [大容量データ処理を行わない]:
    大容量データ処理を行いません。
  • [大容量データ処理を行う]:
    大容量データ処理を行います。
  
コメント
項目名 必須/省略可 変数の使用 説明 備考
コメント 省略可 使用不可 このアダプタの簡単な説明を記述することができます。
説明を記述すると、仕様書に反映させることができます。		  

スキーマ

入力スキーマ

[スキーマ定義]の設定により、カラム数が異なります。
スキーマ構造については、「テーブルモデル型のスキーマ」を参照してください。

出力スキーマ

[スキーマ定義]で設定されたカラムに、更新結果の情報が付与されます。
(以下、「ラベル/API」という形式で表記)

<?xml version="1.0" encoding="UTF-8" ?>
<table>
   <row>
    <column>[スキーマ定義]で設定されたラベル/API</column>
       :
     <column>更新結果_ID/upsert_result_id</column>
     <column>更新結果_成功フラグ/upsert_result_is_success</column>
     <column>更新結果_新規作成フラグ/upsert_result_is_created</column>
     <column>更新結果_エラーステータスコード/upsert_result_error_status_code</column>
     <column>更新結果_エラーメッセージ/upsert_result_error_message</column>
     <column>更新結果_行番号/upsert_result_row_number</column>
   </row>
   <row>
     :
   </row>
</table>
要素名 列名(ラベル/API) 説明 備考
row
-
 入力スキーマに渡されたデータ件数分繰り返します。
  • [更新結果取得有無]を[取得しない]とした場合、0件となります。
  • データ型の不一致など不整合なデータが存在した場合、入力データ順と出力データ順は必ずしも一致しません。[更新結果_行番号/update_result_row_number]を順序条件とすることで、後続のMapperで入力データ順にソートすることができます。
column 更新結果_ID/upsert_result_id SalesforceのIDを出力します。  
更新結果_成功フラグ/upsert_result_is_success 成功フラグを出力します。
  • [true]:処理に成功しました。
  • [false]:処理に失敗しました。[更新結果_エラーステータスコード/upsert_result_error_status_code]および[更新結果_エラーメッセージ/upsert_result_error_message]を確認してください。
  
更新結果_新規作成フラグ/upsert_result_is_created 新規作成フラグを出力します。
  • [true]:レコードが新規作成されました。
  • [false]:レコードの新規作成は行われませんでした。
  
更新結果_エラーステータスコード/upsert_result_error_status_code SalesforceのAPIが返すステータスコードを出力します。  
更新結果_エラーメッセージ/upsert_result_error_message SalesforceのAPIが返すメッセージを出力します。  
更新結果_行番号/upsert_result_row_number 入力スキーマに渡されたデータ内のノードの位置に基づいて番号を出力します。  

Mapperでのスキーマ読み込み

スキーマは自動で読み込まれます。
詳細については、「スキーマ編集」を参照してください。

大容量データ処理

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

トランザクション

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

PSPでの使用について

PSPでは使用できません。

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

コンポーネント変数名 説明 備考
insert_count 追加処理に成功したデータの件数が格納されます。
  • デフォルト値はnullです。
update_count 更新処理に成功したデータの件数が格納されます。
  • デフォルト値はnullです。
error_count 追加・更新処理に失敗したデータの件数が格納されます。
  • デフォルト値はnullです。
read_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のバージョンにより、格納される内容が変わる可能性があります。

更新時のキー指定

データ書き込み(UPSERT)処理では、Salesforceであらかじめ作成された外部ID(またはID)を指定して、入力データのうち、外部ID(またはID)の値と一致する行が既にSalesforceに存在した場合は、
その行を更新し、なければ追加するという処理を、Salesforceが判別して追加・更新(IDの場合は更新)を行います。



画像内の番号 名称 説明 備考
(1) Salesforceの外部IDの設定 Salesforceのカスタマイズ機能を使用して外部IDの項目を作成します。
新規項目作成の詳細を入力する画面より、外部ID「外部システムの一意のレコード識別子として設定する」にチェックを入れます。
  • 本説明にて使用している項目の設定は設定例となります。
    使用しているSalesforce組織に必ず存在するものではありません。
    各種設定を行った上で本機能を使用してください。
(2) 外部キー項目の設定 [スキーマ定義]にて、(1)で作成した外部ID項目の[外部キー]に「true」を選択します。  

結果取得使用例

[挿入結果取得有無]に[取得する]を選択した場合、入力データに対する挿入結果を、テーブルモデル型のデータとして後続に受け渡すことが可能です。

リレーションシップ項目定義

参照項目(Reference項目)の更新処理では、これまで参照先オブジェクトのIDをMapperにて受け渡して更新する仕様でした。
当設定を行うことにより、参照先オブジェクトの外部キー項目の値をMapperにて受け渡すことで、外部キーに対応するレコードのIDを自動で取得し更新することが可能となります。

スキーマの作成

Salesforceから読み取りを行うデータ項目、または書き込みを行うデータ項目をスキーマの作成で指定することができます。
処理に必要な項目のみを指定することにより、Salesforceに対する通信データ量を削減することができ、一般的に処理効率が向上します。
Salesforceへ書き込み(追加・更新)を行なう場合、「追加不可」または「更新不可」の項目は未選択にする必要があります。



画像内の番号 名称 説明 備考
(1) 選択済み項目 Salesforceから読み取り、または書き込みを行う項目を選択します。  
(2) 未選択の項目 Salesforceから読み取り、または書き込みを行わない項目を選択します。
  • 列名上部のフィールドに値を入力・選択することで項目を絞り込むことができます。
    テキストフィールドの場合、入力した値の前方一致で絞り込まれます。

テーブル情報の表示

Salesforceのテーブルに対する操作可能な処理、およびテーブルのフィールド属性を確認することができます。
また、フィールド情報については、印刷することも可能です。



画像内の番号 名称 説明 備考
(1) テーブル名 テーブル構造の表示を行うテーブルを選択します。  
(2) テーブル情報 選択したテーブルに対する、操作可能なオペレーションを表示します。  
(3) 桁数 項目の桁数を表示します。  
(4) 外部ID 対象項目が外部IDとして設定されているか否かを表します。  
(5) 追加可能 データ追加時に値を設定することが可能か否かを表します。  
(6) 更新可能 データ更新時に値を設定することが可能か否かを表します。  
(7) Null許可 データ追加、更新時にNullが許容されるか否かを表します。  
(8) 初期値有無 データ追加時にSalesforceが初期値を自動設定するか否かを表します。  
(9) 参照先 参照関係または主従関係の項目の場合、参照先のオブジェクト名を表示します。  

仕様制限

主な例外

例外名 原因 対策
ResourceNotFoundException
リソース定義が見つかりませんでした。名前:[]		 [接続先]が指定されていません。 [接続先]を指定してください。
ResourceNotFoundException
リソース定義が見つかりませんでした。名前:[<グローバルリソース名>]		 [接続先]で選択されたリソース定義が見つかりません。 [接続先]で指定したグローバルリソースを確認してください。
java.net.UnknownHostException グローバルリソースで指定したPROXYサーバが見つからない例外です。 PROXYサーバの状態を確認して下さい。または、[接続先]で指定したグローバルリソースの[Proxyホスト]を確認してください。
java.net.SocketTimeoutException
connect timed out 		Salesforceに接続中にタイムアウトが発生しました。 ネットワークの状態、Salesforceのサーバの状態を確認してください。または、[接続先]で指定したグローバルリソースの[Connectionタイムアウト(秒)]を確認してください。
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の関連ドキュメントなどに対象のエラーに関する情報がないか確認してください。

注意事項