SalesforceのsObject Rows by External IDの使用例

SalesforceのExternal IDを使用するREST APIリソース

SalesforceのREST APIリソースのひとつに、sObject Rows by External IDがあります。 sObject Rows by External IDを使用すると、Salesforceの外部ID標準項目を使って、外部オブジェクトからレコードの値の取得、挿入／更新を実行することができます。

SalesforceにおけるsObject Rows by External IDの概要

sObject Rows by External IDでは、Salesforceの外部IDを使用して、レコードの新規作成もしくは既存のレコードの更新（upsert）やPATCHによる更新／挿入を実行できます。 外部IDの値により、新規レコードの作成もしくは既存レコードの更新のいずれかを判別し、実行します。指定された外部ID項目の値との一致状況に応じて以下のように処理されます。 ・1回も一致しない場合 →リクエストボディに従って新規レコードが作成されます。 ・1回だけ一致する場合 →リクエストボディに従ってレコードが更新されます。 ・複数回の一致がある場合 →300エラーが報告され、レコードの作成、更新はされません。

SalesforceにおけるsObject Rows by External IDの使用例

sObject Rows by External IDリソースで、外部IDを使用したレコードの取得およびレコードの挿入／更新（Upsert）の行う場合の方法を説明します。

Salesforce External IDの使用例①　外部IDを使用してレコードを取得する

SalesforceのsObject Rows by External IDリソースのGETメソッドを使用する方法です。指定した外部IDに関連するレコードを取得できます。ここでは、以下の想定にもとづくサンプルを紹介します。 オブジェクト：Sample__cカスタムオブジェクト 外部ID項目：SampleExtID__c

外部IDを使用してSample__cのレコードを取得するサンプル

curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Sample__c/SampleExtID__c/123 -H "Authorization: Bearer token"

レスポンスボディのサンプル

{
    "attributes" : {
        "type" : "Sample__c",
        "url" : "/services/data/v20.0/sobjects/Sample__c/a00D0000008oWP8IAM"
     },
    "Id" : "a00D0000008oWP8IAM",
    "OwnerId" : "005D0000001KyEIIA0",
    "IsDeleted" : false,
    "Name" : "Example Sample",
    "CreatedDate" : "2012-07-12T17:49:01.000+0000",
    "CreatedById" : "005D0000001KyEIIA0",
    "LastModifiedDate" : "2012-07-12T17:49:01.000+0000",
    "LastModifiedById" : "005D0000001KyEIIA0",
    "SystemModstamp" : "2012-07-12T17:49:01.000+0000",
    "Description__c" : "Merch with external ID",
    "Price__c" : 10.0,
    "Total_Inventory__c" : 100.0,
    "Distributor__c" : null,
    "SampleExtID__c" : 123.0
}

Salesforce External IDの使用例②　新規レコードを挿入／更新する（Upsert）

PATCHメソッドを使用して新規レコードを挿入する方法を説明します。ここでは、Accountに、新規レコードをUpsertするサンプルを紹介します。 外部ID項目：customExtIdField __c 現状：Accountには、customExtIdField値が12345のレコードが存在しない。

存在しない値の外部IDのレコードを挿入／更新（Upsert）するサンプル

curl services/data/v20.0/sobjects/Account/customExtIdField__c/12345 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X PATCH

JSONリクエストボディnewrecord.jsonファイルのサンプル

{
    "Name" : "Sample Corporation",
    "Type" : "New Customer"
}

処理が成功した場合のJSON応答サンプル

処理が成功した場合に、HTTP状況コード201（Created）を返すサンプルです。

{
    "id" : "00190000001pPvHAAU",
    "errors" : [ ],
    "success" : true,
    "created": true
}

処理が失敗した場合のJSON応答サンプル

外部ID項目が不正だった場合に返す、応答サンプルです。

{
    "message" : "The requested resource does not exist",
    "errorCode" : "NOT_FOUND"
}

Salesforce External IDの使用例③　既存のレコードを更新する（Upsert）

PATCHメソッドを使用して、既存のレコードを更新する方法です。更新する項目値の指定には、updates.jsonを使用します。 外部ID項目：customExtIdField __c 現状：Accountには、customExtIdField 値が12345のレコードが存在する。

外部IDの値が存在するレコードをUpsertするサンプル

curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/customExtIdField__c/11999 -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @updates.json -X PATCH

JSONリクエストボディupdates.jsonファイルのサンプル

{
    "BillingCity" : "Sample"
}

処理が成功した場合のJSON応答サンプル

SalesforceのAPIバージョン46.0以降は、成功した場合、HTTP状況コード200（OK）の応答を返します。API バージョン45.0以前ではHTTP状況コード204（No Content）で 、レスポンスボディは不要です。

{
    "id" : "001D000000Kv3g5IAB",
    "success" : true,
    "errors" : [ ],
    "created": false
}

処理が失敗した場合のJSON応答サンプル

外部ID項目の状況により、応答が変わります。 外部ID値が一意でない場合 →HTTP状況コード300の応答と一致したレコードのリストが返されます。 外部ID項目が存在しない場合 →エラーメッセージとコードを返します。

{
    "message" : "The requested resource does not exist",
    "errorCode" : "NOT_FOUND"
}

Salesforce External IDの使用例④　Idを外部IDとして使用したレコード

特殊なケースとして、Id項目が外部IDとして処理されるレコードの挿入について説明します。 POSTメソッドを使用し、nullであるIdの値により要求から除外されます。外部IDの違いによって複数のレコードをUpsertするコードを記述するため、個別のリソースを要求したくない場合に便利です。

存在しないレコードを挿入／更新（Upsert）するサンプル

curl https://yourInstance.salesforce.com/services/data/v37.0/sobjects/Account/Id -H "Authorization: Bearer token" -H "Content-Type: application/json" -d @newrecord.json -X POST

JSONリクエストボディnewrecord.jsonファイルのサンプル

{
    "Name" : "Sample",
    "Type" : "New Customer"
}

処理が成功した場合のJSON応答サンプル

処理が成功した場合、HTTP 状況コード201（Created）を返します。

{
    "id" : "001D000000Kv3g5IAB",
    "success" : true,
    "errors" : [ ],
    "created": true
}

SalesforceのsObject Rows by External IDリソースを理解しよう

SalesforceのsObject Rows by External IDについて説明しました。 sObject Rows by External IDは、Salesforceの外部オブジェクトのデータの取得や挿入／更新を実行するとき、必要なAPIです。 sObject Rows by External IDの基本的な使い方を理解しておきましょう。]]>