View a markdown version of this page

Menggabungkan sumber daya FHIR - AWS HealthLake
Bundel sebagai entitas independenPUT bersyaratBundel sebagai entitas tunggalMengkonfigurasi tingkat validasi untuk bundelDukungan terbatas untuk “pesan” tipe BundleTransaksi asinkron

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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

Batchbundel memproses setiap sumber daya secara independen. Jika satu sumber daya gagal, sumber daya yang tersisa masih dapat 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.

Transactionbundel 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 integritas referensial terjamin di seluruh sumber daya terkait, seperti membuat pasien dengan pengamatan dan kondisi terkait di mana semua data harus dicatat bersama.

Perbedaan antara bundel batch dan 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. Diterapkan untuk sumber daya yang direferensikan secara lokal dalam bundel.
Paling baik digunakan untuk Operasi massal di mana keberhasilan parSIAL 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 updatedelete, dan. patch Untuk informasi tambahan, lihat Paket Sumber Daya 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 secara massal catatan pengobatan historis di mana beberapa catatan mungkin memiliki masalah validasi.

  • Muat data referensi, seperti organisasi dan praktisi, di mana kegagalan individu tidak mempengaruhi entri lain.

Bundel transaksi

  • Buat pasien dengan pengamatan dan kondisi terkait selama penerimaan gawat darurat di mana semua data harus dicatat 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.

  2. Buat URL untuk permintaan menggunakan nilai yang dikumpulkan untuk HealthLake region dandatastoreId. Jangan menentukan 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/

  3. Buat badan JSON untuk permintaan, menentukan setiap kata kerja HTTP sebagai bagian dari method elemen. Contoh berikut menggunakan interaksi batch tipe dengan Bundle sumber daya untuk membuat sumber daya baru Patient dan Medication sumber daya. Semua bagian yang diperlukan dikomentari sesuai. Untuk tujuan prosedur ini, simpan file sebagaibatch-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"
            }
        }
    ]
}

  4. Kirim permintaan . Jenis Bundle batch FHIR menggunakan POST permintaan dengan AWS Signature Version 4 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 IdentityProviderConfiguration 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 Cakupan OAuth 2.0.

    Server mengembalikan respons yang menunjukkan Medication sumber daya Patient dan yang dibuat sebagai hasil dari permintaan tipe Bundle batch.

PUT bersyarat dalam bundel

AWS HealthLake mendukung pembaruan bersyarat dalam bundel menggunakan parameter kueri berikut:

catatan

PUT bersyarat hanya didukung dalam batch bundel. Transactionbundel tidak mendukung PUT bersyarat.

  • _id(mandiri)

  • _iddalam kombinasi dengan salah satu dari berikut ini:

    • _tag

    • createdAt

    • _lastUpdated

Saat Anda menggunakan PUT bersyarat dalam bundel, AWS HealthLake mengevaluasi parameter kueri terhadap sumber daya yang ada dan mengambil tindakan berdasarkan hasil kecocokan.

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 dilakukan.
Sumber daya dengan ID yang ada (ketidakcocokan ID) 400 Permintaan Buruk Mengembalikan kesalahan. Tidak ada perubahan yang dilakukan.
Beberapa kondisi pencocokan sumber daya 412 Prasyarat Gagal Mengembalikan kesalahan. Tidak ada perubahan yang dilakukan.

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 entitas

Untuk menggabungkan sumber daya FHIR sebagai satu entitas

  1. Kumpulkan HealthLake region dan datastoreId nilai. Untuk informasi selengkapnya, lihat Mendapatkan properti penyimpanan data.

  2. Buat URL untuk permintaan menggunakan nilai yang dikumpulkan untuk HealthLake region dandatastoreId. 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

  3. Buat 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 sebagaibatch-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"
                        ]
                    }
                ]                
            }
        }
    ]
}

  4. Kirim permintaan . Jenis Bundle dokumen FHIR menggunakan POST permintaan dengan protokol penandatanganan AWS Signature Version 4. 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 IdentityProviderConfiguration 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 Cakupan OAuth 2.0.

    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 secara opsional menentukan header x-amzn-healthlake-fhir-validation-level HTTP untuk mengonfigurasi tingkat validasi untuk sumber daya. Tingkat validasi ini akan diatur untuk semua permintaan pembuatan dan pembaruan 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 yang ada. 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 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 ada kesalahan ini.

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 menerapkan semantik pesan FHIR R4 atau integritas referensial. Hubun AWS gi Dukungan untuk meminta pengaktifan akun Anda sebelum menggunakan bundel pesan.

Perbedaan utama dari pemrosesan pesan standar

  • Bundel Pesan (spesifikasi FHIR): Entri pertama harus mereferensi MessageHeader kan sumber daya lain. Sumber daya tidak request memiliki objek individu, dan MessageHeader peristiwa 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.

Batasan penting

  • Aturan Message-specific pemrosesan FHIR R4 tidak diberlakukan

  • Tidak ada integritas transaksional di seluruh sumber daya

  • Inter-resource referensi tidak divalidasi

  • Memerlukan daftar izin akun eksplisit

Contoh struktur bundel 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 dikirimkan melalui operasi PUT individu. Jika semantik pesan FHIR penuh 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 sumber daya hingga 500. Saat Anda mengirimkan transaksi asinkron, HealthLake mengantrekannya untuk diproses dan segera mengembalikan URL polling. Anda dapat menggunakan URL ini untuk memeriksa status dan mengambil respons. Ini mengikuti pola bundel async FHIR.

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 menampilkan hasil. Rancang integrasi Anda untuk mengambil dan menyimpan hasil dalam jendela ini.

catatan

Jenis sinkron Bundle transaction terus mendukung hingga 100 sumber daya dan merupakan mode pemrosesan default. Jika Anda mengirimkan Bundle tipe 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 tipe yang transaction dapat dikirimkan secara asinkron (dengan hingga 500 operasi).

catatan

PATCHoperasi dan PUT bersyarat tidak 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 tipetransaction. 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 Accepted dengan header content-location respons yang berisi URL polling.

Untuk mengirimkan transaksi jenis Bundel asinkro n

  1. Kirim POST permintaan ke titik akhir penyimpanan HealthLake data.

    POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/

  2. Buat badan JSON untuk permintaan dengan tipe bundeltransaction. Untuk tujuan prosedur ini, simpan file sebagaiasync-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"
            }
        }
    ]
}

  3. Kirim permintaan dengan Prefer: respond-async header. Jenis Bundle transaksi FHIR menggunakan POST permintaan dengan Tanda Tangan Versi AWS 4 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 IdentityProviderConfiguration 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 Cakupan OAuth 2.0.

  4. Pada pengiriman berhasil, server mengembalikan HTTP 202 Accepted. Header content-location respons berisi URL polling. Badan respons adalah OperationOutcome sumber 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 penyimpanan data yang diaktifkan SMART pada FHIR, token otorisasi harus menyertakan read izin pada jenis Transaction sumber daya untuk melakukan polling status transaksi. Untuk informasi lebih lanjut tentang SMART pada cakupan FHIR, lihatSMART pada cakupan FHIR OAuth 2.0 didukung oleh HealthLake.

Kirim GET permintaan ke URL polling. Contoh berikut menggunakan alat curl baris 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 diantri OperationOutcomedengan diagnostik “DIKIRIM”
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 mengantri (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"
        }
    ]
}

Pemrosesan pesanan

Bundel jenis asinkron transaction diantrean tetapi tidak diproses dalam urutan pengiriman yang ketat. HealthLake mengoptimalkan pemrosesan berdasarkan kapasitas yang tersedia dan beban sistem.

penting

Jangan bergantung pada transaksi yang diproses dalam urutan mereka dikirimkan. Misalnya, jika Anda mengirimkan Transaksi A pada pukul 10:00 pagi dan Transaksi B pukul 10:01 pagi, Transaksi B mungkin selesai sebelum Transaksi A. Rancang aplikasi Anda untuk:

  • Tangani penyelesaian yang tidak sesuai pesanan.

  • 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
Maksimum transaksi tertunda per penyimpanan data 500 Ya

  • Transaksi asinkron berbagi batas tarif API yang sama yang ditentukan di bawah. Kuota layanan

  • Polling untuk status transaksi berbagi 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 dibagi menjadi dua kategori: kesalahan pengiriman yang dikem HealthLake balikan secara serempak, dan kesalahan pemrosesan yang Anda ambil melalui polling.

Kesalahan pengajuan

HealthLake memvalidasi bundel pada waktu pengiriman dan mengembalikan kesalahan secara serempak sebelum transaksi diantri. Kesalahan pengiriman termasuk kesalahan validasi sumber daya FHIR yang tidak valid, jenis sumber daya yang tidak didukung, melebihi batas operasi 500, dan menggunakan Prefer: respond-async header dengan bundel batch. Jika batas transaksi tertunda untuk penyimpanan data telah tercapai, HealthLake mengembalikan aThrottlingException. Ketika kesalahan pengiriman terjadi, transaksi tidak akan diantri.

Kesalahan pemrosesan

Kesalahan pemrosesan terjadi setelah transaksi diantri 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 menampilkan OperationOutcome detail kesalahan.