Halaman ini menjelaskan cara mengelola resource FHIR dengan menjalankan paket FHIR, yang merupakan kumpulan resource FHIR dan operasi yang akan dilakukan pada resource FHIR tersebut.
Metode
ExecuteBundle
menerapkan interaksi batch/transaksi standar FHIR
(DSTU2,
STU3,
R4,
dan R5) dan operasi histori.
Paket FHIR
Paket FHIR berisi array entri, yang masing-masing merepresentasikan operasi, seperti pembuatan, update, atau penghapusan, 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 dilakukan. Jenis paket berikut tersedia:
batch
: menjalankan operasi sebagai beberapa permintaan independen.transaction
: menjalankan operasi sebagai beberapa permintaan yang saling bergantung.history
: memasukkan entri ke dalam histori resource.
Misalnya, paket transaksi mencakup pembuatan resource Pasien dan resource Observasi. Jika permintaan pembuatan resource Pasien gagal, resource Pengamatan tidak akan dibuat.
Jika operasi gagal saat jenis paket adalah batch
, Cloud Healthcare API akan 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 satu transaksi dengan batas
100 entri per paket. Jika versi resource dalam paket history
memiliki
stempel waktu yang lebih besar daripada versi terbaru di FHIR store, maka
versi terbaru akan diupdate 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
pada
konfigurasi penyimpanan FHIR.
Anda tidak dapat menggunakan paket histori jika disableResourceVersioning
disetel ke true
pada konfigurasi penyimpanan FHIR.
Paket histori disediakan dalam format yang sama dengan format saat 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 disediakan harus sama. Stempel waktu resource disediakan
dengan kolom meta.lastUpdated
di resource atau kolom
response.lastModified
.
Memberikan izin untuk mengeksekusi paket
Peran izin datasets.fhirStores.fhir.executeBundle
diperlukan untuk
mengeksekusi paket. Untuk memberikan izin ini, gunakan peran
healthcare.fhirResourceReader
. Untuk mengetahui langkah-langkah pemberian 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 Anda 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 mengeksekusi 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.
Bundle contoh 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 operasi individual, setelah menjalankan paket batch, server akan menampilkan representasi berenkode 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
berjenis 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 di-roll back tidak dilaporkan dalam respons.
Paket contoh berikut adalah output dari keberhasilan menjalankan 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 operasi individual, setelah menjalankan paket batch, server akan menampilkan representasi berenkode 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
berjenis 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 di-roll back tidak dilaporkan dalam respons.
Paket contoh berikut adalah output dari keberhasilan menjalankan 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 Mengeksekusi permintaan PATCH
dalam FHIR bundle
untuk mengetahui 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 hubungan antara resource menggunakan
kolom entry.fullUrl
. Referensi yang cocok dengan nilai entry.fullUrl
dari
resource lain dalam paket ditulis ulang ke ID resource yang sesuai
di toko. Operasi 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 di-resolve ke nama yang berbeda sebagai hasil dari operasi pembuatan.
Paket contoh 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 mengeksekusi bundle, buat permintaan POST dan tentukan informasi berikut:
- Nama dan lokasi set data induk dan penyimpanan FHIR
- Lokasi file Bundle 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 menjalankan 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 mengeksekusi bundle, buat permintaan POST dan tentukan informasi berikut:
- Nama dan lokasi set data induk dan penyimpanan FHIR
- Lokasi file Bundle 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 menjalankan 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" }