Web API を使用する条件付き演算を実行する

  • [アーティクル]

Microsoft Dataverse により、ETags として知られている標準 HTTP リソースのバージョン管理メカニズムに依存する条件付き演算のセットをサポートします。

ETag

HTTP プロトコルは、リソースの特定のバージョンを識別するために、エンティティ タグ、または省略して ETag を定義します。 ETags は不透明の識別子であるため、その正確な値は実装に依存します。 ETag 値は 2 つの種類で表示されます: 厳密と緩い検証です。 強力な検証は、特定のURIによって識別される一意のリソースが、対応するETag値が変更されていない場合、バイナリ レベルで同一であることを示します。 緩い検証は、同じ ETag の値におけるリソースの表示は、意味的に同等であることを保証するのみです。

Dataverse により、各エンティティ インスタンスに対して軽く検証する @odata.etag プロパティが生成され、このプロパティは取得した各エンティティ レコードに自動で返されます。 詳細については、Web API を使用したテーブル行の取得 を参照してください。

If-Match ヘッダーおよび If-None-Match ヘッダー

ETag値を含む If-Match ヘッダーと If-None-Match ヘッダーを使用して、リソースの現在のバージョンが最後に取得されたものと一致するか、以前のバージョンと一致するか、どのバージョンとも一致しないかを確認します。 これらの比較を行うことによって、条件付きの操作サポートのベースが作られます。 Dataverse は条件付き検索、オプティミスティック同時実行、および制限付き upsert 操作をサポートする ETags を提供します。

警告

クライアント コードは ETag の特定値に、または平等または不平等以外の ETag 間の明確な関連付けに意味を持たせることはできません。 たとえば、リソースの新バージョンの ETag 値がそれ以前のバージョンの ETag 値を超えることは保証されません。 また、新しい ETag 値を生成するのに使用されるアルゴリズムはサービスのリリース通知なしに変更する場合があります。

条件付き検索

Etags により、同じレコードに複数回アクセスするときは、いつでもレコードの検索を最大限に活用することができます。 以前にレコードを取得したことがある場合は、 If-None-Match ヘッダーとともにETag値を渡すことで、前回の取得以降に変更された場合にのみデータの取得を要求できます。 データが変更された場合、リクエストはリクエストの本文に最新のデータを含むHTTPステータス 200 OK を返します。 データが変更されていない場合は、レコードが変更されていないことを示すHTTPステータス コード 304 Not Modified が返されます。

次のメッセージペアの例は、Etag値が最後に取得されてからデータが変更されていない場合に、 accountid が 00000000-0000-0000-0000-000000000001 に等しいアカウントレコードのデータを返します。 W/"468026"

要求:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue   HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
If-None-Match: W/"468026"

応答:

HTTP/1.1 304 Not Modified  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0

以下のセクションでは、条件付き取得の使用に関する制限について説明します。

テーブルではオプティミスティック同時実行が有効になっている必要がある

次のWeb APIリクエストを使用して、テーブルで楽観的同時実行が有効になっているかどうかを確認します。 楽観的同時実行が有効になっているテーブルでは、 EntityMetadata.IsOptimisticConcurrencyEnabled プロパティが true に設定されています。

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='<Entity Logical Name>')?$select=IsOptimisticConcurrencyEnabled

クエリに $expand を含めることはできません

Etagは、取得される単一のレコードが変更されたかどうかのみを検出できます。 クエリで $expand を使用すると、より多くのレコードが返される可能性があり、それらのレコードが変更されたかどうかを検出することはできません。 クエリに $expand が含まれている場合、 304 Not Modified は返されません。

クエリに注釈を含めることはできません

Prefer: odata.include-annotations ヘッダーが GET リクエストに含まれている場合、 304 Not Modified は返されません。 注釈の値は、関連するレコードの値を参照できます。 これらのレコードは変更されている可能性があり、この変更は検出できなかったため、何も変更されていないことを示すのは誤りです。

upsert 操作の制限

通常、upsertは、レコードが存在しない場合はレコードを作成し、存在する場合は既存のレコードを更新することによって動作します。 ただし、作成または更新のいずれかを阻止するために、ETags は upserts をさらに制限するのに使用できます。

upsert での作成の阻止

データを更新していて、レコードが意図的に削除された可能性がある場合は、レコードを再作成しないでください。 これを阻止するには、If-Match ヘッダーを * の値を持つ要求に追加します。

要求:

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  
}

応答:

レコードが見つかった場合は、ステータス 204 No Content の通常の 応答 が返されます。 レコードが見つからない場合は、ステータス 404 Not Found を含む次の 応答 が返されます。

HTTP/1.1 404 Not Found  
OData-Version: 4.0  
Content-Type: application/json; odata.metadata=minimal  
  
{  
 "error": {  
  "code": "",  
  "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist"
 }  
}

upsert での更新の阻止

データを挿入する場合、同じ id 値を持つレコードがすでにシステム内に存在する可能性があり、それを更新したくない場合があります。 これを阻止するには、If-None-Match ヘッダーを 「*」 の値を持つ要求に追加します。

要求:

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-None-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  
}

応答:
レコードが見つからない場合は、ステータス 204 No Content の通常の 応答 が返されます。 レコードが見つかると、ステータス 412 Precondition Failed を含む次の 応答 が返されます。

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

オプティミスティック同時実行の適用

楽観的同時実行性を使用すると、レコードが最後に取得されてから変更されたかどうかを検出できます。 更新または削除しようとしているレコードが、取得後にサーバー上で変更されている場合は、更新または削除操作を完了しないことをお勧めします。 ここで示すパターンを適用することで、この状況を検出し、レコードの最新バージョンを取得し、必要な基準を適用して、操作を再試行するかどうかを再評価できます。

削除でのオプティミスティック同時実行の適用

00000000-0000-0000-0000-000000000001 の accountid を持つ取引先企業の以下の削除要求は、If-Match ヘッダーと共に送信される ETag 値が現在の値とは異なるので失敗します。 値が一致した場合、 204 No Content ステータスが期待されます。

要求:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
If-Match: W/"470867"  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

応答:

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." 
  }  
}

更新でのオプティミスティック同時実行の適用

00000000-0000-0000-0000-000000000001 の accountid を持つ取引先企業の以下の更新要求は、If-Match ヘッダーと共に送信される ETag 値が現在の値とは異なるので失敗します。 値が一致した場合、 204 No Content ステータスが期待されます。

要求:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
If-Match: W/"470867"  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"name":"Updated Account Name"}

応答:

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."
  }  
}

参照

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 分かかります。 個人データは収集されません (プライバシー ステートメント)。