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

sObject Rows by External ID

指定された外部 ID 項目の値に基づいて、新しいレコードを作成するか、既存のレコードを更新 (レコードを Upsert) します。PATCH を使用して外部 ID を使用して更新/挿入します。更新/挿入では、外部 ID の値を使用して、新規レコードを作成するか、既存レコードを更新するかを判別します。

外部 ID が一致しない場合は、リクエストボディに従って新規レコードが作成されます。
外部 ID が一度だけ一致する場合は、リクエストボディに従ってレコードが更新されます。
外部 ID が複数回一致する場合は、300 エラーが報告され、レコードは作成も更新もされません。

リクエストボディに ID または外部 ID 項目を指定してはいけません。指定すると、エラーが発生します。

メモ

セキュリティ上の理由で、一部のトップレベルドメイン (TLD) は特定のファイル形式拡張子と競合する場合があります。実装を調整して、そのようなケースを回避してください。たとえば、メールアドレスが要求 URL の外部 ID として使用されていて、TLD ".inc" が項目値の一部として使用されている場合、その要求では「404 not found」エラーが返されます。

次に例を示します。

「404 not found」が返されます。

1GET /services/data/v52.0/sobjects/Lead/Email/example@email.inc

回避策:

別の外部 ID 項目を使用します。
メール項目と同じ新しい外部 ID 項目を作成し、このケースに対応するために「.」を「_」に置き換えます。
「.inc」で終わるメールに対してクエリを実行し、レコード ID を取得してそれを upsert (更新/挿入) に使用します。
upsert 操作に REST API の代わりに SOAP API を使用します。
カスタム Apex REST API を作成して、メールをパスパラメータでなくクエリパラメータとして受け入れます。Apex を使用して、upsert 操作を実行します。

メモ

URI

/services/data/vXX.X/sobjects/sObject/fieldName/fieldValue

形式

JSON、XML

HTTP メソッド

HEAD、GET、PATCH、DELETE、POST (「使用方法」セクションを参照)

認証

Authorization: Bearer token

パラメータ

なし

使用方法

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

特殊なケースとして、API バージョン 37.0 以降では、/vXX.X/sobjects/sObjectName/Id に対する POST 要求を使用してレコードを作成できます。Id の値が null であるため、要求から除かれ、リクエストボディに従ってレコードが作成されます。このメソッドを使用したレコードの更新/挿入では各新規レコードに各 POST 要求の同じリソースを使用できるため、便利です。この場合、レコードを作成するために外部 ID を指定する必要はありません。

例

外部 ID に基づいてレコードを取得する例は、「外部 ID を使用してレコードを取得する」を参照してください。
外部 ID に基づいてレコードを作成および更新する例は、「外部 ID を使用してレコードを挿入/更新 (Upsert) する」を参照してください。

REST API 開発者ガイド

sObject Rows by External ID