Web API の条件付き操作のサンプル

このサンプルのコレクションでは、Microsoft Dataverse サーバーに含まれているテーブル行のバージョンに基づいて、または現在クライアントによって管理されている操作を条件付きで実行する方法を示します。詳細については、「 Web API を使用した条件付き操作の実行」を参照してください。このサンプルは、次の言語に対する別個のプロジェクトとして実装されます。

Dataverse Web API は、ETag を使用してリソースのバージョン管理を実装する OData v4.0 プロトコルの規則に従います。 Web API の条件付き操作は、このバージョン管理メカニズムによって異なります。

この記事では、より高い言語に依存しないレベルでのサンプルの構造と内容について説明します。 HTTP 要求と応答、および関連するプログラム出力 (該当する場合) について詳しく説明します。リンクされたサンプル記事を確認して、言語固有の実装と、この記事で説明されている操作の実行方法に関する関連する詳細を取得します。

対象

このサンプルは、次の表に示す 3 つの主要なセクションに分かれています。各セクションには、関連する Web API 操作のセットが含まれています。これについては、 Web API を使用した条件付き操作の実行に関する記事の関連する概念セクションで詳しく説明します。

コードセクション	関連する概念に関する記事
セクション 0: サンプルレコードを作成する	Web API を使用してテーブル行を作成する
セクション 1: 条件付き GET	条件付き取得
セクション 2: 削除と更新に関するオプティミスティックコンカレンシー	オプティミスティックコンカレンシーを適用するアップサート操作を制限する
セクション 3: サンプルレコードを削除する	基本的な削除 Web API を使用してバッチ操作を実行する

次のセクションでは、実行された Dataverse Web API 操作、対応する HTTP メッセージ、および言語実装ごとに同じ関連するコンソール出力について簡単に説明します。簡潔にするために、関連の少ない HTTP ヘッダーは省略されます。テーブル行の URI は、基本組織のアドレスと、Dataverse サーバーによって割り当てられた行の ID によって異なります。

セクション 0: サンプルレコードを作成する

このサンプルでは、プリンシパルコードセクションが実行される前に、次のテーブル行が作成されます。

要求:

POST [Organization Uri]/api/data/v9.2/accounts?$select=name,revenue,telephone1,description HTTP/1.1
Prefer: return=representation
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "name": "Contoso Ltd",
  "telephone1": "555-0000",
  "revenue": 5000000,
  "description": "Parent company of Contoso Pharmaceuticals, etc."
}

応答：

HTTP/1.1 201 Created
Preference-Applied: return=representation
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

コンソール出力:

Created and retrieved the initial account, shown below:
{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

セクション 1: 条件付き GET

プログラムのこのセクションでは、クライアントの最新の行状態を維持しながら、ネットワーク帯域幅とサーバー処理を最適化するために条件付き取得を実行する方法を示します。詳細: 条件付き検索

アカウント Contoso Ltd. の取得を試行するのは、アカウント行の作成時に返された最初の ETag 値によって識別される現在のバージョンと一致 しない 場合のみです。この条件は、 If-None-Match ヘッダーによって表されます。

要求:
```
GET [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
```
応答：
```
HTTP/1.1 304 NotModified
```
コンソール出力:
```
Account record retrieved using ETag: W/"72965013"
Expected outcome: Entity was not modified so nothing was returned.
```
応答値 304 NotModifiedは、現在のテーブル行が最新であることを示します。そのため、サーバーは応答本文で要求された行を返 しません 。

プライマリ電話番号プロパティを変更して、アカウントを更新します。

要求:

PUT [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{"value": "555-0001"}

応答：

HTTP/1.1 204 NoContent
OData-Version: 4.0

コンソール出力:

Modified account record retrieved using ETag: W/"72965013"

元の ETag 値を使用して、同じ条件付き GET 操作を再試行します。今回は、サーバー上のバージョンが要求で識別されたバージョンとは異なる (以降) ため、操作は要求されたデータを返します。すべてのテーブル行の取得と同様に、応答には、現在のバージョンを識別する ETag ヘッダーが含まれます。

要求:

GET [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

応答：

HTTP/1.1 200 OK
ETag: W/"72965025"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

コンソール出力:

Modified account record retrieved using ETag: W/"72965013"
Notice the updated ETag value and telephone number
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

セクション 2: 削除と更新に関するオプティミスティックコンカレンシー

プログラムのこのセクションでは、条件付き削除操作と更新操作を実行する方法について説明します。このような操作の最も一般的な用途は、マルチユーザー環境で行処理にオプティミスティックコンカレンシーアプローチを実装することです。詳細情報: 楽観的並行性の適用

元のアカウントが元のバージョン (ETag 値) と一致する場合にのみ、元のアカウントの削除を試みます。 If-Match ヘッダーはこの条件を表します。前のセクションでアカウント行が更新されたため、この操作は失敗するため、サーバー上でそのバージョンが更新されました。

要求:

DELETE [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答：

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

コンソール出力:

Attempting to delete the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not deleted using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

元の ETag 値と一致する場合にのみ、アカウントの更新を試みます。ここでも、この条件は If-Match ヘッダーによって表され、同じ理由で操作が失敗します。

要求:

PATCH [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0002",
"revenue": 6000000
}

応答：

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

コンソール出力:

Attempting to update the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not updated using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

更新を再試行しますが、代わりに前のセクションの最後の行の取得から取得した現在の ETag 値を使用します。

要求:

PATCH [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965025"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0003",
"revenue": 6000000
}

応答：

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

コンソール出力:

Attempting to update the account using the current ETag value

Account successfully updated using ETag: W/"72965025".

GET要求を使用して現在のアカウントの状態を取得して出力することで、更新が成功したことを確認します。

要求:

GET [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答：

HTTP/1.1 200 OK
ETag: W/"72965035"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

コンソール出力:

Below is the final state of the account
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

セクション 3: サンプルレコードを削除する

このセクションでは、「セクション 0: サンプルレコードの作成」で作成したレコードを削除するだけです。 $batch要求を使用します。

要求:

POST [Organization Uri]/api/data/v9.2/$batch HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

--batch_98e0fdc2-a298-4f42-85a8-da0536140b78
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-Length: 115

DELETE /api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1


--batch_98e0fdc2-a298-4f42-85a8-da0536140b78--

応答：

HTTP/1.1 200 OK
OData-Version: 4.0

--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
OData-Version: 4.0


--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb--

コンソール出力:

Deleting created records.

こちらも参照ください

Dataverse Web API を使用する
 Web API を使用して条件付き操作を実行する
 Web API の条件付き操作のサンプル (C#)
Web API の条件付き操作のサンプル (クライアント側 JavaScript)

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-04

次の方法で共有

Web API の条件付き操作のサンプル

対象

セクション 0: サンプル レコードを作成する

セクション 1: 条件付き GET

セクション 2: 削除と更新に関するオプティミスティック コンカレンシー

セクション 3: サンプル レコードを削除する

こちらも参照ください

フィードバック

その他のリソース

セクション 0: サンプルレコードを作成する

セクション 2: 削除と更新に関するオプティミスティックコンカレンシー

セクション 3: サンプルレコードを削除する