ファイルアップロード処理

オペレーション名

ファイルアップロード

機能概要

REST API を使用してコンテンツバージョン(ContentVersion)にファイルをアップロードまたは更新します。

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

本オペレーションの使用例については、「ファイルアップロード使用例」を参照してください。

本オペレーションでは以下のAPIを使用します。

SOAP API
- login()
- retrieve()
REST API
- sObject Basic Information
- sObject Rows
- sObject Rows by External ID

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

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

データモデル

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

プロパティ

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

基本設定

項目名	必須/省略可	変数の使用	説明	備考
名前	必須	使用不可	スクリプトキャンバス上での名前を入力します。
入力データ	必須	使用不可	スクリプトキャンバス上にあるコンポーネントを選択します。

必須設定

項目名	必須/省略可	変数の使用	説明	備考
接続先	必須	使用不可	グローバルリソースを選択します。グローバルリソースの設定方法については、「グローバルリソースのプロパティ」を参照してください。 [追加]: 新規にグローバルリソースを追加します。 [一覧の編集]: 「リソース一覧の編集」画面にて、グローバルリソースの設定を編集することができます。	API 43.0以降のグローバルリソースが選択可能です。本コンポーネントでは、影響を受けないグローバルリソースのプロパティがあります。詳細については、「影響を受けないグローバルリソースのプロパティ」を参照してください。
スキーマ定義	必須	-	コンテンツバージョン(ContentVersion)に対して書き込みを行う項目を設定します。	Salesforceに対して書き込みが必要な項目に限定(不要な項目をスキーマ定義から除く)することにより、処理効率が向上します。 [HTTPメソッド]で[PATCH]を選択した場合、[外部ID項目]で選択した項目を選択している必要があります。設定例については、「ファイルアップロードの使用例」を参照してください。
スキーマ定義/ラベル	必須	使用不可	列のラベル名を表示します。
スキーマ定義/API	必須	使用不可	列のAPI名を表示します。
スキーマ定義/型	必須	使用不可	列のデータ型を表示します。
リレーションシップ項目定義	省略可	-	スキーマ定義にリレーション項目が存在する場合、外部キーによる更新を行うための項目を設定します。リレーション先オブジェクトの外部キー項目を選択することにより、リレーション関係を持たせたデータの受け渡しが可能となります。	詳細については、「リレーションシップ項目定義」を参照してください。
リレーションシップ項目定義/元項目API名	必須	使用不可	リレーション項目の列のAPI名を表示します。
リレーションシップ項目定義/リレーションシップ名	必須	使用不可	リレーション項目の列のリレーションシップ名を表示します。
リレーションシップ項目定義/オブジェクトAPI名	省略可	使用不可	リレーション項目の列のリレーション先のオブジェクトのAPI名を選択します。
リレーションシップ項目定義/リレーション用カラムAPI名	省略可	使用不可	リレーション項目の列のリレーション先オブジェクトの外部キー項目を選択します。	省略した場合、リレーション先オブジェクトの該当レコードのIDを受け渡す仕様となります。

プロパティアクション

項目名	説明	備考
スキーマの作成	Salesforceに対して書き込みを行う項目の追加・削除を行うことができます。設定方法については、「スキーマの作成」を参照してください。

オプション設定

項目名	必須/省略可	変数の使用	説明	備考
HTTPメソッド	必須	使用不可	REST APIで使用するHTTPメソッドを選択します。 [POST]:(デフォルト) HTTPのPOSTメソッドでリクエストを実行します。 [PATCH]: HTTPのPATCHメソッドでリクエストを実行します。	新規レコードを作成する場合、[POST]を選択します。例: 新規にファイルをアップロードするファイルの新しいバージョンを追加するレコードを更新する場合、[PATCH]を選択します。例: ファイルのタイトルと説明を更新する外部ID(またはID)を使用してレコードを挿入/更新 (Upsert) する設定例については、「ファイルアップロードの使用例」を参照してください。
外部ID項目	省略可	使用不可	更新処理のキーとする外部ID項目を選択します。	[HTTPメソッド]で[PATCH]を選択した場合、有効かつ必須入力となります。選択した[外部ID項目]は、[スキーマ定義]に設定する必要があります。
更新時Null設定	省略可	使用不可	更新対象フィールドに対する入力データがnullであった場合、nullで上書きするか、該当項目の更新をスキップするかを選択します。 [読み込みデータで常に上書き]:(デフォルト) 入力データがnullの場合、更新対象フィールドをnullで上書きします。 [読み込みデータをスキップ]: 入力データがnullの場合、更新対象フィールドの更新をスキップし、更新前の状態を維持します。入力データがnull以外の場合、更新対象フィールドは入力データで上書きします。	[HTTPメソッド]で[PATCH]を選択した場合、有効となります。
コンテンツドキュメントIDを取得する	省略可	使用不可	アップロードしたファイルのコンテンツドキュメント(ContentDocument)のIDを取得するかどうかを選択します。 [チェックあり]:(デフォルト) コンテンツドキュメントIDを取得します。 [チェックなし]: コンテンツドキュメントIDを取得しません。	[チェックあり]とした場合、取得したコンテンツドキュメントIDをテーブルモデル型のデータとして後続に受け渡すことができます。詳細については、「コンテンツドキュメントIDを取得する」を参照してください。

プロパティアクション

項目名	説明	備考
ファイルからスキーマ定義を読み取り	ファイルチューザでファイルを選択して、そのファイルの1行目にカンマ区切りで指定された項目(API)を読み取り、スキーマ定義として設定します。	選択するファイルのエンコードは「UTF-8」を指定してください。

データ処理方式

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

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

スキーマ

入力スキーマ

[スキーマ定義]の設定により、カラム数が異なります。

スキーマ構造については、「テーブルモデル型のスキーマ」を参照してください。

出力スキーマ

[スキーマ定義]で設定されたカラムに、アップロード結果の情報が付与されます。

<?xml version="1.0" encoding="UTF-8" ?>
<table>
  <row>
    <column>[スキーマ定義]で設定されたAPI</column>
       :
    <column>result_id</column>
    <column>result_is_success</column>
    <column>result_is_created</column>
    <column>result_error_status_code</column>
    <column>result_error_message</column>
    <column>result_row_number</column>
    <column>result_content_document_id</column>
  </row>
  <row>
    :
  </row>
</table>

要素名	列名	説明	備考
row	-	入力スキーマに渡されたデータ件数分繰り返します。
column	result_id	コンテンツバージョン(ContentVersion)のIdを出力します。	レコードが新規作成された場合のみ出力します。
	result_is_success	成功フラグを出力します。 [true]:処理に成功しました。 [false]:処理に失敗しました。[result_error_status_code]および[result_error_message]を確認してください。
	result_is_created	新規作成フラグを出力します。 [true]:レコードが新規作成されました。 [false]:レコードの新規作成は行われませんでした。
	result_error_status_code	SalesforceのAPIが返すステータスコードを出力します。	以下の場合はSalesforceアダプタがコードおよびメッセージを出力します。「SALESFORCE_ADAPTER_ILLEGAL_DATA_TYPE」定義された項目の属性と入力データ型が一致しない場合に設定されます。たとえば、「date」と定義された項目に対し日付以外の文字列が入力された場合などです。
	result_error_message	SalesforceのAPIが返すメッセージを出力します。
	result_row_number	入力スキーマに渡されたデータ内のノードの位置に基づいて番号を出力します。
	result_content_document_id	コンテンツバージョン(ContentVersion)のContentDocumentIdを出力します。	[コンテンツドキュメントIDを取得する]を[チェックなし]とした場合、nullとなります。 [コンテンツドキュメントIDを取得する]を[チェックあり]とした場合においても、nullとなることがあります。詳細については「コンテンツドキュメントIDを取得する」を参照してください。

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_error_message	エラー発生時、発生したエラーのメッセージが格納されます。	デフォルト値はnullです。 DataSpider Servistaのバージョンにより、格納される内容が変わる可能性があります。
operation_error_trace	エラー発生時、発生したエラーのトレース情報が格納されます。	デフォルト値はnullです。 DataSpider Servistaのバージョンにより、格納される内容が変わる可能性があります。

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

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

例: コンテンツバージョン(ContentVersion)への更新(INSERT,UPDATE,UPSERT)

例の詳細

種類	説明	備考
要件仕様	コンテンツバージョン(ContentVersion)の更新処理にて、取引先責任者IDの項目(参照項目)に参照先のオブジェクトのIDを設定したい。参照先となる取引先責任者(Contact)の関連は、入力データの取引先責任者コードに対応するレコードと紐付けたい。
設定方法	コンテンツバージョン(ContentVersion)への更新にて、取引先責任者IDの項目(参照項目)へ参照先オブジェクトとなる取引先責任者(Contact)の取引先責任者コード(あらかじめ作成した外部キー項目:ContactCode__c)の値をMapperに受け渡す事により更新時に対応する参照先オブジェクトのIDを自動で取得してリレーション関係を設定します。	本説明にて使用している項目や一部の設定は使用例となります。使用しているSalesforce組織に必ず存在するものではありません。各種設定を行った上で本機能を使用してください。

連携イメージ

画像内の番号	名称	説明	備考
(1)	取引先責任者(Contact)のデータイメージ	コンテンツバージョン(ContentVersion)から参照されるオブジェクトのデータイメージです。
(2)	取引先責任者(Contact)の外部キー項目	あらかじめ「取引先責任者コード(ContactCode__c)」を外部キーとして設定しておきます。
(3)	入力データイメージ	コンテンツバージョン(ContentVersion)へ更新するための入力データイメージです。	「取引先責任者コード」を保持したデータです。
(4)	コンテンツバージョン(ContentVersion)への更新(INSERT,UPDATE,UPSERT)の設定	ここでは、「タイトル」,「クライアントでのパス」,「バージョンデータ」,「取引先責任者ID」の4項目を更新対象とします。
(5)	リレーションシップ項目定義の設定	「リレーション用カラムAPI名」にて参照先オブジェクトの外部キー項目を選択します。ここでは、リレーション関係を設定するためのキー項目として、参照先オブジェクトの外部キー「Contact.ContactCode__c」を選択します。	選択値が無しの場合、参照先のオブジェクトの該当レコードのIDをMapperに受け渡す仕様となります。
(6)	コンテンツバージョン(ContentVersion)の更新結果データイメージ	コンテンツバージョン(ContentVersion)の更新結果データイメージです。	「取引先責任者コード」に対応したレコードとのリレーション関係が正しく設定されています。

スキーマの作成

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

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

ファイルアップロード使用例

以下に使用例を示します。

コンテンツバージョン(ContentVersion)のオブジェクト詳細については、グローバルリソースで選択したバージョンのドキュメントを以下のリンク先ページより参照してください。

「Salesforce Developer Documentation」-(https://developer.salesforce.com/docs)
- Object Reference for Salesforce and Lightning Platform

例1: 新規にファイルをアップロードする

[スキーマ定義]で以下の項目を設定します。

ラベル	API	型	備考
タイトル	Title	string	[スキーマ定義]で選択しない場合、または[スキーマ定義]で選択して入力データがnullであった場合、「PathOnClient」項目の入力データからファイルパスおよび拡張子を除外したファイル名が自動で保存されます。
クライアントでのパス	PathOnClient	string	ファイルをSalesforceの [プレビュー] タブに表示するには、拡張子を含める必要があります。例: /data/file.txt
バージョンデータ	VersionData	base64	入力データにファイルパスを設定してください。例: /data/file.txt ファイルパスはDataSpiderファイルシステムの絶対パスで指定してください。パス区切り文字「/」以外のDataSpiderファイルシステムの使用禁止文字は使用できません。

[HTTPメソッド]で[POST]を選択します。

例2: ファイルの新しいバージョンを追加する

[スキーマ定義]で以下の項目を設定します。

ラベル	API	型	備考
タイトル	Title	string	[スキーマ定義]で選択しない場合、バージョンアップ前のタイトルが維持されます。 [スキーマ定義]で選択して入力データがnullであった場合、「PathOnClient」項目の入力データからファイルパスおよび拡張子を除外したファイル名が自動で保存されます。
クライアントでのパス	PathOnClient	string	ファイルをSalesforceの [プレビュー] タブに表示するには、拡張子を含める必要があります。例: /data/file.txt
バージョンデータ	VersionData	base64	入力データにファイルパスを設定してください。例: /data/file.txt ファイルパスはDataSpiderファイルシステムの絶対パスで指定してください。パス区切り文字「/」以外のDataSpiderファイルシステムの使用禁止文字は使用できません。
ContentDocument ID	ContentDocumentId	reference	入力データにバージョンアップしたいファイルのコンテンツドキュメント(ContentDocument)のIdを設定します。

[HTTPメソッド]で[POST]を選択します。

例3: ファイルのタイトルと説明を更新する

[スキーマ定義]で以下の項目を設定します。

ラベル	API	型	備考
ContentVersion ID	Id	id	入力データに更新したいファイルのコンテンツバージョン(ContentVersion)のIdを設定します。
タイトル	Title	string
説明	Description	textarea

[HTTPメソッド]で[PATCH]を選択します。

[外部ID項目]で[Id (ContentVersion ID)]を選択します。

例4: 外部ID(またはID)を使用してレコードを挿入/更新 (Upsert) する

外部ID(またはID)の値と一致する行が既にSalesforceに存在した場合は、その行を更新し、なければ追加するという処理を、Salesforceが判別して追加・更新(IDの場合は更新)を行います。
[スキーマ定義]の選択項目によっては更新時にエラーが発生する場合があります（「PathOnClient」を更新しようとした場合など）。

[スキーマ定義]で以下の項目を設定します。

ラベル	API	型	備考
タイトル	Title	string	例1を参考に設定します。
クライアントでのパス	PathOnClient	string
バージョンデータ	VersionData	base64
<外部ID項目のラベル>	<外部ID項目のAPI>	<外部ID項目の型>	スキーマ作成で「外部ID」がチェックありの項目を選択する必要があります。ここで選択するためには、事前にSalesforceのカスタマイズ機能を使用して外部IDの項目を作成します。新規項目作成の詳細を入力する画面より、外部ID「外部システムの一意のレコード識別子として設定する」にチェックを入れます。

[HTTPメソッド]で[PATCH]を選択します。

[外部ID項目]で[<外部ID項目のAPI> (<外部ID項目のラベル>)]を選択します。

コンテンツドキュメントIDを取得する

当設定を行うことにより、アップロードしたファイルのコンテンツドキュメントIDを取得します。
取得したコンテンツドキュメントIDは、出力スキーマの[result_content_document_id]に格納され、テーブルモデル型のデータとして後続に受け渡すことが可能です。

当設定は SOAP API の retrieve() を使用してコンテンツバージョン(ContentVersion)のContentDocumentIdを取得します。

[HTTPメソッド]で[PATCH]を選択し、既存レコードが更新された場合、出力スキーマの[result_content_document_id]はnullとなります。

例：アップロードしたファイルのコンテンツドキュメントIDを取得し、取引先責任者に紐付ける

画像内の番号	名称	説明
(1)	入力データイメージ	コンテンツバージョン(ContentVersion)へ更新するための入力データイメージです。
(2)	コンテンツドキュメントIDの取得有無の設定	[オプション設定]タブの[コンテンツドキュメントIDを取得する]を[チェックあり]とします。
(3)	スクリプトイメージ	本説明のスクリプト実装イメージです。
(4)	ファイル紐付けイメージ	コンテンツバージョン(ContentVersion)へ更新したファイルを紐づけた取引先責任者のSalesforce詳細ページのイメージです。

影響を受けないグローバルリソースのプロパティ

本コンポーネントは、グローバルリソースのプロパティを参照し、REST API を使用してファイルをアップロードします。
以下の設定は SOAP API に関するプロパティのため、影響を受けません。

グローバルリソースのプロパティについては、「グローバルリソースのプロパティ」を参照してください。

オプション設定

項目名	備考
更新時の文字列項目の切り捨て	影響を受けません。入力データが大きすぎる場合、更新は失敗し、出力スキーマの[result_error_status_code]に「STRING_TOO_LONG」が出力されます。

SOAPヘッダー設定

項目名	備考
AllOrNoneヘッダー (allOrNone)	影響を受けません。ファイルアップロードは、1件の入力データにつき1回の REST API を実行します。複数件の入力データの場合、エラーのなかった入力データはコミットされますが、エラーのあった入力データは出力スキーマにエラー情報を格納します。
Emailヘッダー (triggerAutoResponseEmail)	影響を受けません。
Emailヘッダー (triggerOtherEmail)
Emailヘッダー (triggerUserEmail)
Mruヘッダー (updateMru)	影響を受けません。
AssignmentRuleヘッダー (useDefaultRule)	影響を受けません。ファイルアップロードは、有効な割り当てルールが適用されるように REST API を実行します。割り当てルールの ID は指定できません。詳細についてはAPIドキュメント「REST API Developer's Guide」の「Assignment Rule ヘッダー」ページを参照してください。
AssignmentRuleヘッダー (assignmentRuleId)
DisableFeedTrackingヘッダー (disableFeedTracking)	影響を受けません。
DuplicateRuleヘッダー (allowSave)	影響を受けません。

仕様制限

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

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

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

REST APIによるファイルアップロード時の最大サイズは 2GB (ヘッダーを含む)となります。詳細はSalesforceのドキュメントをご確認ください。

主な例外

例外名	原因	対策
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の関連ドキュメントなどに対象のエラーに関する情報がないか確認してください。

注意事項

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

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

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

ファイルアップロード処理

オペレーション名

機能概要

データモデル

プロパティ

基本設定

必須設定

プロパティアクション

オプション設定

プロパティアクション

データ処理方式

コメント

スキーマ

入力スキーマ

出力スキーマ

Mapperでのスキーマ読み込み

大容量データ処理

トランザクション

PSPでの使用について

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

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

スキーマの作成

ファイルアップロード使用例

コンテンツドキュメントIDを取得する

影響を受けないグローバルリソースのプロパティ

オプション設定

SOAPヘッダー設定

仕様制限

主な例外

注意事項