この文章は Salesforce 機械翻訳システムを使用して翻訳されました。詳細はこちらをご参照ください。

upsert()

新しいオブジェクトを作成するか、既存のオブジェクトを更新します。カスタム項目を使用して、既存オブジェクトの有無を判別します。セールスフォース・ドットコムでは、多くの場合、不要な重複レコードが作成されないようにするために、create() の代わりに upsert() を使用することをお勧めしています。API バージョン 7.0 以降で使用できます。

API バージョン 15.0 以降、文字列を含む項目に値を指定し、値が項目に対して大きすぎる場合、コールは失敗してエラーが返されます。これまでのバージョンの API では、値は切り捨てられ、コールは正常に終了していました。バージョン 15.0 以降でもこの動作を保持する場合、AllowFieldTruncationHeader SOAP ヘッダーを使用してください。

メモ

構文

1UpsertResult[] = connection.upsert(String externalIdFieldName, sObject[] sObjects);

使用方法

Upsert は、insert と update の結合したものです。このコールは、オブジェクトに外部 ID 項目または項目プロパティが idLookup の項目がある場合、オブジェクトに使用できます。

カスタムオブジェクトの場合、このコールは、外部 ID というインデックス付けされたカスタム項目を使用して、新しいレコードを作成するか、既存オブジェクトを更新するかを判別します。標準オブジェクトの場合、このコールでは外部 ID の代わりに idLookup を持つ項目の名前を使用できます。

外部 ID 項目では、merge() を使用することはできません。

メモ

外部 ID 項目など、カスタム項目のオブジェクトへの追加に関する詳細は、Salesforce オンラインヘルプの項目の追加に関するトピックを参照してください。

このコールを使用すると、特に次のような場合に、必要なコール数を大幅に減らすことができます。

組織の Salesforce データと、経理や製造などの ERP (統合業務ソフト) システムと統合する場合。
データをインポートして、重複オブジェクトの作成を回避する場合。

[外部 ID] 属性および Unique 属性の両��が選択された (インデックスが一意) カスタム項目を持つオブジェクトのレコードを更新/挿入する場合、Unique 属性によって重複作成が防止されるため、特別な権限は必要ありません。[外部 ID] 属性が選択され、Unique 属性が選択されていない (インデックスが一意ではない) オブジェクトのレコードを更新/挿入する場合、クライアントアプリケーションがこのコールを実行するには「すべてのデータの参照」権限が必要です。

外部 ID による一致は、外部 ID 項目で Unique 属性と [「ABC」と「abc」を値の重複として扱う (大文字と小文字を区別しない)] オプションを選択している場合にのみ大文字と小文字の区別をしません。これらのオプションは、項目作成時に Salesforce ユーザインターフェースで選択されています。この場合、「ABC123」は「abc123」と一致します。操作を実行する前に、外部 ID 項目で大文字と小文字を区別しないオプションを選択していない場合は、大文字と小文字を考慮しない場合に一致する値の外部 ID を確認します。そのような値が存在する場合、それらの値が一意のものとなるよう変更したり、外部 ID 項目の大文字と小文字を区別するオプションを選択したりする必要があります。項目属性についての詳細は、Salesforce オンラインヘルプの「カスタム項目の属性」を参照してください。

メモ

upsert が update() と create() を判別する方法

upsert では、外部 ID を使用して、新規レコードを作成するか、既存レコードを更新するかを判別します。

外部 ID が一致しない場合、新規レコードが作成されます。
外部 ID が一度だけ一致したら、既存レコードが更新されます。
外部 ID が複数回一致すると、エラーが報告されます。
バッチコールで外部 ID が同じ複数のレコードを一括更新すると、それらのレコードは、UpsertResult ファイルでエラーとしてマークされます。レコードは作成も更新もされません。

エラー時のロールバック

AllOrNoneHeader ヘッダーを使用すると、すべてのレコードが正常に処理されない限り、すべての変更をロールバックできます。このヘッダーは、API バージョン 20.0 以降で使用できます。正常に処理されないレコードがあった場合に、コールですべての変更をロールバックできます。

Chatter フィードの自動登録

作成するレコードを登録するには、ユーザは個人設定の [作成したレコードを自動的にフォローする] オプションを有効にする必要があります。自動登録が有効化されている場合、ユーザは自分が作成したレコードを自動的にフォローし、それらのレコードへの変更が [ホーム] タブの Chatter フィードに表示されます。

レコードの所有者を更新する場合、新しい所有者が Chatter フィード設定でレコードの自動登録が有効化されていない限り、新しい所有者は自動的にレコードに登録されません。前の所有者の登録は自動的には解除されません。新しい所有者のレコードの自動登録が有効化されている場合は、新旧両方の所有者のニュースフィードでレコードへの変更が表示されます。

ユーザはレコードまたは他のユーザを登録できます。レコードへの変更とユーザからの更新は、ユーザのホームページの Chatter フィードに表示されます。これは、Salesforce で他のユーザやレコードに加えられた変更の最新状況を把握するのに役立ちます。フィードは、API バージョン 18.0 以降で使用できます。

upsert() と外部キー

外部 ID 項目を外部キーとして使用することによって、最初に親レコードの ID を照会するのではなく、レコードを作成または更新して他の既存のレコードに関連付ける操作を 1 つの手順で実行できます。これを行うには、指定された外部 ID 項目のみを持つ親 sObject のインスタンスに、外部キーを設定します。この外部 ID は親レコードの外部 ID の値と一致する必要があります。create() とは異なり、upsert() を使用して外部キーで関連する子レコードを作成または更新するには、親レコードがすでに存在する必要があります。

次の Java および C# の例では、商談を更新/挿入します。この場合、商談はデータベースに存在しないので、upsert() コールによって作成されます。この商談は既存の取引先を参照します。個別のクエリを取得する必要がある取引先 ID を指定せず、取引先の外部 ID、この例では MyExtId__c カスタム項目を指定します。

Java の例

1public void upsertForeignKeySample() {
2   try {
3      Opportunity newOpportunity = new Opportunity();
4      newOpportunity.setName("UpsertOpportunity");
5      newOpportunity.setStageName("Prospecting");
6      Calendar dt = connection.getServerTimestamp().getTimestamp();
7      dt.add(Calendar.DAY_OF_MONTH, 7);
8      newOpportunity.setCloseDate(dt);
9      newOpportunity.setMyExtId__c("UPSERTID001");
10
11      // Parent Account record must already exist
12      Account parentAccountRef = new Account();
13      parentAccountRef.setMyExtId__c("SAP111111");
14      newOpportunity.setAccount(parentAccountRef);
15
16      SaveResult[] results = connection
17            .upsert("MyExtId__c", new SObject[] { newOpportunity });         
18   } catch (ConnectionException ce) {
19      ce.printStackTrace();
20   }
21}

C# の例

1public void upsertForeignKeySample()
2{
3   try
4   {
5      Opportunity newOpportunity = new Opportunity();
6      newOpportunity.Name = "UpsertOpportunity";
7      newOpportunity.StageName = "Prospecting";
8      DateTime dt = (DateTime)binding.getServerTimestamp().timestamp;
9      newOpportunity.CloseDate = dt.AddDays(7);
10      newOpportunity.CloseDateSpecified = true;
11      newOpportunity.MyExtId__c = "UPSERTID001";
12
13      // Parent Account record must already exist
14      Account parentAccountRef = new Account();
15      parentAccountRef.MyExtId__c = "SAP111111";
16      newOpportunity.Account = parentAccountRef;
17
18      SaveResult[] results = binding
19            .upsert("MyExtId", new sObject[] { newOpportunity });
20   }
21   catch (SoapException e)
22   {
23      Console.WriteLine("An unexpected error has occurred: " +
24                                 e.Message + "\n" + e.StackTrace);
25   }
26}

サンプルコード — Java

このサンプルでは、MyExtId__c というカスタム外部 ID 項目を使用して 2 つの取引先を更新/挿入します。upsert() コールでは、取引先を作成するか更新するかを決定するため、MyExtId__c 項目に基づいて取引先を照合します。このサンプルを実行する前に、MyExtId__c 項目名を組織の既存のカスタム ID 項目名に変更してください。

1public void upsertRecords() {
2   SObject[] upserts = new Account[2];
3
4   Account upsertAccount1 = new Account();
5   upsertAccount1.setName("Begonia");
6   upsertAccount1.setIndustry("Education");
7   upsertAccount1.setMyExtId__c("1111111111");
8   upserts[0] = upsertAccount1;
9
10   Account upsertAccount2 = new Account();
11   upsertAccount2 = new Account();
12   upsertAccount2.setName("Bluebell");
13   upsertAccount2.setIndustry("Technology");
14   upsertAccount2.setMyExtId__c("2222222222");
15   upserts[1] = upsertAccount2;
16
17   try {
18      // Invoke the upsert call and save the results.
19      // Use External_Id custom field for matching records.
20      UpsertResult[] upsertResults = connection.upsert(
21                                  "MyExtId__c", upserts);
22      for (UpsertResult result : upsertResults) {
23         if (result.isSuccess()) {
24            System.out.println("\nUpsert succeeded.");
25            System.out.println((result.isCreated() ? "Insert" : "Update")
26                  + " was performed.");
27            System.out.println("Account ID: " + result.getId());
28         } else {
29            System.out.println("The Upsert failed because: "
30                  + result.getErrors()[0].getMessage());
31         }
32      }
33   } catch (ConnectionException ce) {
34      ce.printStackTrace();
35   }
36}

サンプルコード — C#

1public void upsertRecords()
2{
3   sObject[] upserts = new Account[2];
4
5   Account upsertAccount1 = new Account();
6   upsertAccount1.Name = "Begonia";
7   upsertAccount1.Industry = "Education";
8   upsertAccount1.MyExtId__c = "1111111111";
9   upserts[0] = upsertAccount1;
10
11   Account upsertAccount2 = new Account();
12   upsertAccount2 = new Account();
13   upsertAccount2.Name = "Bluebell";
14   upsertAccount2.Industry = "Technology";
15   upsertAccount2.MyExtId__c = "2222222222";
16   upserts[1] = upsertAccount2;
17
18   try
19   {
20      // Invoke the upsert call and save the results.
21      // Use External_Id custom field for matching records.
22      UpsertResult[] upsertResults =
23            binding.upsert("MyExtId__c", upserts);
24      foreach (UpsertResult result in upsertResults)
25      {
26         if (result.success)
27         {
28            Console.WriteLine("\nUpsert succeeded.");
29            Console.WriteLine(
30                  (result.created ? "Insert" : "Update") +
31                  " was performed."
32            );
33            Console.WriteLine("Account ID: " + result.id);
34         }
35         else
36         {
37            Console.WriteLine("The Upsert failed because: " +
38                  result.errors[0].message);
39         }
40      }
41   }
42   catch (SoapException e)
43   {
44      Console.WriteLine("An unexpected error has occurred: " +
45                                 e.Message + "\n" + e.StackTrace);
46   }
47}

引数

名前	型	説明
ExternalIDFieldName	string	カスタムオブジェクトの外部 ID 項目属性または標準オブジェクトの idLookup 項目プロパティを持つこのオブジェクトの項目名を含みます。idLookup 項目プロパティは通常、オブジェクトの ID 項目または名前項目である項目にありますが、例外があるため、`upsert()` を実行するオブジェクトのプロパティの有無を確認してください。
sObjects	sObject[]	作成または更新する 1 つ以上 (最大 200) のレコードの配列。すべてのレコードは同じオブジェクト種別である必要があります。

応答

UpsertResult[]

障害

InvalidSObjectFault

UnexpectedErrorFault

SOAP API 開発者ガイド