다음을 통해 공유

Azure API for FHIR에 대한 FHIR REST API 기능

  • 아티클

Important

Azure API for FHIR은 2026년 9월 30일에 사용 중지됩니다. 마이그레이션 전략에 따라 해당 날짜까지 Azure Health Data Services FHIR 서비스로 전환합니다. Azure API for FHIR의 사용 중지로 인해 2025년 4월 1일부터 신규 배포가 허용되지 않습니다. Azure Health Data Services FHIR 서비스는 고객이 다른 Azure 서비스에 통합된 FHIR, DICOM 및 MedTech 서비스를 관리할 수 있도록 하는 FHIR용 Azure API의 진화된 버전입니다.

이 문서에서는 Azure API for FHIR의 RESTful 상호 작용에 대한 몇 가지 뉘앙스를 설명합니다.

조건부 만들기/업데이트

Azure API for FHIR은 FHIR 사양에 정의된 대로 만들기, 조건부 만들기, 업데이트 및 조건부 업데이트를 지원합니다. 이러한 시나리오에서 유용한 헤더 중 하나는 If-Match 헤더입니다. If-Match 헤더가 사용되며 업데이트하기 전에 업데이트되는 버전의 유효성을 검사합니다. ETag가 예상 ETag와 일치하지 않으면 오류 메시지 412 사전 조건 실패가 생성됩니다.

삭제 및 조건부 삭제

Azure API for FHIR은 두 가지 삭제 유형을 제공합니다. 하드 + 일시 삭제 및 조건부 삭제로도 알려진 삭제가 있습니다.

개별 리소스 ID 또는 대량으로 삭제를 수행할 수 있습니다. 리소스를 대량으로 삭제하는 방법에 대한 자세한 내용은 $대량 삭제 작업을 참조하세요.

삭제(하드 + 일시 삭제)

FHIR 사양에 정의된 삭제를 사용하려면 리소스를 삭제한 후 리소스의 후속 버전이 없는 특정 읽기에서 410 HTTP 상태 코드를 반환해야 합니다. 따라서 검색을 통해 리소스를 더 이상 찾을 수 없습니다. 또한 Azure API for FHIR을 사용하면 리소스를 완전히 삭제(모든 기록 포함)할 수 있습니다. 리소스를 완전히 삭제하기 위해 매개 변수 설정 hardDelete를 실제 (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true)에 전달할 수 있습니다. 이 매개 변수를 전달하지 않거나 hardDelete를 false로 설정하면 리소스의 기록 버전을 계속 사용할 수 있습니다.

참고 항목

기록만 삭제하려는 경우 Azure API for FHIR은 $purge-history라는 사용자 지정 작업을 지원합니다. 이 작업을 통해 리소스의 기록을 삭제할 수 있습니다.

조건부 삭제

조건부 삭제를 사용하면 검색 조건을 전달하여 리소스를 삭제할 수 있습니다. 기본적으로 조건부 삭제를 사용하면 한 번에 하나의 항목을 삭제할 수 있습니다. 한 번에 최대 100개 항목을 삭제하도록 _count 매개 변수를 지정할 수도 있습니다. 다음은 조건부 삭제를 사용하는 몇 가지 예입니다.

조건부 삭제를 사용하여 단일 항목을 삭제하려면 단일 항목을 반환하는 검색 조건을 지정해야 합니다.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704

동일한 검색을 수행할 수 있지만 hardDelete=true를 포함하여 모든 기록을 삭제할 수도 있습니다.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true

여러 리소스를 삭제하려면 _count=100 매개 변수를 포함합니다. 이 매개 변수는 검색 조건과 일치하는 리소스를 최대 100개까지 삭제합니다.

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100

삭제된 파일 복구

하드 삭제 매개 변수를 사용하지 않으면 Azure API for FHIR의 레코드가 여전히 존재합니다. 이 레코드는 리소스에 대한 기록 검색을 수행하고 데이터가 있는 마지막 버전을 검색하여 찾을 수 있습니다.

삭제된 리소스의 ID가 알려진 경우 다음 URL 패턴을 사용합니다.

<FHIR_URL>/<resource-type>/<resource-id>/_history

예: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history

리소스의 ID를 알 수 없는 경우 전체 리소스 종류에 대해 기록 검색을 수행합니다.

<FHIR_URL>/<resource-type>/_history

예: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history

복원하려는 레코드를 찾은 후 PUT 작업을 사용하여 동일한 ID로 리소스를 다시 만들거나 POST 작업을 사용하여 동일한 정보가 포함된 새 리소스를 만듭니다.

참고 항목

기록/일시 삭제 데이터에 대한 시간 기반 만료는 없습니다. 기록/일시 삭제된 데이터를 제거하는 유일한 방법은 하드 삭제 또는 제거 기록 작업을 사용하는 것입니다.

패치 및 조건부 패치

패치는 FHIR 리소스의 일부만 업데이트해야 하는 경우 중요한 RESTful 작업입니다. 패치를 사용하면 전체 레코드를 업데이트하지 않고도 리소스에서 업데이트할 요소를 지정할 수 있습니다. FHIR은 리소스를 패치하는 세 가지 방법인 JSON 패치, XML 패치 및 FHIRPath 패치를 정의합니다. FHIR 서비스는 조건부 JSON 패치 및 조건부 FHIRPath 패치(리소스 ID 대신 검색 조건에 따라 리소스를 패치할 수 있음)와 함께 JSON 패치 및 FHIRPath 패치를 모두 지원합니다. 몇 가지 예제를 진행하려면 각 방법에 대한 샘플 FHIRPath 패치 REST 파일 및 JSON 패치 REST 파일을 참조하세요. 자세한 내용은 FHIR을 사용한 패치 작업에 대한 HL7 설명서를 참조하세요.

참고 항목

STU3에 대해 PATCH를 사용할 때 기록 번들을 요청하는 경우 패치된 리소스의 Bundle.entry.request.method가 PUT에 매핑됩니다. 이는 STU3가 HTTPVerb 값 집합에 PATCH 동사에 대한 정의를 포함하지 않기 때문입니다.

FHIRPath 패치를 사용하여 패치

이 패치 방법은 대상으로 지정할 요소를 선택하는 데 FHIRPath를 활용하기 때문에 가장 강력합니다. 일반적인 시나리오 중 하나는 목록의 순서를 알지 못한 상태로 HIRPath 패치를 사용하여 목록의 요소를 업데이트하는 것입니다. 예를 들어 인덱스를 알지 못한 상태로 환자의 홈 통신 정보를 삭제하려는 경우 아래 예제를 사용할 수 있습니다.

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Content-type: application/fhir+json

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "operation",
            "part": [
                {
                    "name": "type",
                    "valueCode": "delete"
                },
                {
                    "name": "path",
                    "valueString": "Patient.telecom.where(use = 'home')"
                }
            ]
        }
    ]
}

모든 FHIRPath 패치 작업에는 application/fhir+json Content-Type 헤더 집합이 있어야 합니다. FHIRPatch 패치는 추가, 삽입, 삭제, 제거 및 이동 작업을 지원합니다. FHIRPatch 패치 작업을 번들에 쉽게 통합할 수도 있습니다. 자세한 예제는 샘플 FHIRPath 패치 REST 파일을 참조하세요.

JSON 패치를 사용하여 패치

FHIR 서비스의 JSON 패치는 IETF(Internet Engineering Task Force)에서 정의한 잘 사용되는 사양을 준수합니다. 페이로드 형식은 FHIR 리소스를 사용하지 않고 대신 요소 선택에 JSON 포인터를 활용하는 JSON 문서를 사용합니다. JSON 패치는 더 간결하며 패치를 수행하기 전에 조건이 충족되는지 확인할 수 있는 테스트 작업이 있습니다. 예를 들어 환자가 고인으로 아직 표시되지 않은 경우에만 사망으로 설정하려는 경우 아래 예제를 사용할 수 있습니다.

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Content-type: application/json-patch+json

[
	{
		"op": "test",
		"path": "/deceasedBoolean",
		"value": false
	},
	{
		"op": "replace",
		"path": "/deceasedBoolean",
		"value": true
	}
]

모든 JSON 패치 작업에는 application/json-patch+json Content-Type 헤더 집합이 있어야 합니다. JSON 패치는 추가, 제거, 바꾸기, 복사, 이동 및 테스트 작업을 지원합니다. 자세한 예제는 샘플 JSON 패치 REST 파일을 참조하세요.

번들의 JSON 패치

기본적으로 JSON 패치는 번들 리소스에서 지원되지 않습니다. 이는 번들이 FHIR 리소스만 사용하여 지원하고 JSON 패치 페이로드는 FHIR 리소스가 아니기 때문입니다. 이 문제를 해결하려면 Content-Type "application/json-patch+json"과 함께 이진 리소스를 사용하고 번들 내에서 JSON 페이로드의 base64 인코딩을 사용합니다. 이 해결 방법에 대한 자세한 내용은 FHIR Chat Zulip에 대한 이 항목을 참조하세요.

아래 예제에서는 환자의 성별을 여성으로 변경하려고 합니다. JSON 패치 [{"op":"replace","path":"/gender","value":"female"}]을 가져와 base64로 인코딩했습니다.

POST https://{FHIR-SERVICE-HOST-NAME}/
Content-Type: application/json

{
	"resourceType": "Bundle",
	"id": "bundle-batch",
	"type": "batch",
	"entry": [
		{
			"fullUrl": "Patient/{PatientID}",
			"resource": {
				"resourceType": "Binary",
				"contentType": "application/json-patch+json",
				"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
			},
			"request": { 
				"method": "PATCH",
				"url": "Patient/{PatientID}"
			}
		}
	]
}

조건부 작업을 사용한 성능 고려 사항

조건부 상호 작용은 복잡하고 성능이 많이 사용될 수 있습니다. 조건부 상호 작용과 관련된 쿼리의 대기 시간을 향상시키기 위해 요청 헤더 x-conditionalquery-processing-logic을 활용하는 옵션이 있습니다. 이 헤더를 병렬로 설정하면 조건부 상호 작용을 사용하여 쿼리를 동시에 실행할 수 있습니다.

다음 단계

이 문서에서는 Azure API for FHIR의 REST 기능 중 일부에 대해 알아보았습니다. 다음으로, FHIR에서 리소스 검색의 주요 측면에 대해 자세히 알아볼 수 있습니다.

Azure API for FHIR의 검색 개요

(FHIR®)은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.