Mencegah konflik resource FHIR menggunakan ETag

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

Memahami ETag

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

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 menimpa perubahan yang dilakukan oleh klien lain secara tidak sengaja, 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 bersyarat menggunakan header HTTP berikut:

  • If-Match: Permintaan hanya berhasil jika ETag yang diberikan cocok dengan ETag saat ini di server. Hal ini memastikan Anda mengupdate versi resource FHIR yang diharapkan.
  • If-None-Match: Permintaan hanya berhasil jika ETag yang diberikan tidak cocok dengan ETag saat ini di server. Dengan begitu, Anda dapat mengetahui apakah versi resource yang di-cache secara lokal masih berlaku, sehingga mengurangi kebutuhan untuk mengambil resource lengkap dari server setiap saat. Header 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 tetap efektif melacak perubahan resource.

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 Google Cloud project Anda
• LOCATION: lokasi set data
• DATASET_ID: set data induk FHIR store
• FHIR_STORE_ID: ID FHIR store
• FHIR_RESOURCE_TYPE: jenis resource FHIR
• FHIR_RESOURCE_ID: ID resource FHIR

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus sudah diberi izin berikut atau peran Identity and Access Management (IAM) berikut:

Izin

• healthcare.fhirResources.get

Peran

• Healthcare FHIR Resource Reader (roles/healthcare.fhirResourceReader)

Anda dapat meminta administrator Anda untuk memberikan peran Identity and Access Management ini kepada Anda. Untuk mengetahui petunjuk tentang cara memberikan peran, lihat Mengelola akses atau Mengontrol akses ke resource Cloud Healthcare API. Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Catatan: Jika Anda membuat project Google Cloud untuk panduan ini, sebagai pembuat project, Anda akan otomatis diberi peran IAM Pemilik (roles/owner), yang memiliki izin. Anda tidak perlu diberi peran IAM tambahan.

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 mengupdate 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, pembaruan akan berhasil, dan server akan membuat ETag baru untuk resource yang diperbarui. Hal 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 Google Cloud project Anda
• LOCATION: lokasi set data
• DATASET_ID: set data induk FHIR store
• FHIR_STORE_ID: ID FHIR store
• FHIR_RESOURCE_TYPE: jenis resource FHIR
• FHIR_RESOURCE_ID: ID resource FHIR

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus sudah diberi izin berikut atau peran Identity and Access Management (IAM) berikut:

Izin

• healthcare.fhirResources.update

Peran

• Healthcare FHIR Resource Editor (roles/healthcare.fhirResourceEditor)

Anda dapat meminta administrator Anda untuk memberikan peran Identity and Access Management ini kepada Anda. Untuk mengetahui petunjuk tentang cara memberikan peran, lihat Mengelola akses atau Mengontrol akses ke resource Cloud Healthcare API. Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Catatan: Jika Anda membuat project Google Cloud untuk panduan ini, sebagai pembuat project, Anda akan otomatis diberi peran IAM Pemilik (roles/owner), yang memiliki izin. Anda tidak perlu diberi peran IAM tambahan.

curl

Gunakan metode fhir.update.

Penting: Contoh menyertakan tanda -d @request.json. Anda harus memiliki file request.json yang valid di direktori saat ini sebelum menjalankan contoh. Untuk contoh hal-hal yang harus disertakan dalam file request.json, lihat Memperbarui resource FHIR.

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.

Penting: Contoh menyertakan tanda -Infile request.json. Anda harus memiliki file request.json yang valid di direktori saat ini sebelum menjalankan contoh. Untuk contoh hal-hal yang harus disertakan dalam file request.json, lihat Memperbarui resource FHIR.

$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.

Menerapkan penyimpanan dalam 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 di-cache sebelumnya, Anda dapat menyertakan ETag yang di-cache di 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 me-refresh 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 Google Cloud project Anda
• LOCATION: lokasi set data
• DATASET_ID: set data induk FHIR store
• FHIR_STORE_ID: ID FHIR store
• FHIR_RESOURCE_TYPE: jenis resource FHIR
• FHIR_RESOURCE_ID: ID resource FHIR

Izin yang diperlukan untuk langkah ini

Untuk melakukan tugas ini, Anda harus sudah diberi izin berikut atau peran Identity and Access Management (IAM) berikut:

Izin

• healthcare.fhirResources.get

Peran

• Healthcare FHIR Resource Reader (roles/healthcare.fhirResourceReader)

Anda dapat meminta administrator Anda untuk memberikan peran Identity and Access Management ini kepada Anda. Untuk mengetahui petunjuk tentang cara memberikan peran, lihat Mengelola akses atau Mengontrol akses ke resource Cloud Healthcare API. Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Catatan: Jika Anda membuat project Google Cloud untuk panduan ini, sebagai pembuat project, Anda akan otomatis diberi peran IAM Pemilik (roles/owner), yang memiliki izin. Anda tidak perlu diberi peran IAM tambahan.

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"

Respons 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

Respons berisi kode status 304 Not Modified.