Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Bundling sumber daya FHIR
FHIR `Bundle` adalah wadah untuk koleksi sumber daya FHIR di. AWS HealthLake AWS HealthLake mendukung dua jenis bundel dengan perilaku pemrosesan yang berbeda.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction)bundel memproses setiap sumber daya secara independen. Jika satu sumber daya gagal, sumber daya yang tersisa masih bisa berhasil. Setiap operasi diproses secara individual, dan pemrosesan berlanjut bahkan ketika beberapa operasi gagal. Gunakan bundel batch untuk operasi massal di mana keberhasilan sebagian dapat diterima, seperti mengunggah beberapa catatan pasien yang tidak terkait.
[https://hl7.org/fhir/R4/http.html#transaction](https://hl7.org/fhir/R4/http.html#transaction)bundel memproses semua sumber daya secara atom sebagai satu unit. Entah semua operasi sumber daya berhasil, atau tidak AWS HealthLake melakukan satu pun dari mereka. Gunakan bundel transaksi saat Anda membutuhkan jaminan integritas referensial di seluruh sumber daya terkait, seperti membuat pasien dengan pengamatan dan kondisi terkait di mana semua data harus direkam bersama.
**Perbedaan antara batch dan bundel transaksi**
| Fitur | Batch | Transaksi |
| --- | --- | --- |
| Model pengolahan | Setiap operasi berhasil atau gagal secara independen. | Semua operasi berhasil atau gagal sebagai satu unit atom. |
| Penanganan kegagalan | Pemrosesan berlanjut bahkan jika operasi individu gagal. | Seluruh bundel gagal jika ada operasi tunggal yang gagal. |
| Perintah eksekusi | Perintah eksekusi tidak dijamin. | Operasi diproses dalam urutan yang ditentukan. |
| Integritas referensial | Tidak diberlakukan di seluruh operasi. | Ditegakkan untuk sumber daya yang direferensikan secara lokal dalam bundel. |
| Paling baik digunakan untuk | Operasi massal di mana keberhasilan sebagian dapat diterima. | Sumber daya terkait yang harus dibuat atau diperbarui bersama. |
Anda dapat menggabungkan sumber daya FHIR dari jenis yang sama atau berbeda, dan mereka dapat menyertakan campuran operasi FHIR, seperti,`create`,, `read` `update``delete`, dan. `patch` Untuk informasi tambahan, lihat [Resource Bundle](https://hl7.org/fhir/R4/Bundle) dalam dokumentasi **FHIR R4**.
Berikut ini adalah contoh kasus penggunaan untuk setiap jenis bundel.
Bundel Batch
+ Unggah beberapa catatan pasien yang tidak terkait dari fasilitas yang berbeda selama sinkronisasi data malam hari.
+ Unggah massal catatan pengobatan historis di mana beberapa catatan mungkin memiliki masalah validasi.
+ Muat data referensi, seperti organisasi dan praktisi, di mana kegagalan individu tidak memengaruhi entri lain.
Bundel transaksi
+ Buat pasien dengan pengamatan dan kondisi terkait selama penerimaan departemen gawat darurat di mana semua data harus direkam bersama.
+ Perbarui daftar obat pasien dan informasi alergi terkait yang harus tetap konsisten.
+ Catat pertemuan lengkap dengan pasien, pengamatan, prosedur, dan informasi penagihan sebagai satu unit atom.
**penting**
Bundel batch dan transaksi menggunakan struktur `Bundle` sumber daya yang sama. Satu-satunya perbedaan adalah nilai `type` bidang.
Contoh berikut menunjukkan bundel transaksi dengan beberapa jenis sumber daya dan operasi.
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065",
"resource": {
"resourceType": "Patient",
"id": "new-patient",
"active": true,
"name": [
{
"family": "Johnson",
"given": [
"Sarah"
]
}
],
"gender": "female",
"birthDate": "1985-08-12",
"telecom": [
{
"system": "phone",
"value": "555-123-4567",
"use": "home"
}
]
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"fullUrl": "urn:uuid:7f83f473-d8cc-4a8d-86d3-9d9876a3248b",
"resource": {
"resourceType": "Observation",
"id": "blood-pressure",
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel"
}
],
"text": "Blood pressure panel"
},
"subject": {
"reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
},
"effectiveDateTime": "2023-10-15T09:30:00Z",
"component": [
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8480-6",
"display": "Systolic blood pressure"
}
]
},
"valueQuantity": {
"value": 120,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
},
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8462-4",
"display": "Diastolic blood pressure"
}
]
},
"valueQuantity": {
"value": 80,
"unit": "mmHg",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
}
]
},
"request": {
"method": "POST",
"url": "Observation"
}
},
{
"resource": {
"resourceType": "Appointment",
"id": "appointment-123",
"status": "booked",
"description": "Annual physical examination",
"start": "2023-11-15T09:00:00Z",
"end": "2023-11-15T09:30:00Z",
"participant": [
{
"actor": {
"reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
},
"status": "accepted"
}
]
},
"request": {
"method": "PUT",
"url": "Appointment/appointment-123"
}
},
{
"request": {
"method": "DELETE",
"url": "MedicationRequest/med-request-456"
}
}
]
}
```
## Menggabungkan sumber daya FHIR sebagai entitas independen
**Untuk menggabungkan sumber daya FHIR sebagai entitas independen**
1. Kumpulkan HealthLake `region` dan `datastoreId` nilai. Untuk informasi selengkapnya, lihat [Mendapatkan properti penyimpanan data](managing-data-stores-describe.md).
1. Buat URL untuk permintaan menggunakan nilai yang dikumpulkan untuk HealthLake `region` dan`datastoreId`. *Jangan* tentukan jenis sumber daya FHIR di URL. Untuk melihat seluruh jalur URL dalam contoh berikut, gulir ke atas tombol **Salin**.
```
POST https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/
```
1. Membangun badan JSON untuk permintaan, menentukan setiap kata kerja HTTP sebagai bagian dari elemen. `method` Contoh berikut menggunakan interaksi `batch` tipe dengan `Bundle` sumber daya untuk membuat baru `Patient` dan `Medication` sumber daya. Semua bagian yang diperlukan dikomentari sesuai. Untuk tujuan prosedur ini, simpan file sebagai`batch-independent.json`.
```
{
"resourceType": "Bundle",
"id": "bundle-batch",
"meta": {
"lastUpdated": "2014-08-18T01:43:30Z"
},
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"meta": {
"lastUpdated": "2022-06-03T17:53:36.724Z"
},
"text": {
"status": "generated",
"div": "Some narrative"
},
"active": true,
"name": [
{
"use": "official",
"family": "Jackson",
"given": [
"Mateo",
"James"
]
}
],
"gender": "male",
"birthDate": "1974-12-25"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Medication",
"id": "med0310",
"contained": [
{
"resourceType": "Substance",
"id": "sub03",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "55452001",
"display": "Oxycodone (substance)"
}
]
}
}
],
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "430127000",
"display": "Oral Form Oxycodone (product)"
}
]
},
"form": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "385055001",
"display": "Tablet dose form (qualifier value)"
}
]
},
"ingredient": [
{
"itemReference": {
"reference": "#sub03"
},
"strength": {
"numerator": {
"value": 5,
"system": "http://unitsofmeasure.org",
"code": "mg"
},
"denominator": {
"value": 1,
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
}
]
},
"request": {
"method": "POST",
"url": "Medication"
}
}
]
}
```
1. Kirim permintaan . Jenis `Bundle` batch FHIR menggunakan `POST` permintaan dengan [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) atau SMART pada otorisasi FHIR. Contoh kode berikut menggunakan alat baris `curl` perintah untuk tujuan demonstrasi.
------
#### [ SigV4 ]
Otorisasi SiGv4
```
curl --request POST \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "{{$AWS_ACCESS_KEY_ID}}:{{$AWS_SECRET_ACCESS_KEY}}" \
--header "x-amz-security-token:{{$AWS_SESSION_TOKEN}}" \
--header 'Accept: application/json' \
--data @batch-type.json
```
------
#### [ SMART on FHIR ]
SMART pada contoh otorisasi FHIR untuk tipe [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)data.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
Penelepon dapat menetapkan izin di lambda otorisasi. Untuk informasi selengkapnya, lihat [OAuth 2.0 cakupan](reference-smart-on-fhir-oauth-scopes.md).
------
Server mengembalikan respons yang menunjukkan `Patient` dan `Medication` sumber daya yang dibuat sebagai hasil dari permintaan jenis `Bundle` batch.
## Bersyarat PUTs dalam bundel
AWS HealthLake mendukung pembaruan bersyarat dalam bundel menggunakan parameter kueri berikut:
**catatan**
PUTs Kondisional hanya didukung dalam `batch` bundel. `Transaction`bundel tidak mendukung kondisional PUTs.
+ `_id`(mandiri)
+ `_id`dalam kombinasi dengan salah satu dari berikut ini:
+ `_tag`
+ `_createdAt`
+ `_lastUpdated`
Saat Anda menggunakan kondisional PUTs dalam bundel, AWS HealthLake mengevaluasi parameter kueri terhadap sumber daya yang ada dan mengambil tindakan berdasarkan hasil pencocokan.
**Perilaku pembaruan bersyarat**
| Skenario | Status HTTP | Tindakan yang diambil |
| --- | --- | --- |
| Sumber daya tanpa ID yang disediakan | 201 Dibuat | Selalu menciptakan sumber daya baru. |
| Sumber daya dengan ID baru (tidak cocok) | 201 Dibuat | Membuat sumber daya baru dengan ID yang ditentukan. |
| Sumber daya dengan ID yang ada (kecocokan tunggal) | 200 OK | Memperbarui sumber daya yang cocok. |
| Sumber daya dengan ID yang ada (konflik terdeteksi) | 409 Konflik | Mengembalikan kesalahan. Tidak ada perubahan yang dibuat. |
| Sumber daya dengan ID yang ada (ketidakcocokan ID) | 400 Permintaan Buruk | Mengembalikan kesalahan. Tidak ada perubahan yang dibuat. |
| Beberapa kondisi pencocokan sumber daya | 412 Prasyarat Gagal | Mengembalikan kesalahan. Tidak ada perubahan yang dibuat. |
Dalam contoh bundel berikut dengan pembaruan bersyarat, `Patient` sumber daya dengan ID FHIR `476` diperbarui hanya jika kondisi `_lastUpdated=lt2025-04-20` terpenuhi.
```
{
"resourceType": "Bundle",
"id": "bundle-batch",
"meta": {
"lastUpdated": "2014-08-18T01:43:30Z"
},
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "476",
"meta": {
"lastUpdated": "2022-06-03T17:53:36.724Z"
},
"active": true,
"name": [
{
"use": "official",
"family": "Jackson",
"given": [
"Mateo",
"James"
]
}
],
"gender": "male",
"birthDate": "1974-12-25"
},
"request": {
"method": "PUT",
"url": "Patient?_id=476&_lastUpdated=lt2025-04-20"
}
},
{
"resource": {
"resourceType": "Medication",
"id": "med0310",
"contained": [
{
"resourceType": "Substance",
"id": "sub03",
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "55452001",
"display": "Oxycodone (substance)"
}
]
}
}
],
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "430127000",
"display": "Oral Form Oxycodone (product)"
}
]
},
"form": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "385055001",
"display": "Tablet dose form (qualifier value)"
}
]
},
"ingredient": [
{
"itemReference": {
"reference": "#sub03"
},
"strength": {
"numerator": {
"value": 5,
"system": "http://unitsofmeasure.org",
"code": "mg"
},
"denominator": {
"value": 1,
"system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
"code": "TAB"
}
}
}
]
},
"request": {
"method": "POST",
"url": "Medication"
}
}
]
}
```
## Menggabungkan sumber daya FHIR sebagai satu kesatuan
**Untuk menggabungkan sumber daya FHIR sebagai satu kesatuan**
1. Kumpulkan HealthLake `region` dan `datastoreId` nilai. Untuk informasi selengkapnya, lihat [Mendapatkan properti penyimpanan data](managing-data-stores-describe.md).
1. Buat URL untuk permintaan menggunakan nilai yang dikumpulkan untuk HealthLake `region` dan`datastoreId`. Sertakan jenis sumber daya FHIR `Bundle` sebagai bagian dari URL. Untuk melihat seluruh jalur URL dalam contoh berikut, gulir ke atas tombol **Salin**.
```
POST https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Bundle
```
1. Membangun badan JSON untuk permintaan, menentukan sumber daya FHIR untuk dikelompokkan bersama. Contoh berikut mengelompokkan dua `Patient` sumber daya di HealthLake. Untuk tujuan prosedur ini, simpan file sebagai`batch-single.json`.
```
{
"resourceType": "Bundle",
"id": "bundle-minimal",
"language": "en-US",
"identifier": {
"system": "urn:oid:1.2.3.4.5",
"value": "28b95815-76ce-457b-b7ae-a972e527db4f"
},
"type": "document",
"timestamp": "2020-12-11T14:30:00+01:00",
"entry": [
{
"fullUrl": "urn:uuid:f40b07e3-37e8-48c3-bf1c-ae70fe12dabf",
"resource": {
"resourceType": "Composition",
"id": "f40b07e3-37e8-48c3-bf1c-ae70fe12dabf",
"status": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "60591-5",
"display": "Patient summary Document"
}
]
},
"date": "2020-12-11T14:30:00+01:00",
"author": [
{
"reference": "urn:uuid:45271f7f-63ab-4946-970f-3daaaa0663ff"
}
],
"title": "Patient Summary as of December 7, 2020 14:30"
}
},
{
"fullUrl": "urn:uuid:45271f7f-63ab-4946-970f-3daaaa0663ff",
"resource": {
"resourceType": "Practitioner",
"id": "45271f7f-63ab-4946-970f-3daaaa0663ff",
"active": true,
"name": [
{
"family": "Doe",
"given": [
"John"
]
}
]
}
}
]
}
```
1. Kirim permintaan . Jenis `Bundle` dokumen FHIR menggunakan `POST` permintaan dengan protokol penandatanganan [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Contoh kode berikut menggunakan alat baris `curl` perintah untuk tujuan demonstrasi.
------
#### [ SigV4 ]
Otorisasi SiGv4
```
curl --request POST \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Bundle' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "{{$AWS_ACCESS_KEY_ID}}:{{$AWS_SECRET_ACCESS_KEY}}" \
--header "x-amz-security-token:{{$AWS_SESSION_TOKEN}}" \
--header 'Accept: application/json' \
--data @document-type.json
```
------
#### [ SMART on FHIR ]
SMART pada contoh otorisasi FHIR untuk tipe [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)data.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
Penelepon dapat menetapkan izin di lambda otorisasi. Untuk informasi selengkapnya, lihat [OAuth 2.0 cakupan](reference-smart-on-fhir-oauth-scopes.md).
------
Server mengembalikan respons yang menunjukkan dua `Patient` sumber daya yang dibuat sebagai hasil dari permintaan jenis `Bundle` dokumen.
## Mengkonfigurasi tingkat validasi untuk bundel
Saat menggabungkan sumber daya FHIR, Anda dapat menentukan header `x-amzn-healthlake-fhir-validation-level` HTTP secara opsional untuk mengonfigurasi tingkat validasi sumber daya. Tingkat validasi ini akan ditetapkan untuk semua permintaan buat dan perbarui dalam bundel. AWS HealthLake saat ini mendukung tingkat validasi berikut:
+ `strict`: Sumber daya divalidasi sesuai dengan elemen profil sumber daya, atau spesifikasi R4 jika tidak ada profil. Ini adalah tingkat validasi default untuk AWS HealthLake.
+ `structure-only`: Sumber daya divalidasi terhadap R4, mengabaikan profil yang direferensikan.
+ `minimal`: Sumber daya divalidasi minimal, mengabaikan aturan R4 tertentu. Sumber daya yang gagal dalam pemeriksaan struktur yang diperlukan search/analytics akan diperbarui untuk menyertakan peringatan untuk audit.
Sumber daya yang dibundel dengan tingkat validasi minimal dapat dicerna ke dalam Datastore meskipun validasi gagal diperlukan untuk pengindeksan pencarian. Dalam hal ini, sumber daya akan diperbarui untuk menyertakan ekstensi khusus Healthlake untuk mendokumentasikan kegagalan tersebut, dan entri dalam respons Bundel akan mencakup OperationOutcome sumber daya sebagai berikut:
```
{
"resourceType": "Bundle",
"type": "batch-response",
"timestamp": "2025-08-25T22:58:48.846287342Z",
"entry": [
{
"response": {
"status": "201",
"location": "Patient/195abc49-ba8e-4c8b-95c2-abc88fef7544/_history/1",
"etag": "W/\"1\"",
"lastModified": "2025-08-25T22:58:48.801245445Z",
"outcome": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"details": {
"text": "FHIR resource in payload failed FHIR validation rules."
},
"diagnostics": "FHIR resource in payload failed FHIR validation rules."
}
]
}
}
}
]
}
```
Selain itu, header respons HTTP berikut akan disertakan dengan nilai “true”:
```
x-amzn-healthlake-validation-issues : true
```
**catatan**
Perhatikan bahwa data yang dicerna yang cacat menurut spesifikasi R4 mungkin tidak dapat dicari seperti yang diharapkan jika kesalahan ini ada.
## Dukungan terbatas untuk “pesan” tipe Bundle
HealthLake memberikan dukungan terbatas untuk jenis FHIR Bundle `message` melalui proses konversi internal. Dukungan ini dirancang untuk skenario di mana bundel pesan tidak dapat diformat ulang di sumbernya, seperti menelan umpan ADT (Admission, Discharge, Transfer) dari sistem rumah sakit lama.
**Awas**
Fitur ini memerlukan daftar izin AWS akun eksplisit dan tidak memberlakukan semantik pesan FHIR R4 atau integritas referensial. Hubungi AWS Support untuk meminta pengaktifan akun Anda sebelum menggunakan bundel pesan.
### Perbedaan utama dari pemrosesan pesan standar
+ **Bundel Pesan** (spesifikasi FHIR): Entri pertama harus berupa referensi sumber `MessageHeader` daya lain. Sumber daya tidak memiliki `request` objek individu, dan MessageHeader acara menentukan tindakan pemrosesan.
+ **HealthLake Pemrosesan**: Mengonversi Bundel pesan ke Bundel batch dengan secara otomatis menetapkan operasi PUT ke setiap entri sumber daya. Sumber daya diproses secara independen tanpa menegakkan semantik pesan atau integritas referensial.
### Keterbatasan penting
+ Aturan pemrosesan khusus pesan FHIR R4 tidak diberlakukan
+ Tidak ada integritas transaksional di seluruh sumber daya
+ Referensi antar sumber daya tidak divalidasi
+ Memerlukan daftar izin akun eksplisit
### Contoh struktur Bundle pesan
```
{
"resourceType": "Bundle",
"type": "message",
"entry": [
{
"resource": {
"resourceType": "MessageHeader",
"eventCoding": {
"system": "http://hl7.org/fhir/us/davinci-alerts/CodeSystem/notification-event",
"code": "notification-admit"
},
"focus": [{"reference": "Encounter/example-id"}]
}
},
{
"resource": {"resourceType": "Patient", "id": "example-id"}
},
{
"resource": {"resourceType": "Encounter", "id": "example-id"}
}
]
}
```
**catatan**
Setiap sumber daya disimpan secara independen seolah-olah diserahkan melalui operasi PUT individu. Jika semantik pesan FHIR lengkap atau validasi integritas referensial diperlukan, pra-proses Bundel pesan atau terapkan validasi tingkat aplikasi sebelum pengiriman.
## Transaksi bundel asinkron
AWS HealthLake mendukung `Bundle` tipe asinkron `transaction` yang memungkinkan Anda mengirimkan transaksi dengan hingga 500 sumber daya. Saat Anda mengirimkan transaksi asinkron, HealthLake antrean untuk diproses dan segera mengembalikan URL polling. Anda dapat menggunakan URL ini untuk memeriksa status dan mengambil respons. Ini mengikuti pola [bundel async FHIR](https://hl7.org/fhir/async-bundle.html).
**Kapan menggunakan transaksi asinkron**
+ Anda perlu mengirimkan lebih dari 100 sumber daya (batas sinkron) dalam satu transaksi.
+ Anda ingin menghindari pemblokiran aplikasi Anda sambil menunggu pemrosesan transaksi selesai.
+ Anda perlu memproses volume tinggi sumber daya terkait dengan throughput yang lebih baik.
**penting**
Hasil polling tersedia selama 90 hari setelah transaksi selesai. Setelah periode 90 hari ini, URL polling tidak lagi mengembalikan hasil. Rancang integrasi Anda untuk mengambil dan menyimpan hasil dalam jendela ini.
**catatan**
`Bundle`Tipe sinkron `transaction` terus mendukung hingga 100 sumber daya dan merupakan mode pemrosesan default. Jika Anda mengirimkan `Bundle` jenis `transaction` dengan lebih dari 100 sumber daya tanpa `Prefer: respond-async` header, HealthLake mengembalikan `422 Unprocessable Entity` kesalahan. Bundel dengan tipe tidak `batch` didukung untuk pemrosesan asinkron—hanya `Bundle` jenis yang `transaction` dapat dikirimkan secara asinkron (dengan hingga 500 operasi).
**catatan**
`PATCH`operasi dan kondisional tidak PUTs didukung dalam transaksi bundel asinkron.
### Mengirimkan transaksi asinkron
Untuk mengirimkan transaksi asinkron, kirim `POST` permintaan ke titik akhir penyimpanan data dengan header. `Prefer: respond-async` Bundel harus memiliki tipe`transaction`. Bundel dengan tipe tidak `batch` didukung untuk pemrosesan bundel asinkron.
HealthLake melakukan validasi awal untuk bundel pada waktu pengiriman. Jika validasi berhasil, HealthLake mengembalikan HTTP 202 Diterima dengan header `content-location` respons yang berisi URL polling.
**Untuk mengirimkan tipe asinkron `Bundle` `transaction`**
1. Kirim `POST` permintaan ke titik akhir penyimpanan HealthLake data.
```
POST https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/
```
1. Buat badan JSON untuk permintaan dengan tipe bundel. `transaction` Untuk tujuan prosedur ini, simpan file sebagai`async-transaction.json`.
```
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"resource": {
"resourceType": "Patient",
"active": true,
"name": [
{
"use": "official",
"family": "Smith",
"given": ["Jane"]
}
],
"gender": "female",
"birthDate": "1990-01-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Observation",
"status": "final",
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "85354-9",
"display": "Blood pressure panel"
}
]
},
"subject": {
"reference": "urn:uuid:example-patient-id"
}
},
"request": {
"method": "POST",
"url": "Observation"
}
}
]
}
```
1. Kirim permintaan dengan `Prefer: respond-async` header. Jenis `Bundle` transaksi FHIR menggunakan `POST` permintaan dengan [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) atau SMART pada otorisasi FHIR. Contoh kode berikut menggunakan alat baris `curl` perintah untuk tujuan demonstrasi.
------
#### [ SigV4 ]
Otorisasi SiGv4
```
curl --request POST \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "{{$AWS_ACCESS_KEY_ID}}:{{$AWS_SECRET_ACCESS_KEY}}" \
--header "x-amz-security-token:{{$AWS_SESSION_TOKEN}}" \
--header 'Accept: application/json' \
--header 'Prefer: respond-async' \
--data @async-transaction.json
```
------
#### [ SMART on FHIR ]
SMART pada contoh otorisasi FHIR untuk tipe [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)data.
```
{
"AuthorizationStrategy": "SMART_ON_FHIR",
"FineGrainedAuthorizationEnabled": true,
"IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name",
"Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}"
}
```
Penelepon dapat menetapkan izin di lambda otorisasi. Untuk informasi selengkapnya, lihat [OAuth 2.0 cakupan](reference-smart-on-fhir-oauth-scopes.md).
------
1. Pada pengiriman yang berhasil, server mengembalikan HTTP 202 Diterima. Header `content-location` respon berisi URL polling. Badan respons adalah sumber `OperationOutcome` daya.
```
HTTP/1.1 202 Accepted
content-location: https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Transaction/{{transactionId}}
```
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Submitted Asynchronous Bundle Transaction",
"location": [
"https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Transaction/{{transactionId}}"
]
}
]
}
```
### Polling untuk status transaksi
Setelah Anda mengirimkan transaksi asinkron, gunakan URL polling dari header `content-location` respons untuk memeriksa status transaksi. Kirim `GET` permintaan ke URL polling.
**catatan**
Untuk SMART pada penyimpanan data yang diaktifkan FHIR, token otorisasi harus menyertakan `read` izin pada jenis `Transaction` sumber daya untuk melakukan polling untuk status transaksi. Untuk informasi lebih lanjut tentang SMART pada cakupan FHIR, lihat. [SMART pada cakupan FHIR OAuth 2.0 didukung oleh HealthLake](reference-smart-on-fhir-oauth-scopes.md)
Kirim `GET` permintaan ke URL polling. Contoh berikut menggunakan alat baris `curl` perintah.
------
#### [ SigV4 ]
Otorisasi SiGv4
```
curl --request GET \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Transaction/{{transactionId}}' \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "{{$AWS_ACCESS_KEY_ID}}:{{$AWS_SECRET_ACCESS_KEY}}" \
--header "x-amz-security-token:{{$AWS_SESSION_TOKEN}}" \
--header 'Accept: application/json'
```
------
#### [ SMART on FHIR ]
SMART pada otorisasi FHIR. Token otorisasi harus menyertakan `read` izin pada jenis `Transaction` sumber daya.
```
curl --request GET \
'https://healthlake.{{region}}.amazonaws.com/datastore/{{datastoreId}}/r4/Transaction/{{transactionId}}' \
--header 'Authorization: Bearer {{$SMART_ACCESS_TOKEN}}' \
--header 'Accept: application/json'
```
------
Tabel berikut menjelaskan kemungkinan tanggapan.
**Kode respons polling**
| Status HTTP | Arti | Isi respons |
| --- | --- | --- |
| 202 Diterima | Transaksi antri | OperationOutcomedengan diagnostik “DISERAHKAN” |
| 202 Diterima | Transaksi sedang diproses | OperationOutcomedengan diagnostik “IN\_PROGRESS” |
| 200 OK | Transaksi berhasil diselesaikan | Bundledengan tipe transaction-response |
| 4xx/5xx | Transaksi gagal | OperationOutcomedengan detail kesalahan |
Contoh berikut menunjukkan setiap jenis respons.
**Transaksi antri (202)**
```
{
"resourceType": "OperationOutcome",
"id": "{{transactionId}}",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "SUBMITTED"
}
]
}
```
**Pemrosesan transaksi (202)**
```
{
"resourceType": "OperationOutcome",
"id": "{{transactionId}}",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "IN_PROGRESS"
}
]
}
```
**Transaksi selesai (200)**
```
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"response": {
"status": "201",
"location": "Patient/example-id/_history/1",
"etag": "W/\"1\"",
"lastModified": "2024-01-15T10:30:00.000Z"
}
},
{
"response": {
"status": "201",
"location": "Observation/example-id/_history/1",
"etag": "W/\"1\"",
"lastModified": "2024-01-15T10:30:00.000Z"
}
}
]
}
```
**Transaksi gagal (4xx/5xx)**
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "exception",
"diagnostics": "Transaction failed: conflict detected on resource Patient/example-id"
}
]
}
```
### Memproses pesanan
Jenis bundel asinkron diantrian tetapi tidak `transaction` diproses dalam urutan pengiriman yang ketat. HealthLake mengoptimalkan pemrosesan berdasarkan kapasitas yang tersedia dan beban sistem.
**penting**
Jangan bergantung pada transaksi yang diproses sesuai urutan yang diajukan. Misalnya, jika Anda mengirimkan Transaksi A pada pukul 10:00 dan Transaksi B pukul 10:01, Transaksi B mungkin selesai sebelum Transaksi A. Rancang aplikasi Anda ke:
Menangani out-of-order penyelesaian.
Gunakan URL polling untuk melacak setiap transaksi secara independen.
Terapkan pengurutan tingkat aplikasi jika urutan penting untuk kasus penggunaan Anda.
### Kuota dan pelambatan
Kuota dan batas tarif berikut berlaku untuk transaksi asinkron.
**Kuota transaksi asinkron**
| Kuota | Nilai | Dapat Disesuaikan |
| --- | --- | --- |
| Operasi maksimum per transaksi asinkron | 500 | Tidak |
| Transaksi tertunda maksimum per penyimpanan data | 500 | Ya |
+ Transaksi asinkron memiliki batas tarif API yang sama yang ditentukan di bawah. [Kuota layanan](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas)
+ Polling untuk status transaksi memiliki batas tarif API yang sama dengan operasi read (`GET`) pada sumber daya FHIR.
+ Jika batas transaksi yang tertunda tercapai, pengiriman berikutnya mengembalikan kesalahan hingga transaksi yang ada selesai.
### Penanganan kesalahan
Untuk bundel 'transaksi', semua sumber daya FHIR yang terkandung dalam bundel diproses sebagai operasi atom. Semua sumber daya dalam operasi harus berhasil, atau tidak ada operasi dalam bundel yang diproses.
Kesalahan terbagi dalam dua kategori: kesalahan pengiriman yang HealthLake kembali secara sinkron, dan kesalahan pemrosesan yang Anda ambil melalui polling.
**Kesalahan pengiriman**
HealthLake memvalidasi bundel pada waktu pengiriman dan mengembalikan kesalahan secara serempak sebelum transaksi antri. Kesalahan pengiriman mencakup kesalahan validasi sumber daya FHIR yang tidak valid, jenis sumber daya yang tidak didukung, melebihi batas operasi 500, dan menggunakan header dengan bundel batch. `Prefer: respond-async` Jika batas transaksi yang tertunda untuk penyimpanan data telah tercapai, HealthLake kembalikan a`ThrottlingException`. Ketika kesalahan pengiriman terjadi, transaksi tidak akan antri.
**Kesalahan pemrosesan**
Kesalahan pemrosesan terjadi setelah transaksi telah antri dan dikembalikan melalui URL polling. Ini termasuk konflik transaksi, di mana operasi lain memodifikasi sumber daya yang merupakan bagian dari transaksi, dan kesalahan server selama pemrosesan. Ketika kesalahan pemrosesan terjadi, tidak ada mutasi sumber daya yang dilakukan untuk sumber daya dalam transaksi. URL polling akan mengembalikan `OperationOutcome` dengan rincian kesalahan.