Halaman ini menjelaskan cara mengelola resource FHIR dengan mengeksekusi paket FHIR, yang merupakan kumpulan resource dan operasi FHIR untuk dijalankan pada resource FHIR tersebut.
Metode ExecuteBundle
mengimplementasikan interaksi batch/transaksi standar FHIR (DSTU2, STU3, dan R4) serta operasi histori.
Paket FHIR
Paket FHIR berisi array entri, yang masing-masing mewakili operasi, seperti membuat, mengupdate, atau menghapus, pada resource, seperti Pengamatan atau Pasien. Lihat deskripsi mendetail untuk elemen dalam resource Bundle.
Saat Anda menjalankan paket FHIR, jenis paket menentukan cara operasi dalam paket dijalankan. Berikut jenis paket yang tersedia:
batch
: menjalankan operasi sebagai beberapa permintaan independen.transaction
: menjalankan operasi sebagai beberapa permintaan yang bergantung satu sama lain.history
: menyisipkan entri ke dalam histori resource.
Misalnya, anggaplah paket transaksi mencakup pembuatan resource Pasien dan resource Observation. Jika permintaan pembuatan resource Pasien gagal, resource Observation tidak akan dibuat.
Jika operasi gagal saat jenis paket adalah batch
, Cloud Healthcare API menjalankan operasi yang tersisa dalam paket. Jika operasi gagal saat jenis paket adalah transaction
, Cloud Healthcare API akan berhenti menjalankan operasi dan me-roll back transaksi.
Paket histori
Paket histori adalah ekstensi kustom untuk standar FHIR yang mendukung kasus penggunaan pencadangan dan pemulihan, seperti sinkronisasi. Anda dapat menggunakan paket histori untuk menyisipkan atau mengganti versi resource dalam histori resource FHIR. Anda hanya dapat menghapus versi resource menggunakan metode
Resource-purge
. Paket history
dijalankan sebagai transaksi tunggal dengan batas 100 entri per paket. Jika versi resource dalam paket history
memiliki
stempel waktu yang lebih besar daripada versi terbaru di penyimpanan FHIR, maka versi terbaru akan diupdate. Jika paket history
berhasil disisipkan, respons kosong akan ditampilkan. Jika tidak, OperationOutcome
akan ditampilkan yang menjelaskan kegagalan.
Dukungan untuk paket histori tidak diaktifkan secara default. Administrator penyimpanan FHIR harus
menetapkan enableHistoryModifications
ke true
pada
konfigurasi penyimpanan FHIR.
Anda tidak dapat menggunakan paket histori jika disableResourceVersioning
ditetapkan ke true
pada konfigurasi penyimpanan FHIR.
Paket histori disediakan dalam format yang sama dengan yang ditampilkan dari
metode
fhir.history
. Agar valid, setiap entri paket memerlukan ID resource, stempel waktu perubahan, dan
status. Selain itu, semua entri harus memiliki ID resource yang sama. ID
resource disediakan dengan kolom resource.id
atau kolom
request.url
. Jika kolom diberikan, ID resource yang diberikan sama. Stempel waktu resource disediakan
dengan kolom meta.lastUpdated
dalam resource atau
kolom response.lastModified
.
Memberikan izin untuk menjalankan paket
Peran izin datasets.fhirStores.fhir.executeBundle
diperlukan untuk
menjalankan paket. Untuk memberikan izin ini, gunakan
peran healthcare.fhirResourceReader
. Untuk mengetahui langkah-langkah dalam memberikan izin ini,
lihat Mengubah kebijakan.
Untuk menjalankan paket histori, peran izin datasets.fhirStores.fhir.import
juga diperlukan.
Cloud Healthcare API memeriksa izin untuk setiap operasi dalam paket.
Jika memiliki izin healthcare.fhirResources.create
tetapi tidak memiliki izin healthcare.fhirResources.update
, Anda hanya dapat menjalankan paket yang berisi operasi healthcare.fhirResources.create
.
Menjalankan paket
Untuk menjalankan paket FHIR, gunakan
metode
projects.locations.datasets.fhirStores.fhir.executeBundle
.
Dalam contoh berikut, BUNDLE.json adalah jalur dan nama file untuk paket FHIR berenkode JSON. Anda juga dapat menyertakan paket dalam isi permintaan.
Contoh Paket berikut membuat resource Pasien dan menghapus resource Pasien lainnya:
{
"resourceType": "Bundle",
"id": "bundle-transaction",
"meta": {
"lastUpdated": "2018-03-11T11:22:16Z"
},
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Smith",
"given": [
"Darcy"
]
}
],
"gender": "female",
"address": [
{
"line": [
"123 Main St."
],
"city": "Anycity",
"state": "CA",
"postalCode": "12345"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"request": {
"method": "DELETE",
"url": "Patient/1234567890"
}
}
]
}
Contoh berikut menunjukkan cara mengeksekusi paket.
curl
Untuk menjalankan paket, buat permintaan POST
dan tentukan informasi
berikut:
- Nama dan lokasi set data induk dan penyimpanan FHIR
- Lokasi file paket di komputer lokal Anda
- Token akses
Contoh berikut menunjukkan permintaan POST
menggunakan curl:
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Terlepas dari hasil operasi individual, setelah mengeksekusi paket batch, server akan menampilkan representasi yang dienkode JSON dari resource Bundle
jenis batch-response
. Resource Bundle
berisi satu entri untuk setiap
entri dalam permintaan dengan hasil pemrosesan entri, yang dapat berupa
campuran hasil sukses dan error.
Jika paket transaksi berhasil, server akan menampilkan representasi yang dienkode
JSON dari resource Bundle
jenis transaction-response
yang berisi
satu entri untuk setiap entri dalam permintaan dengan hasil operasi yang sukses.
Jika terjadi error saat menjalankan paket transaksi, isi respons tidak berisi paket. Sebagai gantinya, file ini berisi resource OperationOutcome
berenkode JSON
yang menjelaskan alasan terjadinya error. Operasi yang berhasil dan di-roll back tidak dilaporkan dalam respons.
Paket contoh berikut adalah output dari keberhasilan mengeksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Patient dan menyertakan ID resource baru. Entri kedua menunjukkan keberhasilan operasi penghapusan.
{ "entry": [ { "response": { "location": projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID, "status": "201 Created" } }, { "response": { "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
Untuk menjalankan paket, buat permintaan POST
dan tentukan informasi
berikut:
- Nama dan lokasi set data induk dan penyimpanan FHIR
- Lokasi file paket di komputer lokal Anda
- Token akses
Contoh berikut menunjukkan permintaan POST
menggunakan Windows PowerShell:
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Terlepas dari hasil operasi individual, setelah mengeksekusi paket batch, server akan menampilkan representasi yang dienkode JSON dari resource Bundle
jenis batch-response
. Resource Bundle
berisi satu entri untuk setiap
entri dalam permintaan dengan hasil pemrosesan entri, yang dapat berupa
campuran hasil sukses dan error.
Jika paket transaksi berhasil, server akan menampilkan representasi yang dienkode
JSON dari resource Bundle
jenis transaction-response
yang berisi
satu entri untuk setiap entri dalam permintaan dengan hasil operasi yang sukses.
Jika terjadi error saat menjalankan paket transaksi, isi respons tidak berisi paket. Sebagai gantinya, file ini berisi resource OperationOutcome
berenkode JSON
yang menjelaskan alasan terjadinya error. Operasi yang berhasil dan di-roll back tidak dilaporkan dalam respons.
Paket contoh berikut adalah output dari keberhasilan mengeksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Patient dan menyertakan ID resource baru. Entri kedua menunjukkan keberhasilan operasi penghapusan.
{ "entry": [ { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "location": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE/RESOURCE_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-03T04:12:47.312669+00:00", "status": "200 OK" } } ], "resourceType": "Bundle", "type": "transaction-response" }
Go
Java
Node.js
File paket sampel tersedia di repositori GitHub contoh kode.
Python
File paket sampel tersedia di repositori GitHub contoh kode.
Buat permintaan PATCH
Anda dapat menggunakan paket FHIR untuk membuat permintaan PATCH
JSON pada resource FHIR.
Lihat Mengeksekusi permintaan PATCH
dalam paket FHIR
untuk informasi selengkapnya.
Menyelesaikan referensi ke resource yang dibuat dalam paket
Resource dalam paket transaksi dapat berisi referensi ke resource yang tidak
ada dalam sistem target, tetapi dibuat selama eksekusi paket. Cloud Healthcare API menyelesaikan pengaitan antara resource menggunakan kolom entry.fullUrl
. Referensi yang cocok dengan nilai entry.fullUrl
resource lain dalam paket ditulis ulang ke ID resource
yang sesuai di penyimpanan. Proses ini akan berhasil terlepas dari urutan operasi dalam paket.
Cloud Healthcare API menerima fullUrl
dalam format berikut:
urn:uuid:UUID
urn:oid:OID
- URL apa pun
- nama resource dalam format
RESOURCE_TYPE/RESOURCE_ID
, sepertiPatient/123
. Penggunaan format ini tidak direkomendasikan karenafullUrl
adalah placeholder lokal untuk paket. Hal ini dapat menimbulkan kebingungan jika resource di toko memiliki nama yang sama, tetapi resource dalam paket me-resolve ke nama yang berbeda sebagai akibat dari operasi create.
Paket contoh berikut membuat resource Pasien dan resource Observation yang merujuk ke resource Pasien.
{
"resourceType": "Bundle",
"type": "transaction",
"entry":[
{
"request": {
"method":"POST",
"url":"Patient"
},
"fullUrl": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9",
"resource": {
"resourceType":"Patient",
"gender":"male"
}
},
{
"request": {
"method":"POST",
"url":"Observation"
},
"resource": {
"resourceType":"Observation",
"subject": {
"reference": "urn:uuid:05efabf0-4be2-4561-91ce-51548425acb9"
},
"status":"preliminary",
"code": {
"text":"heart rate"
}
}
}
]
}
Contoh berikut menunjukkan cara mengeksekusi paket.
curl
File paket sampel tersedia di repositori GitHub contoh kode.
Untuk mengeksekusi paket, buat permintaan POST dan tentukan informasi berikut:
- Nama dan lokasi set data induk dan penyimpanan FHIR
- Lokasi file Paket di Cloud Storage
- Token akses
Contoh berikut menunjukkan permintaan POST
menggunakan curl:
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ --data @BUNDLE_FILE.json \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"
Paket contoh berikut adalah output dari keberhasilan mengeksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Patient dan menyertakan ID resource baru. Entri kedua menunjukkan keberhasilan operasi untuk membuat Observation dan menyertakan ID resource baru tersebut.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }
PowerShell
File paket sampel tersedia di repositori GitHub contoh kode.
Untuk mengeksekusi paket, buat permintaan POST dan tentukan informasi berikut:
- Nama dan lokasi set data induk dan penyimpanan FHIR
- Lokasi file Paket di Cloud Storage
- Token akses
Contoh berikut menunjukkan permintaan POST
menggunakan Windows PowerShell:
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json" ` -InFile BUNDLE_FILE.json ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir" | ConvertTo-Json
Paket contoh berikut adalah output dari keberhasilan mengeksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Patient dan menyertakan ID resource baru. Entri kedua menunjukkan keberhasilan operasi untuk membuat Observation dan menyertakan ID resource baru tersebut.
{ "entry": [ { "response": { "etag": "ETAG1", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID/_history/HISTORY_ID", "status": "201 Created" } }, { "response": { "etag": "ETAG", "lastModified": "2020-08-04T16:14:14.273976+00:00", "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/datasets/REGION/fhirStores/FHIR_STORE_ID/fhir/Observation/OBSERVATION_ID/_history/HISTORY_ID", "status": "201 Created" } } ], "resourceType": "Bundle", "type": "transaction-response" }