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

[アーティクル]
04/22/2022

注意

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

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

Web API 条件付き演算サンプル (C#)

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

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

説明

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

コードセクション	関連する概念的なトピック
条件 GET	条件付き検索
削除および更新でのオプティミスティック同時実行	オプティミスティック同時実行の適用
upsert 操作の制御	upsert 操作の制限

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

サンプルデータ

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

エンティティの種類	クライアントが割り当てたプロパティ	サーバーが割り当てたプロパティ
account	名前: `Contoso Ltd.` 売り上げ: `5000000` 電話: `555-0000` 説明: `Parent company of Contoso Pharmaceuticals, etc.`	ID: `14e151db-9b4f-e611-80e0-00155da84c08` 初期 Etag: `W/"628448"`

条件 GET

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

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

要求

GET https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1  
If-None-Match: W/"628448"  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json

応答

HTTP/1.1 304 Not Modified

コンソール出力

Instance retrieved using ETag: W/"628448"  
Expected outcome: Entity was not modified so nothing was returned.

応答値、304 Not Modified は、現在のテーブル行が最新であることを示しているため、サーバーは応答本文で要求された行を 返しません。

主な電話番号のプロパティを変更することで、取引先企業を更新します。

要求

PUT https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json  
{  
   "value": "555-0001"  
}

応答

HTTP/1.1 204 No Content

コンソール出力

Account telephone number updated.

元の ETag 値を使用してもう一度、同じ条件 GET 操作をやり直してください。今回の操作は、サーバーバージョンが要求で指定したバージョンとは異なる (および最新な) ため、要求されたデータを返します。すべてのテーブル行の取得と同様に、応答には現在のバージョンを識別する ETag ヘッダーが含まれます。

要求

GET https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1  
If-None-Match: W/"628448"  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json

応答

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
ETag: W/"628460"  
{  
   "@odata.context":"https://[Organization URI]/api/data/v9.0/$metadata#accounts(name,revenue,telephone1,description)/$entity",  
   "@odata.etag":"W/\"628460\"",  
   "name":"Contoso Ltd",  
   "revenue":5000000.0000,  
   "telephone1":"555-0001",  
   "description":"Parent company of Contoso Pharmaceuticals, etc.",  
   "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",  
   "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"  
}

コンソール出力

Instance retrieved using ETag: W/"628448"  
{  
   "@odata.context": "https://[Organization URI]/api/data/v9.0/$metadata#accounts(name,revenue,telephone1,description)/$entity",  
   "@odata.etag": "W/\"628460\"",  
   "name": "Contoso Ltd",  
   "revenue": 5000000.0,  
   "telephone1": "555-0001",  
   "description": "Parent company of Contoso Pharmaceuticals, etc.",  
   "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",  
   "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"  
}

削除および更新でのオプティミスティック同時実行

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

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

要求

DELETE https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
If-Match: W/"628448"  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json

応答

 HTTP/1.1 412 Precondition Failed  
 Content-Type: application/json; odata.metadata=minimal  
 OData-Version: 4.0  
 {  
   "error":{  
     "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . .  
     }  
 }

コンソール出力

Expected Error: The version of the existing record doesn't match the property provided.  
      Account not deleted using ETag 'W/"628448"', status code: '412'.

元の ETag 値に一致する場合にのみ、アカウントを更新し直さなくてはいけません。もう一度、この条件は If-Match ヘッダーで表され、同じ理由で操作が失敗します。

要求

 PATCH https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
 If-Match: W/"628448"  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json  
 Content-Type: application/json; charset=utf-8  
 {  
   "telephone1": "555-0002",  
   "revenue": 6000000  
 }

応答

 HTTP/1.1 412 Precondition Failed  
 Content-Type: application/json; odata.metadata=minimal  
 OData-Version: 4.0  
 {  
   "error":{  
     "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . .   
   }  
 }

コンソール出力

 Expected Error: The version of the existing record doesn't match the property provided.  
         Account not updated using ETag 'W/"628448"', status code: '412'.

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

要求

 PATCH https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
 If-Match: W/"628460"  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json  
 {  
   "telephone1": "555-0003",  
   "revenue": 6000000  
 }

回答

 HTTP/1.1 204 No Content

コンソール出力

 Account successfully updated using ETag: W/"628460", status code: '204'.

最新取引先企業の状態の取得と出力に成功した更新を確認します。これには、基本的な GET 要求を使用します。

要求

 GET https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json

応答

 HTTP/1.1 200 OK  
 Content-Type: application/json; odata.metadata=minimal  
 ETag: W/"628461"  
 OData-Version: 4.0  
 {  
   "@odata.context":"https://[Organization URI]/api/data/v9.0/$metadata#accounts(name,revenue,telephone1,description)/$entity",  
   "@odata.etag":"W/\"628461\"",  
   "name":"Contoso Ltd",  
   "revenue":6000000.0000,  
   "telephone1":"555-0003",  
   "description":"Parent company of Contoso Pharmaceuticals, etc.",  
   "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",  
   "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"  
 }

コンソール出力

 {  
   "@odata.context": "https://[Organization URI]/api/data/v9.0/$metadata#accounts(name,revenue,telephone1,description)/$entity",  
   "@odata.etag": "W/\"628461\"",  
   "name": "Contoso Ltd",  
   "revenue": 6000000.0,  
   "telephone1": "555-0003",  
   "description": "Parent company of Contoso Pharmaceuticals, etc.",  
   "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",  
   "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"  
 }

upsert 操作の制御

このセクションのプログラムでは、更新操作のみまたは挿入操作のみの制限付き upsert 操作を実行できる条件付き PATCH 操作の実行方法を示します。詳細: upsert 操作の制限

更新せずに、この取引先企業の主な電話番号と売り上げプロパティを挿入するようにしてください。 * を値に持つ If-None-Match ヘッダーは、この upsert 条件を表します。このアカウント行はサーバー上にまだ存在するため、この操作は失敗します (別のユーザーまたはプロセスによって同時に削除された場合を除く)。

要求

 PATCH https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
 If-None-Match: *  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json  
 Content-Type: application/json; charset=utf-8  
 {  
   "telephone1": "555-0004",  
   "revenue": 7500000  
 }

応答

 HTTP/1.1 412 Precondition Failed  
 Content-Type: application/json; odata.metadata=minimal  
 OData-Version: 4.0  
 {  
   "error":{  
     "code":"","message":"A record with matching key values already exists.", . . .  
   }  
 }

コンソール出力

 Expected Error: A record with matching key values already exists.  
         Account not updated using ETag 'W/"628448", status code: '412'.

作成せずに同じ更新操作を実行します。これを達成するためには、*を値に持つ条件 If-Match ヘッダーが使用されます。行がサーバー上に存在するため、この操作は成功します。

要求

 PATCH https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
 If-Match: *  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json  
 Content-Type: application/json; charset=utf-8  
 {  
   "telephone1": "555-0005",  
   "revenue": 7500000  
 }

回答

 HTTP/1.1 204 No Content

コンソール出力

 Account updated using If-Match '*'

基本の GET 要求と最新取引先企業の状態を取得して出力します。返される ETag 値は、アカウント行の新しい更新バージョンを反映するように変更されていることに注意してください。

要求

 GET https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json

回答

 HTTP/1.1 200 OK  
 Content-Type: application/json; odata.metadata=minimal  
 ETag: W/"628463"  
 OData-Version: 4.0  
 {  
   "@odata.context":"https://[Organization URI]/api/data/v9.0/$metadata#accounts(name,revenue,telephone1,description)/$entity",  
   "@odata.etag":"W/\"628463\"",  
   "name":"Contoso Ltd","revenue":7500000.0000,  
   "telephone1":"555-0005",  
   "description":"Parent company of Contoso Pharmaceuticals, etc.",  
   "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",  
   "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"  
 }

コンソール出力

 {  
   "@odata.context": "https://[Organization URI]/api/data/v9.0/$metadata#accounts(name,revenue,telephone1,description)/$entity",  
   "@odata.etag": "W/\"628463\"",  
   "name": "Contoso Ltd",  
   "revenue": 7500000.0,  
   "telephone1": "555-0005",  
   "description": "Parent company of Contoso Pharmaceuticals, etc.",  
   "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",  
   "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"  
 }

基本の DELETE と取引先企業を削除します。

要求

 DELETE https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json

応答

 HTTP/1.1 204 No Content

コンソール出力

 Account was deleted.

手順 2 と同様に、存在する場合は取引先企業を更新してください。もう一度、この条件は * を値に持つ If-Matchヘッダーで表されます。このテーブル行が削除されたばかりであるため、この操作は失敗します。しかし、この If-Match ヘッダーがない場合、結果の基本的 upsert 操作で新しい行が正常に作成されます。

要求

 PATCH https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
 If-Match: *  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json  
 Content-Type: application/json; charset=utf-8  
 {  
   "telephone1": "555-0006",  
   "revenue": 7500000  
 }

回答

 HTTP/1.1 404 Not Found  
 Content-Type: application/json; odata.metadata=minimal  
 OData-Version: 4.0  
 {  
   "error":{  
     "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .  
   }  
 }

コンソール出力

 Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.  
 Account not updated because it does not exist, status code: '404'.

手順 4 で 1 つのアカウント行がすでに削除されているため、サンプルデータをクリーンアップする必要はありません。

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

説明

サンプルデータ

条件 GET

削除および更新でのオプティミスティック同時実行

upsert 操作の制御

関連項目

フィードバック

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

説明

サンプル データ

条件 GET

削除および更新でのオプティミスティック同時実行

upsert 操作の制御

関連項目

フィードバック

サンプルデータ