ETag を使用して FHIR リソースの競合を防ぐ

このページでは、Cloud Healthcare API で FHIR リソースを使用して同時実行管理を行うために、エンティティ タグ（ETag）を使用する方法について説明します。ETag は、楽観的同時実行制御とクライアントサイド キャッシュを有効にすることで、データ損失を防ぎ、アプリケーションのパフォーマンスを向上させます。

ETag について

ETag は、バージョン番号と同様に、サーバー上の FHIR リソースの現在の状態の一意の識別子として機能します。FHIR リソースが作成または変更されるたびに、新しい ETag 値が生成されます。

ETag を使用すると、次の状況でデータの完全性を確保し、パフォーマンスを最適化できます。

  • 楽観的同時実行制御を保証するには: FHIR リソースを変更するリクエストに ETag を含めると、Cloud Healthcare API はその ETag がサーバー上の FHIR リソースの最新バージョンと一致するかどうかを検証します。これにより、あるクライアントが別のクライアントによる変更を誤って上書きするのを防ぐことができます。これは、書き込み-書き込みの競合または「更新の消失問題」とも呼ばれます。

  • 条件付きリクエストの送信: ETag を使用すると、特定の条件が満たされた場合にのみ、クライアントが条件付きでリクエストを送信できます。これにより、データ取得が最適化され、不要なネットワーク トラフィックが削減されます。たとえば、次の HTTP ヘッダーを使用して条件付きリクエストを送信できます。

    • If-Match: 指定された ETag がサーバー上の現在の ETag と一致する場合にのみ、リクエストは成功します。これにより、FHIR リソースの想定されるバージョンが確実に更新されます。
    • If-None-Match: 指定された ETag がサーバー上の現在の ETag と一致しない場合にのみ、リクエストは成功します。これにより、リソースのローカル キャッシュ バージョンが最新かどうかを確認できるため、毎回サーバーからリソース全体を取得する必要がなくなります。これは通常、効率的なキャッシュ保存に使用されます。

FHIR ETag は弱い検証を使用します。つまり、異なるサーバー インスタンス間で同一ではない可能性がありますが、リソースの変更を効果的に追跡できます。

ETag を取得する

次のサンプルでは、FHIR リソースの内容を取得する方法を示しています。

ETag は、FHIR リソースのコンテンツを取得するときに、完全な HTTP レスポンス ヘッダーに含まれます。ETag は FHIR リソースの Meta.versionId と一致します。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクトの ID
  • LOCATION: データセットの場所
  • DATASET_ID: FHIR ストアの親データセット
  • FHIR_STORE_ID: FHIR ストア ID
  • FHIR_RESOURCE_TYPE: FHIR のリソースタイプ
  • FHIR_RESOURCE_ID: FHIR のリソース ID

curl

fhir.read メソッドを使用します。-verbose フラグは、レスポンス内の HTTP ヘッダーを返します。このヘッダーには ETag が含まれています。

curl -X GET \
    -verbose \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

レスポンスには次のものが含まれます。

< etag: W/"ETAG_VALUE"

PowerShell

fhir.read メソッドを使用します。-Headers フラグは、レスポンスで HTTP ヘッダーを返します。このヘッダーには ETag が含まれています。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

レスポンスには次のものが含まれます。

ETag                   {W/"ETAG_VALUE"}

FHIR リソースの更新時に同時実行を管理する

次のサンプルは、FHIR リソースを更新するときに ETag を含める方法を示しています。

サンプルでは If-Match を使用します。この動作は次のとおりです。

  • ETag がサーバー上の FHIR リソースの現在の ETag と一致する場合、更新は成功し、サーバーは更新されたリソースの新しい ETag を生成します。これにより、FHIR リソースの想定されるバージョンが確実に更新されます。

  • ETag が一致しない場合、更新は 412 Precondition Failed エラーで失敗します。これは、元の ETag が取得されてから別のクライアントがリソースを変更したことを示します。これにより、誤って上書きされたことによるデータ損失を防ぐことができます。

リクエストのデータを使用する前に、次のように置き換えます。

  • ETAG_VALUE: FHIR リソースの ETag 値
  • PROJECT_ID: Google Cloud プロジェクトの ID
  • LOCATION: データセットの場所
  • DATASET_ID: FHIR ストアの親データセット
  • FHIR_STORE_ID: FHIR ストア ID
  • FHIR_RESOURCE_TYPE: FHIR のリソースタイプ
  • FHIR_RESOURCE_ID: FHIR のリソース ID

curl

fhir.update メソッドを使用します。

curl -X PUT \
    -H "If-Match: W/\"ETAG_VALUE\"" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -d @request.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

レスポンスには、更新された FHIR リソースが含まれます。

PowerShell

fhir.update メソッドを使用します。

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
  "Authorization" = "Bearer $cred"
  "If-Match"      = "$etag"}

Invoke-WebRequest `
    -Method PUT `
    -Headers $headers `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Content

レスポンスには、更新された FHIR リソースが含まれます。

クライアントサイド キャッシュを実装する

ETag を使用してクライアントサイド キャッシュを実装できます。これにより、データ取得が高速化され、よりスムーズでレスポンシブなユーザー エクスペリエンスを実現できます。

以前にキャッシュに保存された FHIR リソースを取得するには、キャッシュに保存された ETag を If-None-Match ヘッダーに含めます。このヘッダーには次の動作があります。

  • ETag が一致する場合、サーバーは 304 Not Modified で応答し、クライアントはキャッシュされたコピーを使用します。これにより、帯域幅が節約され、サーバーの負荷が軽減されます。

  • ETag が一致しない場合、サーバーは更新された FHIR リソースとその新しい ETag を送信し、クライアントがキャッシュを更新できるようにします。

次のサンプルは、サーバーの ETag と一致する ETag を使用して FHIR リソースの内容を取得する方法を示しています。

リクエストのデータを使用する前に、次のように置き換えます。

  • ETAG_VALUE: FHIR リソースの ETag 値
  • PROJECT_ID: Google Cloud プロジェクトの ID
  • LOCATION: データセットの場所
  • DATASET_ID: FHIR ストアの親データセット
  • FHIR_STORE_ID: FHIR ストア ID
  • FHIR_RESOURCE_TYPE: FHIR のリソースタイプ
  • FHIR_RESOURCE_ID: FHIR のリソース ID

curl

fhir.read メソッドを使用します。-verbose フラグはレスポンスで HTTP ヘッダーを返します。それ以外の場合はレスポンスが返されません。

curl -X GET \
    -H "If-None-Match: W/\"ETAG_VALUE\"" \
    -v \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

レスポンスには 304 Not Modified ステータス コードが含まれます。

PowerShell

fhir.read メソッドを使用します。-Headers フラグはレスポンスで HTTP ヘッダーを返します。それ以外の場合はレスポンスが返されません。

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
"Authorization" = "Bearer $cred"
  "If-None-Match"      = "$etag"}

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

レスポンスには 304 Not Modified ステータス コードが含まれます。