Web API 条件付き演算サンプル

[アーティクル]
08/24/2023

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

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

このトピックは、より高度でニュートラル言語レベルの構造と内容の例を説明します。適応可能な HTTP 要求と応答、また関連するプログラム出力について説明しています。このトピックに説明されている操作を実行する方法に関する言語固有の実装および関連する詳細の取得については、上記のリンクされたサンプルトピックを確認してください。

説明

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

コードセクション	関連する概念的なトピック
セクション 0: サンプルレコードを作成する	Web API を使用してテーブル行を作成する
セクション 1: 条件 GET	条件付き検索
セクション 2: 削除および更新でのオプティミスティック同時実行	オプティミスティック同時実行の適用 upsert 操作の制限
セクション 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": "59d88f5e-6629-ed11-9db1-0022482746b6",
  "_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": "59d88f5e-6629-ed11-9db1-0022482746b6",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

セクション 1: 条件 GET

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

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

要求:
```
GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$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(59d88f5e-6629-ed11-9db1-0022482746b6)/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(59d88f5e-6629-ed11-9db1-0022482746b6)?$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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

セクション 2: 削除および更新でのオプティミスティック同時実行

このセクションのプログラムでは、条件付きの削除および更新処理の実行方法を示します。このような操作の最も一般的な使用法は、マルチユーザー環境での行処理へのオプティミスティック同時実行アプローチの実装です。詳細: オプティミスティック同時実行の適用

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

要求:

DELETE [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) 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(59d88f5e-6629-ed11-9db1-0022482746b6) 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(59d88f5e-6629-ed11-9db1-0022482746b6) 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(59d88f5e-6629-ed11-9db1-0022482746b6)

コンソール出力

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(59d88f5e-6629-ed11-9db1-0022482746b6)?$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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_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(59d88f5e-6629-ed11-9db1-0022482746b6) 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)

注意

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

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

Web API 条件付き演算サンプル

説明

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

セクション 1: 条件 GET

セクション 2: 削除および更新でのオプティミスティック同時実行

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

参照

フィードバック

その他のリソース

Web API 条件付き演算サンプル

説明

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

セクション 1: 条件 GET

セクション 2: 削除および更新でのオプティミスティック同時実行

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

参照

フィードバック

その他のリソース

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

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