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

  • [アーティクル]

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

基本的な更新

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

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

重要

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

statecode プロパティを更新するときは、常に目的の statuscode を設定することが重要です。 statecode と statuscode には従属値があります。 特定の statecode 値に対して複数の有効な statuscode 値がある可能性がありますが、各 statecode 列には 1 つの DefaultStatus 値が設定されています。 statuscode を指定せずに statecode を更新すると、デフォルトのステータス値がシステムによって設定されます。 また、テーブルと statuscode 列で監査が有効になっている場合、更新操作で指定しない限り、statuscode 列の変更された値は監査データに取り込まれません。

注意

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

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

要求:

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 要求ヘッダーを使用する必要があります。

どのプロパティが返されるかを制御するには、$select クエリ オプションを URL に、そしてエンティティ セットに追加します。 $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 アクション を使用することです。 UpdateMultiple アクション の作成時点。 すべての標準テーブルがこのアクションをサポートしているわけではありませんが、すべてのエラスティック テーブルはサポートしています。

詳細情報:

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

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

次のように、例えば、 00000000-0000-0000-0000-000000000001 の accountid の値で既存の account 行の name プロパティを更新します。

要求:

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

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

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

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

要求:

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

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

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

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

次の例では、sample_thing という名前のテーブルがあり、そのテーブルには 2 つの列 sample_key1 と 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 に最小限のデータ、できれば主キー列のみが含まれるようにします。 詳細: 返されるデータで更新するおよび返されるデータで作成する。

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

  • 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 の値を使用して取引先企業エンティティを削除します。

要求:

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 アクションはプレビュー機能です。 標準テーブルはこのアクションをサポートしませんが、すべてのエラスティック テーブルはサポートしています。

注意

標準テーブルの場合は、クエリに一致するレコードの非同期削除を可能にする SDK 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 を使用する条件付き演算を実行する

注意

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

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