OCAPI リソースの状態 23.1

リソースの状態は、買い物カゴや顧客といった特定のリソースのサーバー側の状態を表します。これは、すべてのリソースプロパティ情報上で作成される文字列トークンです。

OCAPI は、_resource_state を使用して、リソースの状態の情報をレスポンスペイロード (ボディ) に表示します。レスポンスには、1 つのリソースの状態が含まれるか、あるいはコレクションや検索のリソースを呼び出す場合は複数のリソースの状態が含まれます。ボディのないレスポンス (HEAD など) の場合は、リソースの状態は x-dw-resource-state レスポンスヘッダーによって表示されます。

リソースの状態は、クライアントに楽観的ロック を実装するためのオプションのメカニズムを提供します。"失われた更新" の問題を解決するなど、同時実行リクエスト間での競合を防ぐために使用できます。

強い Etag はサーバー側のリソース状態だけではなく、ビットレベルで HTTP レスポンス全体を対象とします。つまり、圧縮 (gzip など) が使用されるかどうかも対象とします。プロキシが中間にあるシナリオでは、これによって予期しない動作が引き起こされる可能性があります。たとえば、クライアントが圧縮をリクエストしていないにもかかわらず、プロキシとサーバー間で圧縮が行われた場合、Etag 値に "-gzip" を付加するプロキシと、Etag を完全に吸収するプロキシが発生します。

OCAPI は用語 "resource_state" を使用して、その概念を Etag と明確に区別しています。OCAPI は現在 Etag をサポートしていません。

楽観的ロックにリソースの状態を使用するには、次回の状態変更 (DELETE、PATCH、POST、PUT) リクエストに、最後のサーバーレスポンスからのリソース状態を含める必要があります。ボディには常に _resource_state プロパティを使用するようにします。リクエストした API にボディがない場合は、x-dw-resource-state ヘッダーを使用します。リソースの状態がクライアントのリクエストの一部である場合は常に、OCAPI は指定された値をサーバーのリソース状態と比較して、検証します。両方のリソースの状態が等しい場合、操作は実行されます。等しくない場合は、HTTP 409 ResourceStateConflictException フォールトが返されます。(PUT を使用する場合など) リクエスト作成で (not_exists 状態を使用して) リソースが存在する必要がない場合、返されるフォールトは HTTP 409 ResourceAlreadyExistsException です。

お使いのアプリケーションで状態変更 (DELETE、PATCH、POST、PUT) 操作の実行時に同時実行リクエストの可能性がある場合、リソースの状態を基にした楽観的ロックの使用をお勧めします。

OCAPI は、リソースの状態をレスポンスボディで _resource_state プロパティとして、および x-dw-resource-state ヘッダーとして表示します。

リソースの状態は、いずれかの状態変更メソッド (DELETE、PATCH、POST、PUT) に渡すことができます。リソースの状態が渡されないと、リソースは、デフォルトの HTTP メソッド動作に基づいて通知なしに上書き、更新、または削除されます。リソースの状態が渡されると、サーバーのリソースの状態に照らし合わせて検証されます。両方の状態が一致しない場合、ResourceStateConflictException または ResourceAlreadyExistsException フォールトが返されます。API ユーザーがリソースの存在を必要としない場合 (リソース作成時など)、リソースの状態 not_exists を渡すことができます。これにより、既存のリソースが間違って上書きされることのないようにします。

リソース上での書き込み操作では、リソース状態トークンを渡せますが、必須ではありません。トークンが渡されないと、リソースは通知なしに上書き、更新、削除されます。リソースの状態が渡されると、リソースのサーバー状態に照らし合わせて確認されます。両方の状態が一致しない場合、409 ステータスコードが取得されます。API ユーザーがリソースの存在を必要としない場合、リソースの状態 not_exists を渡す必要があります (リクエストの作成の場合)。