Mencegah konflik resource FHIR menggunakan ETag

Halaman ini menjelaskan cara menggunakan tag entity (ETag) untuk pengelolaan konkurensi dengan resource FHIR di Cloud Healthcare API. ETag membantu mencegah hilangnya data dan meningkatkan performa aplikasi dengan mengaktifkan kontrol konkurensi optimis dan penyimpanan dalam cache sisi klien.

Memahami ETag

ETag berfungsi sebagai ID unik untuk status resource FHIR saat ini di server, mirip dengan nomor versi. Setiap kali resource FHIR dibuat atau diubah, nilai ETag baru akan dihasilkan.

Anda dapat menggunakan ETag untuk memastikan integritas data dan mengoptimalkan performa dalam situasi berikut:

  • Untuk memastikan kontrol konkurensi optimis: Saat Anda menyertakan ETag dalam permintaan untuk mengubah resource FHIR, Cloud Healthcare API akan memverifikasi apakah ETag cocok dengan versi terbaru resource FHIR di server. Hal ini membantu mencegah satu klien tidak sengaja menimpa perubahan yang dibuat oleh klien lain, yang juga disebut konflik tulis-tulis atau "masalah update yang hilang".

  • Mengirim permintaan bersyarat: ETag memungkinkan klien mengirim permintaan secara bersyarat hanya jika kondisi tertentu terpenuhi. Hal ini mengoptimalkan pengambilan data dan mengurangi traffic jaringan yang tidak perlu. Misalnya, Anda dapat mengirim permintaan kondisional menggunakan header HTTP berikut:

    • If-Match: Permintaan hanya berhasil jika ETag yang diberikan cocok dengan ETag saat ini di server. Tindakan ini memastikan Anda memperbarui versi resource FHIR yang diharapkan.
    • If-None-Match: Permintaan hanya berhasil jika ETag yang diberikan tidak cocok dengan ETag saat ini di server. Hal ini memungkinkan Anda mengetahui apakah versi resource yang di-cache secara lokal masih terbaru, sehingga mengurangi kebutuhan untuk mengambil resource lengkap dari server setiap saat. Hal ini biasanya digunakan untuk penyimpanan dalam cache yang efisien.

ETag FHIR menggunakan validasi lemah, yang berarti ETag tersebut mungkin tidak identik di berbagai instance server, tetapi ETag tersebut masih melacak perubahan resource secara efektif.

Mendapatkan ETag

Contoh berikut menunjukkan cara mendapatkan ETag resource FHIR.

ETag disertakan dalam header respons HTTP lengkap saat Anda mendapatkan konten resource FHIR. ETag cocok dengan Meta.versionId dalam resource FHIR.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: ID project Google Cloud Anda
  • LOCATION: lokasi set data
  • DATASET_ID: set data induk penyimpanan FHIR
  • FHIR_STORE_ID: ID FHIR store
  • FHIR_RESOURCE_TYPE: jenis resource FHIR
  • FHIR_RESOURCE_ID: ID resource FHIR

curl

Gunakan metode fhir.read. Flag -verbose menampilkan header HTTP dalam respons, yang berisi 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"

Responsnya berisi hal berikut:

< etag: W/"ETAG_VALUE"

PowerShell

Gunakan metode fhir.read. Flag -Headers menampilkan header HTTP dalam respons, yang berisi 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

Responsnya berisi hal berikut:

ETag                   {W/"ETAG_VALUE"}

Mengelola serentak saat memperbarui resource FHIR

Contoh berikut menunjukkan cara menyertakan ETag saat memperbarui resource FHIR.

Contoh menggunakan If-Match, yang memiliki perilaku berikut:

  • Jika ETag cocok dengan ETag saat ini dari resource FHIR di server, update akan berhasil, dan server akan membuat ETag baru untuk resource yang diperbarui. Tindakan ini memastikan Anda mengupdate versi resource FHIR yang diharapkan.

  • Jika ETag tidak cocok, update akan gagal dengan error 412 Precondition Failed, yang menunjukkan bahwa klien lain telah mengubah resource sejak ETag asli diambil. Tindakan ini mencegah kehilangan data akibat penimpaan yang tidak disengaja.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • ETAG_VALUE: nilai ETag resource FHIR
  • PROJECT_ID: ID project Google Cloud Anda
  • LOCATION: lokasi set data
  • DATASET_ID: set data induk penyimpanan FHIR
  • FHIR_STORE_ID: ID FHIR store
  • FHIR_RESOURCE_TYPE: jenis resource FHIR
  • FHIR_RESOURCE_ID: ID resource FHIR

curl

Gunakan metode 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"

Respons berisi resource FHIR yang diperbarui.

PowerShell

Gunakan metode 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

Respons berisi resource FHIR yang diperbarui.

Mengimplementasikan cache sisi klien

Anda dapat menggunakan ETag untuk menerapkan penyimpanan dalam cache sisi klien, yang mempercepat pengambilan data dan berkontribusi pada pengalaman pengguna yang lebih lancar dan responsif.

Untuk mengambil resource FHIR yang sebelumnya di-cache, Anda dapat menyertakan ETag yang di-cache dalam header If-None-Match, yang memiliki perilaku berikut:

  • Jika ETag cocok, server akan merespons dengan 304 Not Modified, dan klien akan menggunakan salinan yang di-cache. Hal ini menghemat bandwidth dan mengurangi beban server.

  • Jika ETag tidak cocok, server akan mengirimkan resource FHIR yang diperbarui dan ETag barunya, sehingga klien dapat memuat ulang cache-nya.

Contoh berikut menunjukkan cara mendapatkan konten resource FHIR menggunakan ETag yang cocok dengan ETag di server.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • ETAG_VALUE: nilai ETag resource FHIR
  • PROJECT_ID: ID project Google Cloud Anda
  • LOCATION: lokasi set data
  • DATASET_ID: set data induk penyimpanan FHIR
  • FHIR_STORE_ID: ID FHIR store
  • FHIR_RESOURCE_TYPE: jenis resource FHIR
  • FHIR_RESOURCE_ID: ID resource FHIR

curl

Gunakan metode fhir.read. Flag -verbose menampilkan header HTTP dalam respons. Jika tidak, tidak ada respons yang ditampilkan.

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"

Responsnya berisi kode status 304 Not Modified.

PowerShell

Gunakan metode fhir.read. Flag -Headers menampilkan header HTTP dalam respons, jika tidak, tidak ada respons yang ditampilkan.

$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

Responsnya berisi kode status 304 Not Modified.