機械翻訳について

5 データ整合性タスク

REST APIの呼び出し中にデータの整合性チェックを実行できます。 この機能は、データベース内のバージョン履歴を使用して、リソース自体の更新に従ってHTTPペイロードを管理できるようにします。

データ一貫性について

REST APIでは、リソース・アイテムを更新または取得するときにデータの一貫性をチェックできます。 データ整合性は、リソース・アイテムが更新または取得前にサーバー側のリソース状態と一致するように、事前条件ヘッダー付きのエンティティ・タグ(ETag)を生成することによってREST APIによって強制されます。

REST APIは、リクエストされたリソース・アイテムのデータ一貫性チェックが有効になっているときに、レスポンス・ヘッダーにエンティティ・タグ(ETag)を生成することをサポートします。

ビジュアル開発ツールがエンティティ変更インジケータをサポートする場合(たとえば、Oracle Visual Builder)では、REST APIによって、サーバー側の各リソース・アイテムの状態を示す一意の値が割り当てられます。 実行時に、サーバー側のリソース・アイテムの基礎となるビジネス・オブジェクト・アイテムが変更されると、REST APIは新しい状態値をETagに割り当てます。 次のヘッダーは、Departmentリソース・アイテムを取得するリクエストとともに返されるETagを示しています。

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Location:
Content-Length: 1069
Content-Type: application/json
ETag: "ACED00057372037200136261636C6520136261636C65237200136261636C652"
Link: <base_url>/Department/10>;rel="self";kind="item";name="Department"

Webアプリケーション・リクエストは、各リソース・アイテムのヘッダー・レスポンスで返されたETag値を使用して、前提条件ヘッダー(If-Match/If-None-Match)を含む後続のリクエストを作成できます。 指定されたETagと前提条件に基づいて、サーバーは現在のリソース・アイテム状態を評価し、提供されたETagと照合します。 事前条件が満たされた場合は、リクエストされた操作が実行され、それ以外の場合は412エラーが返されます。 エラー・ペイロードには、現在のリソース・アイテムがサーバー側に格納され、ヘッダーには現在のETag値も反映されます。

ETag値のテストをサポートするために、REST APIは次の前提条件ヘッダー・フィールドを提供します。 これらの前提条件フィールドを使用すると、REST APIは提供されたETag値と以前にリクエストされたアイテムのETag値を比較します。

  • クライアントが(前のリソース・アイテム・レスポンスから取得して)提供している状態が、サーバーの現在の状態に一致することを検証します:

    If-Match: "<ETag value from resource item response>"
    
  • クライアントが(前のリソース・アイテム・レスポンスから取得して)提供している状態が、サーバーの現在の状態に一致しないことを検証します。

    If-None-Match: "<ETag value from resource item response>"
    

データ整合性をチェックする際の一般的なユースケースは、次のとおりです:

  • 更新前にビジネス・オブジェクト・アイテムがサーバー側のリソース・アイテムの状態と一致することを確認

  • リクエストされたアイテムのどれも以前にリクエストされたアイテムと一致しない場合に、サーバー側のリソース・アイテム状態を使用してビジネス・オブジェクト・アイテムを取得

これらのユースケースではGETメソッドとPATCHメソッドが使用されますが、前提条件ヘッダーとETag値を使用して、HTTPメソッド操作がビジネス・オブジェクト・アイテムの現在の状態に適用されることを確認できます。

リソース・コレクションを取得するとき、追加のカスタム・プロパティchangeIndicatorが、リソースのレスポンス・ペイロードに表示され、データ整合性が有効になります。 このプロパティには、リクエストされたコレクション内の各リソース・アイテムの現在のETag値が含まれています。 次のサンプルは、Departmentリソース・コレクションのlinksセクションのchangeIndicatorプロパティを示しています。 リソース・コレクション・ペイロード内のETag値の存在は、個々のリソース・アイテムからETagを取得するリクエストの数を減らすことができるWebアプリケーションにとって便利です。

{
  "items" : [ {
    "DepartmentId" : 10,
    "DepartmentName" : "Administration",
    "RelState" : 1,
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/10",
      "name" : "Department",
      "kind" : "item",
      "properties" : {
        "changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C69737
        47881D21D99C7619D03000149000473697A65787000000001770400000001737200186F721
        636C652E6A626F2E646F6D61696E2E4E7564A362286F0200015B0004646174617400025B45
        27870757200025B42ACF317F8060854E00200007870"
      }
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/10",
      "name" : "Department",
      "kind" : "item",
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/10/child/Employee",
      "name" : "Employee",
      "kind" : "collection",
    } ]
  }, {
    "DepartmentId" : 20,
    "DepartmentName" : "Marketing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/20",
      "name" : "Department",
      "kind" : "item",
      "properties" : {
        "changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200186F7261636C652E6A626F2E646F6D61696E2E4E756D626572A5B1371914E0BFDA0200014900096D48617368436F6465787200116F7261636C652E73716C2E4E554D424552E90466EE632BE1D5020000787200106F7261636C652E73716C2E446174756D4078F514A362286F0200015B0004646174617400025B427870757200025B42ACF317F8060854E0020000787000000002C10A0000000078"
      }
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/20/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
      ...
    } ]
  } ],
  "count" : 5,
  "hasMore" : true,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

ビジネス・オブジェクト・アイテムを更新するときのデータ整合性のチェック

REST APIでは、リソース・アイテムの更新時にデータの一貫性をチェックできます。

ETagヘッダー・フィールドおよび条件付ヘッダー・フィールドを使用してデータ整合性をチェックする手順は、次のとおりです:

  1. 1つ以上のビジネス・オブジェクト・アイテムを問合せし、戻されたリソース・アイテムごとに、レスポンスのpropertiesセクションのchangeIndicatorプロパティからETag値を取得します。 複数のビジネス・オブジェクト・アイテムを問合せする場合、単一のETagレスポンス・ヘッダーはありません。 代わりに、レスポンス内の各アイテムのETagはpropertiesセクションにあります。

    HTTP/1.1 200 OK
    Cache-Control: no-cache, no-store, must-revalidate
    Location:
    Content-Length: 861
    Content-Type: application/json
    ETag: "responseETag123"
    Link: <<base_url>/Department/10>;rel="self";kind="item";name="Department"
    Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly
    X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad
    X-Powered-By: Servlet/2.5 JSP/2.1
     
    {
      "DepartmentId" : 10,
      "DepartmentName" : "Administration",
      "links" : [ {
        "rel" : "self",
        "href" : "<base_url>/Department/10",
        "name" : "Department",
        "kind" : "item",
        "properties" : {
          "changeIndicator" : "responseETag123"
        }
      }, {
        "rel" : "child",
        "href" : "<base_url>/Department/10/child/Employee",
        "name" : "Employee",
        "kind" : "collection"
      } ]
    }
    
  2. PATCHリクエストを使用してビジネス・オブジェクト・アイテムを更新し、次の条件付きヘッダー・フィールドを指定してデータの整合性をチェックします:

    • If-Match: " <ETag value from resource item response> "は、リクエストされたリソース・アイテムの状態が、前のリソース・アイテムのレスポンスで最新であることを確認します。

次のサンプルは、If-Match前提条件テストが満たされたときに、10部門のDepartmentNameフィールドを更新します。 最初のリクエスト(リクエスト1)では、ETag値responseETag123は、サーバー側の現在の部門10のETagと同一であり、リソース・アイテムの状態がサーバー側と一致していることを示します。 そのため、DepartmentNameへの更新が許可されます。

ただし、後続の要求(Request 2)では、If-Match前提条件で提供されたETagは変更されず、サーバーがdepartment 10リソース・アイテムに対して持っている新しいETag値ともはや一致しません。 2番目のリクエストで使用されている失効したETag値の結果として、HTTPコード412で更新が失敗し、事前条件テストが失敗したこと、および現在のETag値responseETag567がレスポンス・ヘッダーに返されます。 これは、複数のユーザーが同じビジネス・オブジェクト・アイテムに同時にアクセスする場合、本番Webアプリケーションで発生します。 たとえば、ユーザー1とユーザー2の両方が同じアイテムを問合せすると、そのアイテムは、たとえばETag値1を持ちます。 次に、ユーザー1がETag値1でアイテムを正常に更新し、ユーザー2がETag値1で同じアイテムを更新しようとすると、その試みは失敗します。

リクエスト1

  • URL 1

    <base_url>/Department/10

  • HTTPメソッド

    PATCH

  • 事前条件1

    If-Match: "responseETag123"

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ペイロード 1

    {
      "DepartmentName" : "FirstAttempt_NewDepartmentName"
    }
    

レスポンス1

  • HTTPコード

    200

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ETag

    responseETag567

  • ペイロード 1

    {
        "DepartmentId" : 10,
        "DepartmentName" : "FirstAttempt_NewDepartmentName",
        "RelState" : null,
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Department/10",
          "name" : "Department",
          "kind" : "item",
          "properties" : {
            "changeIndicator" : "responseETag567"
          }
        }, {
          "rel" : "child",
          "href" : "<base_url>/Department/10/child/Employee",
          "name" : "Employee",
          "kind" : "collection"
        } ]
    }
    

リクエスト2

  • URL 2

    <base_url>/Department/10

  • HTTPメソッド

    PATCH

  • 事前条件2

    If-Match: "staleETag789"

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ペイロード 2

    {
      "DepartmentName" : "SecondAttempt_NewDepartmentName"
    }
    

レスポンス2

  • HTTPコード

    412 (事前条件は失敗しました)

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ETag

    responseETag567

  • ペイロード 2

    {
        "DepartmentId" : 10,
        "DepartmentName" : "FirstAttempt_NewDepartmentName",
        "RelState" : null,
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Department/10",
          "name" : "Department",
          "kind" : "item",
          "properties" : {
            "changeIndicator" : "responseETag567"
          }
        }, {
          "rel" : "child",
          "href" : "<base_url>/Department/10/child/Employee",
          "name" : "Employee",
          "kind" : "collection"
        } ]
    }

ビジネス・オブジェクト・アイテムの取得時のデータ整合性の確認

REST APIでは、リソース・アイテムを取得するときにデータの一貫性をチェックできます。

ETagヘッダー・フィールドおよび条件付ヘッダー・フィールドを使用してデータ整合性をチェックする手順は、次のとおりです:

  1. 1つ以上のビジネス・オブジェクト・アイテムを問合せし、戻されたリソース・アイテムごとに、レスポンスのpropertiesセクションのchangeIndicatorプロパティからETag値を取得します。 複数のビジネス・オブジェクト・アイテムを問合せする場合、単一のETagレスポンス・ヘッダーはありません。 代わりに、レスポンス内の各アイテムのETagはpropertiesセクションにあります。

    HTTP/1.1 200 OK
    Cache-Control: no-cache, no-store, must-revalidate
    Location:
    Content-Length: 861
    Content-Type: application/json
    ETag: "responseETag123"
    Link: <base_url>/Department/10>;rel="self";kind="item";name="Department"
    Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly
    X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad
    X-Powered-By: Servlet/2.5 JSP/2.1
     
    {
      "DepartmentId" : 10,
      "DepartmentName" : "Administration",
      "links" : [ {
        "rel" : "self",
        "href" : "<base_url>/Department/10",
        "name" : "Department",
        "kind" : "item",
        "properties" : {
          "changeIndicator" : "responseETag123"
        }
      }, {
        "rel" : "child",
        "href" : "<base_url>/Department/10/child/Employee",
        "name" : "Employee",
        "kind" : "collection"
      } ]
    }
    
  2. 1つ以上のビジネス・オブジェクト・アイテムを問合せし、以下の条件付きヘッダー・フィールドを指定してデータの一貫性をチェックします:

    • If-None-Match: " <ETag value from resource item response> "以前にリクエストされたいずれのリソース・アイテムも、リソース・アイテム・リクエストを含んでいない状態であることを確認します。

次のサンプルは、If-None-Match前提条件テストが満たされたときに部門10を取得します。 最初の要求(Request 1)では、ETag値responseETag123が、サーバー側の以前に要求されたDepartment 10リソース・アイテムのETagと一致し、リソース・アイテムの状態がサーバー側と一致していることを示します。 したがって、前提条件は失敗し、新しい部門の10リソース・アイテムを返す必要はありません。 リクエストはHTTPコード304を返し、サーバー上の状態が変更されていないことを示します。

ただし、後続のリクエスト(リクエスト2)では、If-None-Match事前条件で指定されているETag unmatchedETagXYZがサーバーに存在しません。 結果として、前提条件が成功し、部門10が検索されます。 リクエストはHTTPコード200を返し、状態が変更されたことを示します。また、現在の(変更されていない)ETag値responseETag123がレスポンス・ヘッダーに返されます。

リクエスト1

  • URL 1

    <base_url>/Department/10

  • HTTPメソッド

    GET

  • 事前条件1

    If-None-Match: "responseETag123"

  • Content-Type

    none

  • ペイロード

    none

レスポンス1

  • HTTPコード

    304状態は変更されていません

  • Content-Type

    none

  • ペイロード 1

    none

リクエスト2

  • URL 2

    <base_url>/Department/10

  • HTTPメソッド

    GET

  • 事前条件2

    If-None-Match: "unmatchedETagXYZ"

  • Content-Type

    none

  • ペイロード

    none

レスポンス2

  • HTTPコード

    200

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ETag

    responseETag123

  • ペイロード 2

    {
        "DepartmentId" : 10,
        "DepartmentName" : "Administration",
        "RelState" : null,
        "links" : [ {
          "rel" : "self",
          "href" : "<base_url>/Department/10",
          "name" : "Department",
          "kind" : "item",
          "properties" : {
            "changeIndicator" : "responseETag123"
          }
        }, {
          "rel" : "child",
          "href" : "<base_url>/Department/10/child/Employee",
          "name" : "Employee",
          "kind" : "collection"
        } ]
    }