データを変更する操作は、Web API の中核となる部分です。 単純な更新操作と削除操作に加えて、1 つのテーブル列 (エンティティ属性) に対して操作を実行し、存在するかどうかに応じてデータを更新または挿入する アップサート 要求を作成できます。
基本的な更新
更新操作では、HTTP PATCH 動詞を使用します。 更新するプロパティを含む JSON オブジェクトを、レコードを表す URI に渡します。 更新が成功した場合、応答は 204 No Contentの状態を返します。
If-Match: * ヘッダーを使用すると、誤ってアップサート操作を実行して新しいレコードを作成しないようにします。 詳細については、「 アップサートでの作成を禁止する」を参照してください。
Important
エンティティを更新する場合は、変更するプロパティのみを要求本文に含めます。 以前に取得したエンティティのすべてのプロパティを含めてエンティティを更新すると、値が同じ場合でも各プロパティが更新されます。 この更新により、値が変更されたことを予期するビジネス ロジックをトリガーするシステム イベントが発生する可能性があります。 実際に変更されなかった場合、監査データでプロパティが更新されたように見える可能性があります。
statecode プロパティを更新するときは、常に目的のstatuscodeを設定します。
statecodeとstatuscodeの値は互いに異なります。 特定の statecode 値に対して、複数の有効な statuscode 値を指定できます。 ただし、各 statecode 列には、1 つの DefaultStatus 値が構成されています。
statecodeを指定せずにstatuscodeを更新すると、システムによって既定のステータス値が設定されます。 また、テーブルと statuscode 列の監査を有効にした場合、更新操作で指定しない限り、 statuscode 列の変更された値は監査データにキャプチャされません。
注
属性の定義には、 RequiredLevel プロパティが含まれています。 このプロパティが SystemRequired に設定されている場合、これらの属性を null 値に設定することはできません。 詳細については、「 属性要件レベル」を参照してください。
次の使用例は、 accountid 値が 000000000-0000-0000-0000-000000000001 の既存の取引先企業レコードを更新します。
要求:
PATCH [Organization URI]/api/data/v9.2/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 要求ヘッダーを使用します。
返されるプロパティを制御するには、エンティティ セットの URL に $select クエリ オプションを追加します。
$expand クエリ オプションは、使用されている場合は無視されます。
次の使用例は、アカウント エンティティを更新し、要求されたデータを応答で返します。
要求:
PATCH [Organization URI]/api/data/v9.2/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.2/$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"
}
1 つの要求で複数のレコードを更新する
1 つの要求で同じ種類の複数のレコードを更新する最も高速な方法は、 UpdateMultiple アクションを使用することです。 すべての標準テーブルがこのアクションをサポートしているわけではありませんが、すべてのエラスティック テーブルはサポートしています。
詳細情報:
1 つのプロパティ値を更新する
1 つのプロパティ値を更新するには、 PUT 要求を使用し、エンティティの Uri にプロパティ名を追加します。
次の例では、既存のname行のaccount プロパティを accountid の00000000-0000-0000-0000-000000000001値で更新します。
要求:
PUT [Organization URI]/api/data/v9.2/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
1 つのプロパティ値を削除する
1 つのプロパティの値を削除するには、エンティティの URI にプロパティ名が追加された DELETE 要求を使用します。
次の例では、descriptionのaccountid値を持つアカウント エンティティの00000000-0000-0000-0000-000000000001 プロパティの値を削除します。
要求:
DELETE [Organization URI]/api/data/v9.2/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
アップサート操作は更新に似ています。
PATCH要求を使用し、URI を使用して特定のレコードを参照します。 違いは、レコードが存在しない場合は作成されるということです。 既に存在する場合は更新されます。
Upsert は、外部システム間でデータを同期する場合に重要です。 外部システムには Dataverse テーブルの主キーへの参照が含まれていない可能性があるため、両方のシステムでレコードを一意に識別する外部システムの値を使用して、Dataverse テーブルの代替キーを構成できます。 詳細情報: 行を参照する代替キーの定義
テーブルに対して定義されている代替キーは、$metadata サービス ドキュメントのエンティティ型の注釈で確認できます。 詳細情報: 代替キー。
次の例では、sample_thingとsample_key1の 2 つの列を参照する代替キーを持つ名前sample_key2を持つテーブルがあります。このテーブルは、両方とも整数値を格納するために定義されています。
要求:
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)
応答は同じであるため、操作が Create 操作と Update 操作のどちらを表したかはわかりません。
知る必要がある場合は、 Prefer: return=representation 要求ヘッダーを使用できます。 このヘッダーを使用すると、レコードの作成時に 201 Created 応答を取得し、レコードが更新されたときに 200 OK 応答を取得します。 このオプションは、パフォーマンスに影響を与える Retrieve 操作を追加します。
Prefer: return=representation要求ヘッダーを使用する場合は、$selectに最小限のデータ量 (できれば主キー列のみ) が含まれていることを確認します。 詳細情報: 返されたデータを使用して更新し、返されたデータを使用して作成します。
代替キーを使用する場合は、要求の本文に代替キーの値を含めないでください。
- アップサートが
Updateを表す場合、これらの代替キー値は無視されます。 代替キー値を使用してレコードを識別している間は更新できません。 - upsertが
Createを表す場合、URL 内のキー値が本文に存在しない場合は、そのキー値がレコードに設定されます。 そのため、要求の本文に含める必要はありません。
詳細情報: Upsert を使用してレコードを作成または更新する
注
通常、新しいレコードを作成するときに、システムに主キーの GUID 値を割り当てることができます。 この方法が最適なのは、インデックス用に最適化されたキーがシステムによって生成され、この選択によってパフォーマンスが向上するためです。 ただし、外部システムによってキー GUID 値が生成された場合など、特定の主キー値を持つレコードを作成する必要がある場合は、 upsert 操作でこれを行うことができます。
upsert を使用した作成または更新を禁止する
場合によっては、 upsert を実行するが、作成または更新のいずれかの操作を回避したい場合があります。 これらの操作は、 If-Match または If-None-Match ヘッダーを使用して回避できます。 詳細については、「 アップサート操作の制限」を参照してください。
基本的な削除
削除操作は簡単です。 削除するエンティティの URI で DELETE 動詞を使用します。 このメッセージ例では、主キー accountid 値が 00000000-0000-0000-0000-000000000001と等しいアカウント エンティティを削除します。
要求:
DELETE [Organization URI]/api/data/v9.2/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 を使用した更新操作中の重複の検出」を参照してください。
1 つの要求で複数のレコードを削除する
1 つの要求で同じ種類の複数のレコードを削除するには、 DeleteMultiple アクションを使用します。 標準テーブルでは、この DeleteMultiple アクションはサポートされていませんが、すべてのエラスティック テーブルでサポートされます。
注
標準テーブルの場合は、 BulkDelete アクションを使用します。 このアクションにより、クエリに一致するレコードを非同期で削除できます。 詳細については、「データを 一括で削除する」を参照してください。
詳細情報:
ストレージ パーティション内のドキュメントを更新および削除する
パーティションに格納されているエラスティック テーブル データを更新または削除する場合は、そのデータにアクセスするときにパーティション キーを指定します。
詳細: PartitionId 値の選択
こちらも参照ください
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 を使用して条件付き操作を実行する