Halaman ini menjelaskan cara mengelola resource FHIR dengan menjalankan paket FHIR, yang merupakan kumpulan resource dan operasi FHIR yang akan dilakukan pada resource FHIR tersebut.
Metode
ExecuteBundle
menerapkan 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, memperbarui, atau menghapus, pada resource, seperti Pengamatan atau Pasien. Lihat deskripsi mendetail untuk elemen dalam resource Paket.
Saat Anda menjalankan paket FHIR, jenis paket menentukan cara operasi dalam paket dilakukan. Jenis paket berikut tersedia:
batch
: mengeksekusi operasi sebagai beberapa permintaan independen.transaction
: menjalankan operasi sebagai beberapa permintaan yang saling bergantung.history
: menyisipkan entri ke histori resource.
Misalnya, paket transaksi mencakup pembuatan resource Pasien dan resource Pengamatan. Jika permintaan pembuatan resource Pasien gagal, resource Pengamatan tidak akan dibuat.
Jika operasi gagal saat jenis paket adalah batch
, Cloud Healthcare API akan mengeksekusi operasi yang tersisa dalam paket. Jika operasi gagal saat jenis paket adalah transaction
, Cloud Healthcare API akan berhenti menjalankan operasi dan melakukan rollback 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 satu transaksi dengan batas
100 entri per paket. Jika versi resource dalam paket history
memiliki
stempel waktu yang lebih besar dari versi terbaru di FHIR store, versi terbaru akan diperbarui sebagaimana mestinya. Jika paket history
berhasil dimasukkan, 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
di
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 format yang ditampilkan dari metode
fhir.history
. Agar valid, setiap entri paket memerlukan ID resource, stempel waktu modifikasi, dan
status. Selain itu, semua entri harus memiliki ID resource yang sama. ID resource diberikan dengan kolom resource.id
atau kolom request.url
. Jika kolom disediakan, ID resource yang diberikan akan sama. Stempel waktu resource disediakan
dengan kolom meta.lastUpdated
di 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 ke paket FHIR yang dienkode 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 menjalankan 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 setiap operasi, setelah menjalankan paket
batch, server akan menampilkan representasi yang dienkode JSON dari resource Bundle
berjenis batch-response
. Resource Bundle
berisi satu entri untuk setiap entri dalam permintaan dengan hasil pemrosesan entri, yang dapat berupa campuran hasil keberhasilan 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 berhasil.
Jika terjadi error saat menjalankan paket transaksi, isi respons tidak
berisi paket. Sebagai gantinya, respons akan berisi resource OperationOutcome
yang dienkode JSON yang menjelaskan alasan error. Operasi yang berhasil dan
di-roll back tidak dilaporkan dalam respons.
Contoh paket berikut adalah output dari keberhasilan eksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Pasien 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 setiap operasi, setelah menjalankan paket
batch, server akan menampilkan representasi yang dienkode JSON dari resource Bundle
berjenis batch-response
. Resource Bundle
berisi satu entri untuk setiap entri dalam permintaan dengan hasil pemrosesan entri, yang dapat berupa campuran hasil keberhasilan 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 berhasil.
Jika terjadi error saat menjalankan paket transaksi, isi respons tidak
berisi paket. Sebagai gantinya, respons akan berisi resource OperationOutcome
yang dienkode JSON yang menjelaskan alasan error. Operasi yang berhasil dan
di-roll back tidak dilaporkan dalam respons.
Contoh paket berikut adalah output dari keberhasilan eksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Pasien 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 contoh tersedia di repositori GitHub contoh kode.
Python
File paket contoh tersedia di repositori GitHub contoh kode.
Membuat permintaan PATCH
Anda dapat menggunakan paket FHIR untuk membuat permintaan PATCH
JSON pada resource FHIR.
Lihat Menjalankan permintaan PATCH
dalam paket FHIR
untuk mengetahui informasi selengkapnya.
Me-resolve referensi ke resource yang dibuat dalam paket
Resource dalam paket transaksi dapat berisi referensi ke resource yang tidak
ada di 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 akan ditulis ulang ke ID resource
yang sesuai di penyimpanan. Hal ini 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 hasil dari operasi pembuatan.
Contoh paket berikut membuat resource Pasien dan resource Observasi 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 menjalankan paket.
curl
File paket contoh tersedia di repositori GitHub contoh kode.
Untuk menjalankan 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"
Contoh paket berikut adalah output dari keberhasilan eksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Pasien dan menyertakan ID resource baru. Entri kedua menunjukkan keberhasilan operasi untuk membuat Pengamatan dan menyertakan ID resource baru.
{ "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 contoh tersedia di repositori GitHub contoh kode.
Untuk menjalankan 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
Contoh paket berikut adalah output dari keberhasilan eksekusi contoh di atas. Entri pertama menunjukkan keberhasilan operasi untuk membuat Pasien dan menyertakan ID resource baru. Entri kedua menunjukkan keberhasilan operasi untuk membuat Pengamatan dan menyertakan ID resource baru.
{ "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" }