Web API を使用したテーブル行の更新と削除

注意

エンティティとテーブルの違いがわかりませんか? Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

データを変更する操作は Web API のコア部分です。 簡単な更新と削除に加えて、単一のテーブル列 (エンティティ属性) に対して操作を実行し、upsert を作成することができます。データが存在するかどうかに応じて、データの更新または挿入を要求します。

基本的な更新

更新操作には HTTP 動詞 PATCH を使用します。 更新するプロパティが含まれる JSON オブジェクトを、レコードを表す URI に渡します。 更新が成功した場合、ステータス 204 No Content の応答が返されます。

If-Match: * ヘッダーにより、誤って upsert 操作を実行して新しいレコードを作成しないようになります。 詳細: upsert での作成の阻止

重要

エンティティを更新するとき、要求本文には変更するプロパティのみを含めます。 先に取得したエンティティのプロパティを単純に更新して、その JSON を要求に含めることにより、値が同じであっても、各プロパティが更新されます。 これにより、値が変化したことを予期するビジネス ロジックをトリガーすることができる、システム イベントを発生させます。 これにより、プロパティが実際には変更されなかったとき、監査データではプロパティが更新されたように見えます。

注意

属性の定義には、RequiredLevel プロパティが含まれます。 これが SystemRequired に設定された場合、これらの属性を NULL 値に設定することはできません。 詳細: 属性の入力要求レベル

この例は、 00000000-0000-0000-0000-000000000001 のaccountid 値で既存の取引先企業レコードを更新します。

Request

PATCH [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}  

回答

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

注意

更新時のエンティティの関連付けと関連付け解除については、単一値ナビゲーション プロパティを使用するを参照してください。

返されるデータでの更新

更新するエンティティからデータを取得するには、作成されたレコードからのデータを 200 (OK) の状態で返すよう PATCH 要求を作成します。 この結果を取得するには、Prefer: return=representation 要求ヘッダーを使用する必要があります。

どのプロパティが返されるかを制御するには、$select クエリ オプションを URL に、そしてエンティティ セットに追加します。 $expand クエリ オプションは、使用すると無視されます。

この例では、取引先企業エンティティを更新し、応答で必要なデータを返します。

要求

PATCH [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
Prefer: return=representation
If-Match: * 
  
{"name":"Updated Sample Account"}  

応答

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
Preference-Applied: return=representation  
OData-Version: 4.0  
  
{  
    "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",  
    "@odata.etag": "W/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}  
  

単一のプロパティ値の更新

単一のプロパティ値のみを更新するときは、エンティティの Uri にプロパティ名が付加された PUT 要求を使用します。

次のように、例えば、 00000000-0000-0000-0000-000000000001 のaccountid の値で既存の取引先企業エンティティの名前プロパティを更新します。

要求

PUT [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}  

応答

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

単一のプロパティ値の削除

単一のプロパティ値を削除するには、エンティティの URI にプロパティ名が付加された DELETE 要求を使用します。

次の例は、 値 00000000-0000-0000-0000-000000000001 のaccountid 値で取引先企業エンティティの description プロパティの値を削除します。

Request

DELETE [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  

回答

HTTP/1.1 204 No Content  
OData-Version: 4.0  
  

注意

これを単一値ナビゲーション プロパティに対して使用して、2 つのエンティティの関連付けを解除することはできません。 代替アプローチについては、単一値ナビゲーション プロパティとの関連付けを解除するを参照してください。

テーブル行の Upsert

upsert 操作は更新に似ています。 この操作では PATCH 要求が使用され、URI を使用して特定のレコードが参照されます。 違いは、存在しない場合にレコードが作成されることです。 すでに存在する場合は、そのエンティティが更新されます。

Upsert は、外部システム間でデータを同期するときに役立ちます。 外部システムは、Dataverse テーブルの主キーへの参照を含まないことがあるので、両方のシステムのレコードを一意に識別する外部システムからの値を使用して Dataverse テーブルの代替キーを構成することができます。 詳細情報: 行を参照する代替キーの定義

$metadata サービス ドキュメントのエンティティ タイプのコメントでテーブルに定義されている代替キーを確認することができます。 詳細: 代替キー

次の例では、sample_key1sample_key2 というどちらも整数値を格納するよう定義された 2 つの列を参照する代替キーを持ち、名前が sample_thing というテーブルがあります。

Request

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

作成および更新操作の両方で、同じ応答が得られます。 OData-EntityId 応答ヘッダーが、レコードの GUID の主キーの識別子ではなく、どのようにキー値を使用するかに注意してください。

回答

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

応答が同じであるため、操作が CreateUpdate のどちらを表しているかを知ることはできません。

知る必要がある場合、Prefer: return=representation 要求ヘッダーを使用することができます。 このヘッダーを使用すると、レコードが作成された時には 201 Created 応答が、レコードが更新された時には 200 OK 応答が得られます。 これにより、追加の Retrieve 操作が追加され、パフォーマンスに影響があります。 Prefer: return=representation 要求ヘッダーを使用する場合、$select に最小限のデータ、できれば主キー列のみが含まれるようにします。 詳細: 返されるデータで更新するおよび返されるデータで作成する

代替キーを使用する場合、要求の本文に代替キーの値を含めないでください。

  • Upsert が Update を表す場合、これらの代替キーの値は無視されます。 代替キーの値を使用してレコードを識別している間は、更新できません。
  • Upsert が Create を表す場合、本文に存在しないなら、URL のキーの値がレコードに設定されます。 したがって、要求の本文に含める必要はありません。

詳細: Upsert を使用してレコードを作成または更新

注意

通常、新しいレコードの作成時に、システムが主キーに GUID 値を割り当てるようにします。 システムはインデックス用に最適化されたキーを生成し、パフォーマンスが向上するため、これがベスト プラクティスです。 しかし、外部システムによってキーの GUID 値が生成される場合など、特定の主キー値を持つレコードを作成する必要がある場合は、upsert 操作はこれを行う方法を提供します。

Upsert による作成または更新を防ぐ

upsert を操作する場合もありますが、潜在的な操作である、作成または更新のいずれかを止める方がいいでしょう。 If-Match または If-None-Match の追加によってこれを実行できます。 詳細については、「upsert 操作の制限」を参照してください。

基本的な削除

削除操作は非常に単純です。 削除するエンティティの URI に対して、DELETE 動詞を使用します。 この例のメッセージは、00000000-0000-0000-0000-000000000001 に等しい主要キーの accountid の値を使用して取引先企業エンティティを削除します。

Request

DELETE [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  

回答

このエンティティが存在する場合は、削除に成功したことを示すステータス 204 の通常応答を受け取ります。 エンティティが存在しなかった場合は、ステータス 404 の応答を受け取ります。

HTTP/1.1 204 No Content  
OData-Version: 4.0  

重複レコードの確認

更新操作中に重複データを検出する方法の詳細については、Web API を使用した、更新操作中の重複データ検出を参照してください。

ストレージ パーティション内のドキュメントを更新および削除する

パーティションに格納されているエンティティ データを更新または削除する場合は、そのデータにアクセスするときに必ずパーティション キーを指定してください。

詳細: ストレージ パーティションを使用したテーブル データへの高速アクセス

関連項目

Web API 基本操作のサンプル (C#)
Web API 基本操作のサンプル (クライアント側の JavaScript)
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理
Web API を使用したクエリ データ
Web API を使用してテーブル行を作成する
Web API を使用してテーブルの行を取得する
Web API を使用したテーブル行の関連付けと関連付け解除
Web API 関数の使用
Web API アクションの使用
Web API を使用してバッチ操作を実行する
Web API を使用して別のユーザーを偽装する
Web API を使用する条件付き演算を実行する

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。