기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

FHIR 리소스 번들링

FHIRBundle은의 FHIR 리소스 모음을 위한 컨테이너입니다 AWS HealthLake.는 서로 다른 처리 동작을 가진 두 가지 유형의 번들을 AWS HealthLake 지원합니다.

Batch 번들은 각 리소스를 독립적으로 처리합니다. 리소스 하나가 실패하더라도 나머지 리소스는 여전히 성공할 수 있습니다. 각 작업은 개별적으로 처리되며 일부 작업이 실패하더라도 처리가 계속됩니다. 관련 없는 여러 환자 레코드를 업로드하는 등 부분적 성공이 허용되는 대량 작업에 배치 번들을 사용합니다.

Transaction 번들은 모든 리소스를 원자적으로 단일 단위로 처리합니다. 모든 리소스 작업이 성공하거나 커 AWS HealthLake 밋하지 않습니다. 모든 데이터를 함께 기록해야 하는 관련 관찰 및 조건이 있는 환자 생성과 같이 관련 리소스에서 참조 무결성을 보장해야 하는 경우 트랜잭션 번들을 사용합니다.

동일하거나 다른 유형의 FHIR 리소스를 번들링할 수 있으며, create, , read, 등의 FHIR 작업을 혼합하여 포함할 수 update delete있습니다patch. 자세한 내용은 FHIR R4 설명서의 리소스 번들을 참조하세요.

다음은 각 번들 유형에 대한 사용 사례의 예입니다.

다음 예제에서는 여러 리소스 유형 및 작업이 있는 트랜잭션 번들을 보여줍니다.

{
  "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"
      }
    }
  ]
}

FHIR 리소스를 독립 엔터티로 번들링

FHIR 리소스를 독립 엔터티로 번들링하려면

번들의 조건부 PUTs

AWS HealthLake 는 다음 쿼리 파라미터를 사용하여 번들 내에서 조건부 업데이트를 지원합니다.

번들에서 조건부 PUTs 사용하는 경우는 쿼리 파라미터를 기존 리소스와 비교하여 AWS HealthLake 평가하고 일치 결과를 기반으로 조치를 취합니다.

조건부 업데이트가 포함된 다음 번들 예제에서는 조건이 충족되는 경우에만 FHIR ID가 인 Patient 리소스_lastUpdated=lt2025-04-20가 476 업데이트됩니다.

{
    "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"
            }
        }
    ]
}

FHIR 리소스를 단일 엔터티로 번들링

FHIR 리소스를 단일 엔터티로 번들링하려면

번들에 대한 검증 수준 구성

FHIR 리소스를 번들링할 때 선택적으로 x-amzn-healthlake-fhir-validation-level HTTP 헤더를 지정하여 리소스에 대한 검증 수준을 구성할 수 있습니다. 이 검증 수준은 번들 내의 모든 생성 및 업데이트 요청에 대해 설정됩니다.는 AWS HealthLake 현재 다음 검증 수준을 지원합니다.

최소 검증 수준으로 번들링된 리소스는 검색 인덱싱에 필요한 검증에 실패하더라도 데이터 스토어에 수집될 수 있습니다. 이 경우 리소스는 해당 실패를 문서화하기 위한 Healthlake별 확장을 포함하도록 업데이트되며 번들 응답 내의 항목에는 다음과 같이 OperationOutcome 리소스가 포함됩니다.

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

또한 다음 HTTP 응답 헤더는 "true" 값과 함께 포함됩니다.

x-amzn-healthlake-validation-issues : true

번들 유형 "메시지"에 대한 제한된 지원

HealthLake는 내부 변환 프로세스를 message 통해 FHIR 번들 유형에 대한 제한된 지원을 제공합니다. 이 지원은 레거시 병원 시스템에서 ADT(Admission, Discharge, Transfer) 피드를 수집하는 등 소스에서 메시지 번들을 다시 포맷할 수 없는 시나리오를 위해 설계되었습니다.

표준 메시지 처리의 주요 차이점

중요 제한 사항

예제 메시지 번들 구조

{
              "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"}
                }
              ]
            }
            

비동기 번들 트랜잭션

AWS HealthLake 는 최대 500개의 리소스가 있는 트랜잭션을 제출할 수 transaction 있는 비동기 Bundle 유형을 지원합니다. 비동기 트랜잭션을 제출하면 HealthLake는 처리를 위해 이를 대기열에 넣고 즉시 폴링 URL을 반환합니다. 이 URL을 사용하여 상태를 확인하고 응답을 검색할 수 있습니다. 이는 FHIR 비동기 번들 패턴을 따릅니다.

비동기 트랜잭션을 사용해야 하는 경우

비동기 트랜잭션 제출

비동기 트랜잭션을 제출하려면 Prefer: respond-async 헤더를 사용하여 데이터 스토어 엔드포인트에 POST 요청을 보냅니다. 번들에는 유형이 있어야 합니다transaction. 유형의 번들batch은 비동기 번들 처리에 지원되지 않습니다.

HealthLake는 제출 시 번들에 대한 초기 검증을 수행합니다. 검증에 성공하면 HealthLake는 폴링 URL이 포함된 content-location 응답 헤더와 함께 HTTP 202 Accepted를 반환합니다.

비동기 Bundle 유형을 제출하려면 transaction

트랜잭션 상태에 대한 폴링

비동기 트랜잭션을 제출한 후 content-location 응답 헤더의 폴링 URL을 사용하여 트랜잭션 상태를 확인합니다. 폴링 URL에 GET 요청을 보냅니다.

폴링 URL에 GET 요청을 보냅니다. 다음 예제에서는 curl 명령줄 도구를 사용합니다.

SigV4

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

FHIR 권한 부여에 대한 SMART. 권한 부여 토큰에는 Transaction 리소스 유형에 대한 read 권한이 포함되어야 합니다.

curl --request GET \
  'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
  --header 'Authorization: Bearer $SMART_ACCESS_TOKEN' \
  --header 'Accept: application/json'

다음 표에서는 가능한 응답을 설명합니다.

다음 예제에서는 각 응답 유형을 보여줍니다.

트랜잭션 대기 중(202)

{
    "resourceType": "OperationOutcome",
    "id": "transactionId",
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "SUBMITTED"
        }
    ]
}

트랜잭션 처리(202)

{
    "resourceType": "OperationOutcome",
    "id": "transactionId",
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "IN_PROGRESS"
        }
    ]
}

트랜잭션 완료(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"
            }
        }
    ]
}

트랜잭션 실패(4xx/5xx)

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "exception",
            "diagnostics": "Transaction failed: conflict detected on resource Patient/example-id"
        }
    ]
}

주문 처리

유형의 비동기 번들transaction은 대기열에 있지만 엄격한 제출 순서로 처리되지 않습니다. HealthLake는 사용 가능한 용량 및 시스템 부하를 기반으로 처리를 최적화합니다.

할당량 및 제한

다음 할당량 및 속도 제한은 비동기 트랜잭션에 적용됩니다.

오류 처리

'트랜잭션' 번들의 경우 번들에 포함된 모든 FHIR 리소스는 원자성 작업으로 처리됩니다. 작업의 모든 리소스가 성공하거나 번들의 작업이 처리되지 않아야 합니다.

오류는 HealthLake가 동기적으로 반환하는 제출 오류와 폴링을 통해 검색하는 처리 오류의 두 가지 범주로 나뉩니다.

제출 오류

HealthLake는 제출 시 번들을 검증하고 트랜잭션이 대기열에 추가되기 전에 동기식으로 오류를 반환합니다. 제출 오류에는 잘못된 FHIR 리소스 검증 오류, 지원되지 않는 리소스 유형, 500개의 작업 제한 초과, 배치 번들과 함께 Prefer: respond-async 헤더 사용 등이 포함됩니다. 데이터 스토어에 대해 보류 중인 트랜잭션 한도에 도달하면 HealthLake는를 반환합니다ThrottlingException. 제출 오류가 발생하면 트랜잭션이 대기열에 추가되지 않습니다.

처리 오류

처리 오류는 트랜잭션이 대기열에 추가되고 폴링 URL을 통해 반환된 후에 발생합니다. 여기에는 다른 작업이 트랜잭션의 일부인 리소스를 수정한 트랜잭션 충돌과 처리 중 서버 오류가 포함됩니다. 처리 오류가 발생하면 트랜잭션의 리소스에 대해 리소스 변형이 수행되지 않습니다. 폴링 URL은 오류 세부 정보와 OperationOutcome 함께를 반환합니다.