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

注意

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

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

基本的な更新

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

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

重要

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

注意

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

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

要求

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 要求を作成します。 この結果を取得するには、要求のヘッダーで 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 プロパティの値を削除します。

要求

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 を使用して特定のエンティティが参照されます。 違いは、エンティティが存在しない場合にエンティティが作成されることです。 すでに存在する場合は、そのエンティティが更新されます。 通常、新しいエンティティの作成時に、システムが一意の識別子を割り当てるようにすることができます。 これがベスト プラクティスです。 特定の id 値でレコードを作成する必要がある場合は、upsert がこれを行う方法を提供します。 これは、異なるシステムのデータを同期している状態で有益なことがあります。

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

基本的な削除

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

要求

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 を使用する条件付き演算を実行する