Bundling sumber daya FHIR - AWS HealthLake
Bundel sebagai entitas independenBersyarat PUTs dalam BundelBundel sebagai entitas tunggalMengkonfigurasi tingkat validasi untuk bundel

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 yang berbeda: batchatau transaction.

  • Untuk bundel 'batch', setiap sumber daya FHIR yang terkandung dalam bundel diproses dan dicatat satu per satu. Setiap operasi sumber daya diperlakukan secara independen dari sumber daya lainnya.

  • 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 pembaruan sumber daya dalam bundel yang berkomitmen dan disimpan.

Anda dapat menggabungkan sumber daya FHIR dari jenis yang sama atau berbeda, dan mereka dapat menyertakan campuran interaksi FHIR lain yang ditentukan dalam Bab ini (misalnyacreate,,, read updatedelete, dansearch). Untuk informasi tambahan, lihat Bundel Sumber Daya dalam dokumentasi FHIR R4.

Perbedaan utama antara Batch dan Transaction type Bundle:

Batch

  • Operasi independen yang dapat berhasil atau gagal secara individual

  • Pemrosesan berlanjut bahkan jika beberapa operasi gagal

  • Urutan eksekusi tidak dijamin

  • Ideal untuk operasi massal di mana keberhasilan sebagian dapat diterima

Transaksi

  • Atomisitas dijamin - baik semua berhasil atau semuanya gagal

  • Mempertahankan integritas referensial untuk sumber daya yang direferensikan secara lokal (dalam Bundel)

  • Operasi diproses dalam urutan yang ditentukan

  • Gagal sepenuhnya jika ada operasi yang gagal

Contoh Kasus Penggunaan:

  • Batch: Mengunggah beberapa catatan pasien yang tidak terkait

  • Transaksi: Menciptakan pasien dengan pengamatan dan kondisi terkait di mana semua harus berhasil bersama

catatan

Keduanya menggunakan tipe sumber daya Bundel tetapi berbeda dalam bidang 'tipe':

{
  "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 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/

  3. 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 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 IdentityProviderConfigurationdata.

    {
    "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.

    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:

  • _id(mandiri)

  • _iddalam kombinasi dengan salah satu dari berikut ini:

    • _tag

    • _createdAt

    • _lastUpdated

Berdasarkan hasil pencocokan kondisi yang diberikan ke sumber daya yang ada, berikut ini akan terjadi dengan kode hasil terkait yang menunjukkan tindakan yang diambil:

Saat membuat atau memperbarui sumber daya FHIR, sistem menangani skenario yang berbeda berdasarkan penyediaan ID sumber daya dan kecocokan yang ada:

  • Sumber daya tanpa IDs selalu dibuat (201).

  • Sumber daya dengan IDs yang baru dibuat (201).

  • Sumber daya yang sudah IDs ada memperbarui sumber daya yang cocok (200) atau menampilkan kesalahan jika ada konflik (409) atau ketidakcocokan ID (400).

  • Beberapa sumber daya yang cocok memicu kegagalan prasyarat (419).

Dalam contoh Bundel dengan pembaruan bersyarat, sumber daya Pasien dengan ID FHIR hanya 456 akan diperbarui 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.

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

    {
    "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.

    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.