Oracle Fusion Cloud ProcurementのREST API

ETag値を使用したリソース更新の確認

リソースに対する変更の検証は、RESTクライアントにとって時間がかかり、帯域幅に負荷がかかるタスクである可能性があります。処理時間とペイロード・サイズを節約するには、エンティティ・タグ(ETag)を使用して、クライアントとともに格納されたリソースを条件付きで取得し、変更がないかどうかを確認します。 ETagは、httpレスポンス・ヘッダーとして確認できます。

ETag値は、If-None-MatchまたはIf-Match条件付きリクエスト・ヘッダーとともに使用して、ステータスを取得できます。 If-None-Matchヘッダーは、通常、リソースに対する変更を検証するためにGETリクエストとともに使用されます。 If-Matchヘッダーは、最後のGETリクエストが送信された時点以降にリソースに変更がないと仮定して、リソースを更新するPATCHリクエストとともに使用されます。

次の表に、これらのヘッダーでETag値を使用した場合に予想される様々なレスポンスを示します。

表 - ETag値

HTTPメソッド	HTTPリクエスト・ヘッダー	リソース変更済	リソースは変更されていません
GET	If-None-Match	ステータス: 200 OK リクエストされたリソースが変更され、リクエストされたリソースが返されたことを示す200が返されます。更新された情報はレスポンス本文に表示されます。	ステータス: 304未変更リクエストされたリソースが変更されていないことを示す304が返されます。レスポンス本文に空のレスポンスが返されます。
PATCH	If-Match	ステータス: 412事前条件に失敗しましたリクエストが失敗しました。	ステータス: 200 OK リクエストが処理され、更新された情報がレスポンス本文に表示されます。

HTTPメソッド

HTTPリクエスト・ヘッダー

リソース変更済

リソースは変更されていません

GET

If-None-Match

ステータス: 200 OK

リクエストされたリソースが変更され、リクエストされたリソースが返されたことを示す200が返されます。

更新された情報はレスポンス本文に表示されます。

ステータス: 304未変更

リクエストされたリソースが変更されていないことを示す304が返されます。

レスポンス本文に空のレスポンスが返されます。

PATCH

If-Match

ステータス: 412事前条件に失敗しました

リクエストが失敗しました。

ステータス: 200 OK

リクエストが処理され、更新された情報がレスポンス本文に表示されます。

ノート:

If-None-MatchヘッダーとIf-Matchヘッダーは、単一のリソースに対してのみ使用できます。

レスポンス本文のETagヘッダーの位置は、RESTフレームワークのバージョンによって異なる場合があります。フレームワーク・バージョン6以上を使用している場合は、レスポンスの@contextセクションにETagがあります。詳細は、トピック「RESTフレームワーク・バージョンの設定」を参照してください

次に、ETag値を取得し、その値を後続のリクエストで使用して、新しいコンテンツを取得するか、リソースを更新する方法について説明します。

GETリクエストを送信して、ETag値を取得します。単一のリソースに対するGET操作の場合、httpリクエスト・レスポンス・ヘッダーとレスポンス本文の両方にETagが表示されます。

この例では、単一のリソースに対するGETリクエストを使用して、ETag値を取得しようとしています。

リクエスト

GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005

レスポンス

レスポンス本文のETag値は、リソースに変更があるかどうかを検証するために、次のステップで使用されます。

"DisplayName": "Erin Mack",
"@context": {
        "key": "180511",
        "headers": {
          "ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000478"
        },
  "links": [
    {
      "rel": "self",
      "href": "https://<host>:<port>/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/ ",
      "name": "names",
      "kind": "item",
      "properties": {
      }
    }
  ]
}

この例では、コレクション・リソースに対するGETリクエストを使用してETag値を取得しようとしています。

リクエスト

GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005

レスポンス

{
  "items": [
   {
     "DisplayName": "Erin Mack",
     "@context": {
        "key": "180511",
        "headers": {
          "ETag": FCED00057372000000014770400000014737A76612E6C616E672E4"
        },
  "links": [
    {
      "rel": "self",
      "href": "https://<host>:<port>/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/ ",
      "name": "names",
      "kind": "item",
      "properties": {
      }
    }
  ]
}

ノート:

レスポンス本文では、各リソース品目に、個別のリクエストを使用して特定のリソースを検証および更新するために使用できる独自のETag値があることがわかります。

後続のリクエストでETag値を使用して、既存の更新またはリソースの更新を確認します。
- ETagの値とIf-None-Matchヘッダーを使用してGETリクエストを送信し、リソースが変更された場合に新しいコンテンツを取得します。
  リクエスト
```
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000000005
If-None-Match: "<etag_value>"
```
  レスポンス
```
304 Not modified
```
  リソースが変更されていない場合、サーバーはリクエストを確認して、ステータス304変更なしを返します。変更がないため、レスポンス本文はありません。
  
  リソースが変更された場合、レスポンス本文には更新された情報と新しいETag値が含まれます。
```
200 OK
{
  "DisplayName": "Erin D Mack",
"@context": {
        "key": "180511",
        "headers": {
          "ETag": "FCED00057372000000014770400000014737A76612E6C616E672E4"
        },
  "links": [
    {
      "rel": "self",
      "href": "https://<host>:<port>/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/ ",
      "name": "names",
      "kind": "item",
      "properties": {
      }
    }
  ]
}
```
- 最後のGETリクエストが送信されてからリソースに変更がない場合、PATCHリクエストを送信してリソースを検証および更新します。この場合、最後のGETリクエストで取得されたETag値とともにIf-Matchヘッダーを使用できます。
  リクエスト
```
PATCH https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/Departments/10 
If-Match:"<etag_value>"
```
  レスポンス
  
  リソースが更新されない場合、リクエストで渡されたETag値はサーバー上の現在の値と一致し、更新リクエストが処理されます。レスポンスには、ステータス200のメッセージが表示され、レスポンス本文には更新された詳細が表示され、その後の使用のために新しいETag値が示されます。
```
200 OK
```
  リクエストのETagの値がサーバー上のものと異なる場合、他のリクエストがこのリソースを最近変更したことを意味します。したがって、この更新は処理できません。レスポンスには、412 Precondition Failedというステータスが表示されます。
```
412 Precondition Failed
```