REST API 開発者ガイド
j外部 ID を使用してレコードを挿入/更新 (Upsert) する
- 外部 ID が一致しない場合は、リクエストボディに従って新規レコードが作成されます。
- 外部 ID が一度だけ一致する場合は、リクエストボディに従ってレコードが更新されます。
- 外部 ID が複数回一致する場合は、300 エラーが報告され、レコードは作成も更新もされません。
以降のセクションでは、外部 ID リソースを使用して外部 ID でレコードを取得する方法とレコードを Upsert する方法を説明します。
新規レコードの Upsert
この例では、PATCH メソッドを使用して新規レコードを挿入します。外部 ID 項目「customExtIdField__c」がすでに Account に追加されていると想定します。また、customExtIdField 値が 11999 の Account レコードがまだ存在していないと想定します。
- まだ存在していないレコードを Upsert する例
-
1curl https://MyDomainName.my.salesforce.com/services/data/v60.0/sobjects/Account/customExtIdField__c/11999 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X PATCH - JSON リクエストボディ newrecord.json ファイルの例
-
1{ 2 "Name" : "California Wheat Corporation", 3 "Type" : "New Customer" 4} - JSON 応答の例
- 成功を示す応答を次に示します。
1{ 2 "id" : "00190000001pPvHAAU", 3 "errors" : [ ], 4 "success" : true, 5 "created": true 6}HTTP 状況コードは 201 (Created) です。
- エラー応答
- 外部 ID 項目が不正な場合は、次のような応答が返されます。
1{ 2 "message" : "The requested resource does not exist", 3 "errorCode" : "NOT_FOUND" 4} - 詳細は、「状況コードとエラー応答」を参照してください。
Id を外部 ID として使用した新規レコードの挿入
この例では、特殊なケースとして POST メソッドを使用し、Id 項目が外部 ID として処理されるレコードを挿入します。Id の値は null であるため、要求から除外されます。このパターンは、異なる外部 ID によって複数のレコードを Upsert するコードを記述していて、個別のリソースを要求したくない場合に役立ちます。Id を使用する POST は、API バージョン 37.0 以降で使用できます。
- まだ存在していないレコードを挿入する例
-
1curl https://MyDomainName.my.salesforce.com/services/data/v60.0/sobjects/Account/Id -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X POST - JSON リクエストボディ newrecord.json ファイルの例
-
1{ 2 "Name" : "California Wheat Corporation", 3 "Type" : "New Customer" 4} - JSON 応答の例
- 成功を示す応答を次に示します。
1{ 2 "id" : "001D000000Kv3g5IAB", 3 "success" : true, 4 "errors" : [ ], 5 "created": true 6}HTTP 状況コードは 201 (Created) です。
既存のレコードの Upsert
この例では、PATCH メソッドを使用して既存のレコードを更新します。外部 ID 項目「customExtIdField__c」がすでに Account に追加されていて、customExtIdField 値が 11999 の Account レコードがすでに存在すると想定します。要求では updates.json を使用して更新する項目値を指定します。
- 既存のレコードを Upsert する例
-
1curl https://MyDomainName.my.salesforce.com/services/data/v60.0/sobjects/Account/customExtIdField__c/11999 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json -X PATCH - JSON リクエストボディ updates.json ファイルの例
-
1{ 2 "BillingCity" : "San Francisco" 3} - JSON 応答の例
- API バージョン 46.0 以降では、HTTP 状況コードは 200 (OK) で、成功を示す応答は次のとおりです。
1{ 2 "id" : "001D000000Kv3g5IAB", 3 "success" : true, 4 "errors" : [ ], 5 "created": false 6}API バージョン 45.0 以前では、HTTP 状況コードは 204 (No Content) で、レスポンスボディはありません。
- エラー応答
- 外部 ID 値が一意でない場合、HTTP 状況コード 300 が返され、さらにクエリに一致したレコードのリストが返されます。エラーについての詳細は、「状況コードとエラー応答」を参照してください。
- 外部 ID 項目が存在しない場合、エラーメッセージとコードが返されます。
1{ 2 "message" : "The requested resource does not exist", 3 "errorCode" : "NOT_FOUND" 4}
レコードの Upsert と外部 ID との関連付け
オブジェクトでリレーションを使用して他のオブジェクトを参照する場合、REST API を使用し、レコードの挿入/更新の両方を行うことができ、さらに外部 ID を使用して別のオブジェクトの参照できます。
次の例では、レコードを作成し、外部 ID を介して親レコードに関連付けます。次の条件を想定します。
- Merchandise__c カスタムオブジェクトには、外部 ID 項目 MerchandiseExtID__c がある。
- Line_Item__c カスタムオブジェクトには、外部 ID 項目 LineItemExtID__c と、Merchandise__c へのリレーションがある。
- MerchandiseExtID__c 値が 123 の Merchandise__c レコードが存在する。
- LineItemExtID__c 値が 456 の Line_Item__c レコードは存在しない。これは作成され、Merchandise__c レコードに関連付けられるレコードです。
- レコードを Upsert して関連オブジェクトを参照する例
-
1curl https://MyDomainName.my.salesforce.com/services/data/v60.0/sobjects/Line_Item__c/LineItemExtID__c/456 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @new.json -X PATCH - JSON リクエストボディ new.json ファイルの例
- 関連する Merchandise__c レコードは、Merchandise__c の外部 ID 項目を使用して参照されます。
1{ 2 "Name" : "LineItemCreatedViaExtID", 3 "Merchandise__r" : 4 { 5 "MerchandiseExtID__c" : 123 6 } 7} - JSON 応答の例
- 成功を示す応答を次に示します。
1{ 2 "id" : "a02D0000006YUHrIAO", 3 "errors" : [ ], 4 "success" : true, 5 "created": true 6} -
HTTP 状況コードは 201 (Created) です。
- エラー応答
- 外部 ID 値が一意でない場合、HTTP 状況コード 300 が返され、さらにクエリに一致したレコードのリストが返されます。エラーについての詳細は、「状況コードとエラー応答」を参照してください。
- 外部 ID 項目が存在しない場合、エラーメッセージとコードが返されます。
1{ 2 "message" : "The requested resource does not exist", 3 "errorCode" : "NOT_FOUND" 4}
既存のレコードの更新には次の方法を使用することもできます。たとえば、上記の例の Line_Item__c を作成した場合、別の要求を使用して関連する Merchandise__c の更新を試みることができます。
- レコードを更新する例
-
1curl https://MyDomainName.my.salesforce.com/services/data/v60.0/sobjects/Line_Item__c/LineItemExtID__c/456 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json -X PATCH - JSON リクエストボディ updates.json ファイルの例
- ここでは、MerchandiseExtID__c 値が 333 の別の Merchandise__c レコードが存在すると想定します。
1{ 2 "Merchandise__r" : 3 { 4 "MerchandiseExtID__c" : 333 5 } 6} - JSON 応答の例
- API バージョン 46.0 以降では、HTTP 状況コードは 200 (OK) で、成功を示す応答は次のとおりです。
1{ 2 "id" : "001D000000Kv3g5IAB", 3 "success" : true, 4 "errors" : [ ], 5 "created": false 6}API バージョン 45.0 以前では、HTTP 状況コードは 204 (No Content) で、レスポンスボディはありません。