SOAP API 開発者ガイド
jupdate()
組織のデータ内にある 1 つ以上の既存レコードを更新します。
構文
1SaveResult[] = connection.update(sObject[] sObjects);使用方法
取引先や取引先責任者など、組織のデータ内にある 1 つ以上の既存レコードを更新するには、このコールを使用します。update() コールは、SQL の UPDATE ステートメントに類似しています。
権限
クライアントアプリケーションには、指定されたオブジェクトと、そのオブジェクト内の個々の項目に対して update() を実行するのに十分な権限でログインする必要があります。詳細は、「データアクセスに影響する要素」を参照してください。
特別な処理
特定のオブジェクト、またこれらのオブジェクト内にある特定の項目には、特別な処理または権限が必要です。たとえば、オブジェクトの親オブジェクトへのアクセス権限も必要になる場合があります。特定のオブジェクトのレコードを更新する前に、「標準オブジェクト」および Salesforce オンラインヘルプの説明を必ず読んでください。
更新可能なオブジェクト
一部のレコードは、API を使用して更新できません。update() コールからレコードを更新するには、そのオブジェクトが更新可能に設定されている (updateable が true) 必要があります。 オブジェクトが更新できるかどうかを確認するために、オブジェクトに対して describeSObjects() コールを実行して updateable プロパティを調べることができます。
必須項目
必須項目を更新する場合、値を入力する必要があります。値を null に設定することはできません。詳細は、「必須項目」を参照してください。
ID 項目
名前に「Id」が含まれている項目は、オブジェクトの主キー (「ID データ型」を参照) または外部キー (「reference データ型」を参照) のいずれかです。クライアントアプリケーションは、主キーを更新することはできませんが、外部キーを更新することができます。たとえば、OwnerID は取引先レコードを所有するユーザを参照する外部キーであるため、クライアントアプリケーションは Account の OwnerId を更新することができます。describeSObjects() を使用して、項目が更新可能かどうかを確認できます。
1Maximum number of duplicate updates in one batch (12 allowed).自動的に更新される項目
API は、LastModifiedDate、LastModifiedById、および SystemModstamp などの特定の項目を自動的に更新します。これらの値を update() コールで明示的に指定することはできません。
値の null へのリセット
項目値を null にリセットするには、sObject の fieldsToNull の配列に項目名を追加します。必須項目 (nillable が false) を null に設定することはできません。
有効な項目値
整数項目については整数 (英字は不可)、項目のデータ型に対して有効な値を入力する必要があります。クライアントアプリケーションでは、使用しているプログラム言語および開発ツールに指定されたデータ形式に従ってください (開発ツールは、SOAP メッセージのデータ型の適切な対応付けを処理します)。
文字列値
String 項目に値を保存する場合、API は先頭および末尾の空白文字を削除します。たとえば、名前項目の値に " ABC Company " と入力されると、その値はデータベースに "ABC Company" と保存されます。
API バージョン 15.0 以降、文字列を含む項目に値を指定し、値が項目に対して大きすぎる場合、コールは失敗してエラーが返されます。これまでのバージョンの API では、値は切り捨てられ、コールは正常に終了していました。バージョン 15.0 以降でもこの動作を保持する場合、AllowFieldTruncationHeader SOAP ヘッダーを使用してください。
割り当てルール
Case または Lead オブジェクトを更新するとき、クライアントアプリケーションで AssignmentRuleHeader オプションを設定して、Salesforce ユーザインターフェースで設定した割り当てルールに基づいて、ケースまたはリードが 1 つ以上のユーザに自動的に割り当てられるようにすることができます。詳細は、「Case」または「Lead」を参照してください。
エラー時のロールバック
AllOrNoneHeader ヘッダーを使用すると、すべてのレコードが正常に処理されない限り、すべての変更をロールバックできます。このヘッダーは、API バージョン 20.0 以降で使用できます。正常に処理されないレコードがあった場合に、コールですべての変更をロールバックできます。
Chatter フィードの自動登録
作成するレコードを登録するには、ユーザは個人設定の [作成したレコードを自動的にフォローする] オプションを有効にする必要があります。自動登録が有効化されている場合、ユーザは自分が作成したレコードを自動的にフォローし、それらのレコードへの変更が [ホーム] タブの Chatter フィードに表示されます。
レコードの所有者を更新する場合、新しい所有者が Chatter フィード設定でレコードの自動登録が有効化されていない限り、新しい所有者は自動的にレコードに登録されません。前の所有者の登録は自動的には解除されません。新しい所有者のレコードの自動登録が有効化されている場合は、新旧両方の所有者のニュースフィードでレコードへの変更が表示されます。
ユーザはレコードまたは他のユーザを登録できます。レコードへの変更とユーザからの更新は、ユーザのホームページの Chatter フィードに表示されます。これは、Salesforce で他のユーザやレコードに加えられた変更の最新状況を把握するのに役立ちます。フィードは、API バージョン 18.0 以降で使用できます。
オブジェクト種別が異なるレコードの更新
API バージョン 20.0 以降では、1 回のコールで、カスタムオブジェクトも含め、複数のオブジェクト種別のレコードを更新できます。たとえば、取引先責任者と取引先を 1 回のコールで更新できます。1 回のコールで、最大 10 種類のオブジェクトのレコードを更新できます。
レコードは、sObjects 入力配列に入力された順序で保存されます。
Salesforce では、オブジェクト種別が異なるレコードは複数のチャンクに分けられます。1 つのチャンクは、sObjects 入力配列のサブセットで、各チャンクにはオブジェクト種別が同じレコードが含まれます。データは、チャンク単位にコミットされます。チャンクに含まれるレコードに関連する Apex トリガは、チャンクごとに 1 回起動されます。次のレコードのセットを含む sObjects 入力配列があるとします。
1account1, account2, contact1, contact2, contact3, case1, account3, account4, contact4Salesforce は、レコードを次の 5 つのチャンクに分割します。
- account1, account2
- contact1, contact2, contact3
- case1
- account3, account4
- contact4
コールごとに最大 10 個のチャンクを処理できます。sObjects 配列に含まれるチャンクが 10 個よりも多い場合、レコードを複数のコールに分けて処理する必要があります。
update() と外部キー
外部 ID 項目を外部キーとして使用することによって、最初に親レコードの ID を照会するのではなく、レコードを更新して他の既存のレコードに関連付ける操作を 1 つの手順で実行できます。これを行うには、指定された外部 ID 項目のみを持つ親 sObject のインスタンスに、外部キーを設定します。この外部 ID は親レコードの外部 ID の値と一致する必要があります。
次の Java および C# の例では、MyExtId__c というカスタム外部 ID 項目を使用して商談を更新して、既存の取引先に関連付ける方法を示します。各例には更新する商談の ID を受け取るメソッドがあります。このサンプルでは、商談 sObject を作成し、そのオブジェクトが更新対象の既存の商談を指定するよう ID 項目を設定した後、フェーズ項目の新しい値を設定し、外部 ID 項目を取引先オブジェクトに設定します。次に商談を更新します。商談が更新されると、取引先がその商談の親になり、フェーズ名が更新されます。
Java の例
1public void updateForeignKeySample(String oppId) {
2 try {
3 Opportunity updateOpportunity = new Opportunity();
4 // Point to an existing opportunity to update
5 updateOpportunity.setId(oppId);
6 updateOpportunity.setStageName("Qualification");
7
8 Account parentAccountRef = new Account();
9 parentAccountRef.setMyExtId__c("SAP1111111");
10 updateOpportunity.setAccount(parentAccountRef);
11
12 SaveResult[] results = connection
13 .update(new SObject[] { updateOpportunity });
14 } catch (ConnectionException ce) {
15 ce.printStackTrace();
16 }
17}C# の例
1public void updateForeignKeySample(String oppId)
2{
3 try
4 {
5 Opportunity updateOpportunity = new Opportunity();
6 // Point to an existing opportunity to update
7 updateOpportunity.Id = oppId;
8 updateOpportunity.StageName = "Prospecting";
9
10 Account parentAccountRef = new Account();
11 parentAccountRef.MyExtId__c = "SAP1111111";
12 updateOpportunity.Account = parentAccountRef;
13
14 SaveResult[] results = binding.update(
15 new sObject[] { updateOpportunity });
16 }
17 catch (SoapException e)
18 {
19 Console.WriteLine("An unexpected error has occurred: " +
20 e.Message + "\n" + e.StackTrace);
21 }
22}レコード更新の基本手順
- update() の対象となる各レコードの ID を確認します。たとえば、query() を特定の検索条件に基づいてコールし、更新するレコード (とその ID) のセットを取得します。更新するレコードの ID がわかっている場合は、retrieve() をコールすることもできます。ID についての詳細は、「ID データ型」を参照してください。
- レコードごとに sObject を作成し、項目に更新するデータを入力します。
- sObject[] 配列を作成し、配列に更新するレコードを入力します。
- update() をコールし、sObject[] 配列を渡します。
- SaveResult[] オブジェクトの結果を処理してレコードの更新が成功したかどうかを確認します。
サンプルコード — Java
このサンプルでは、更新する取引先の ID を受け取ります。2 つの取引先 sObject を作成し、それぞれの sObjects が既存の取引先を指すよう、受け取った ID を 1 つずつ設定した後、その他の項目を設定します。次に、update() コールを実行し、結果を検証します。
1public void updateRecords(String[] ids) {
2 Account[] updates = new Account[2];
3
4 Account account1 = new Account();
5 account1.setId(ids[0]);
6 account1.setShippingPostalCode("89044");
7 updates[0] = account1;
8
9 Account account2 = new Account();
10 account2.setId(ids[1]);
11 account2.setNumberOfEmployees(1000);
12 updates[1] = account2;
13
14 // Invoke the update call and save the results
15 try {
16 SaveResult[] saveResults = connection.update(updates);
17 for (SaveResult saveResult : saveResults) {
18 if (saveResult.isSuccess()) {
19 System.out.println("Successfully updated Account ID: "
20 + saveResult.getId());
21 } else {
22 // Handle the errors.
23 // We just print the first error out for sample purposes.
24 Error[] errors = saveResult.getErrors();
25 if (errors.length > 0) {
26 System.out.println("Error: could not update " + "Account ID "
27 + saveResult.getId() + ".");
28 System.out.println("\tThe error reported was: ("
29 + errors[0].getStatusCode() + ") "
30 + errors[0].getMessage() + ".");
31 }
32 }
33 }
34 } catch (ConnectionException ce) {
35 ce.printStackTrace();
36 }
37}サンプルコード — C#
このサンプルでは、更新する取引先の ID を受け取ります。2 つの取引先 sObject を作成し、それぞれの sObjects が既存の取引先を指すよう、受け取った ID を 1 つずつ設定した後、その他の項目を設定します。次に、update() コールを実行し、結果を検証します。
1public void updateRecords(String[] ids)
2{
3 Account[] updates = new Account[2];
4
5 Account account1 = new Account();
6 account1.Id = ids[0];
7 account1.ShippingPostalCode = "89044";
8 updates[0] = account1;
9
10 Account account2 = new Account();
11 account2.Id = ids[1];
12 account2.NumberOfEmployees = 1000;
13 updates[1] = account2;
14
15 // Invoke the update call and save the results
16 try
17 {
18 SaveResult[] saveResults = binding.update(updates);
19 foreach (SaveResult saveResult in saveResults)
20 {
21 if (saveResult.success)
22 {
23 Console.WriteLine("Successfully updated Account ID: " +
24 saveResult.id);
25 }
26 else
27 {
28 // Handle the errors.
29 // We just print the first error out for sample purposes.
30 Error[] errors = saveResult.errors;
31 if (errors.Length > 0)
32 {
33 Console.WriteLine("Error: could not update " +
34 "Account ID " + saveResult.id + "."
35 );
36 Console.WriteLine("\tThe error reported was: (" +
37 errors[0].statusCode + ") " +
38 errors[0].message + "."
39 );
40 }
41 }
42 }
43 }
44 catch (SoapException e)
45 {
46 Console.WriteLine("An unexpected error has occurred: " +
47 e.Message + "\n" + e.StackTrace);
48 }
49}