FHIR 검색 개요
FHIR®(Fast Healthcare Interoperability Resources) 사양은 FHIR 서버 데이터베이스에서 리소스를 쿼리하기 위한 API를 정의합니다. 이 문서에서는 FHIR에서 데이터 쿼리의 주요 측면을 안내합니다. FHIR 검색 API에 대한 자세한 내용은 HL7 FHIR 검색 설명서를 참조하세요.
이 문서에서는 FHIR 서버 URL을 나타내는 자리 표시자를 사용하여 API 호출 {{FHIR_URL}} 예제에서 FHIR 검색 구문을 보여 줍니다. FHIR 서비스가 Azure Health Data Services에 있는 경우 이 URL은 다음과 같습니다 https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.
FHIR 검색은 FHIR 서버 데이터베이스의 특정 리소스 종류, 지정된 구획 또는 모든 리소스에 대해 검색할 수 있습니다. FHIR에서 검색을 실행하는 가장 간단한 방법은 요청을 사용하는 GET 것입니다. 예를 들어 데이터베이스의 모든 Patient 리소스를 끌어오려면 다음 요청을 사용할 수 있습니다.
GET {{FHIR_URL}}/Patient
를 사용하여 POST검색할 수도 있습니다. 검색을 사용 POST하려면 검색 매개 변수가 요청 본문에 전달됩니다. 이렇게 하면 더 길고 복잡한 일련의 매개 변수를 사용하여 쿼리를 더 쉽게 보낼 수 있습니다.
POST 검색 요청이 성공하면 검색에서 반환된 리소스 인스턴스가 포함된 FHIR searchset 번들을 받습니다GET. 검색에 실패하면 응답에서 OperationOutcome 오류 세부 정보를 찾을 수 있습니다.
다음 섹션에서는 FHIR에서 리소스 쿼리의 다양한 측면을 다룹니다. 이러한 항목을 검토한 후에는 다양한 FHIR 검색 방법의 예제를 제공하는 FHIR 검색 샘플 페이지를 참조하세요.
검색 매개 변수
FHIR에서 검색을 수행하는 경우 데이터베이스에서 특정 조건과 일치하는 리소스를 검색합니다. FHIR API는 검색 조건을 미세 조정하기 위한 다양한 검색 매개 변수 집합을 지정합니다. FHIR의 각 리소스는 정보를 요소 집합으로 전달하며 검색 매개 변수는 이러한 요소의 정보를 쿼리하기 위해 작동합니다. FHIR 검색 API 호출에서 요청의 검색 매개 변수와 리소스 인스턴스에 저장된 해당 요소 값 간에 양수 일치가 발견되면 FHIR 서버는 요소가 검색 조건을 충족하는 리소스 인스턴스가 포함된 번들을 반환합니다.
각 검색 매개 변수에 대해 FHIR 사양은 사용할 수 있는 데이터 형식을 정의합니다. 다양한 데이터 형식에 대한 FHIR 서비스의 지원은 아래에 설명되어 있습니다.
| 검색 매개 변수 유형 | Azure Health Data Services의 FHIR 서비스 | FHIR용 Azure API | Comment(설명) |
|---|---|---|---|
| 번호 | 예 | 예 | |
| date | 예 | 예 | |
| string | Yes | 예 | |
| token | 예 | 예 | |
| reference | 예 | 예 | |
| 복합 | 부분 | 부분 | 지원되는 복합 형식 목록은 이 문서에 나와 있습니다. |
| quantity | 예 | 예 | |
| uri | 예 | 예 | |
| 특별한 | 아니요 | 아니요 |
일반적인 검색 매개 변수
FHIR의 모든 리소스에 적용되는 일반적인 검색 매개 변수 가 있습니다. 이러한 항목은 FHIR 서비스에서의 지원과 함께 다음과 같이 나열됩니다.
| 일반 검색 매개 변수 | Azure Health Data Services의 FHIR 서비스 | FHIR용 Azure API | Comment(설명) |
|---|---|---|---|
_id |
예 | 예 | |
_lastUpdated |
예 | 예 | |
_tag |
예 | 예 | |
_type |
예 | 예 | |
_security |
예 | 예 | |
_profile |
예 | 예 | |
_has |
예 | 예 | |
_query |
아니요 | 아니요 | |
_filter |
아니요 | 아니요 | |
_list |
아니요 | 아니요 | |
_text |
아니요 | 아니요 | |
_content |
아니요 | 아니요 |
리소스별 매개 변수
Azure Health Data Services의 FHIR 서비스는 FHIR 사양에 정의된 거의 모든 리소스별 검색 매개 변수 를 지원합니다. 지원되지 않는 검색 매개 변수는 아래 링크에 나열됩니다.
다음 요청을 사용하여 FHIR 기능 문에서 검색 매개 변수에 대한 현재 지원을 볼 수도 있습니다.
GET {{FHIR_URL}}/metadata
기능 문에서 지원되는 검색 매개 변수를 보려면 리소스별 검색 매개 변수 및 CapabilityStatement.rest.searchParam 모든 리소스에 적용되는 검색 매개 변수로 이동합니다CapabilityStatement.rest.resource.searchParam.
참고 항목
Azure Health Data Services의 FHIR 서비스는 기본 FHIR 사양에 정의되지 않은 검색 매개 변수를 자동으로 인덱싱하지 않습니다. FHIR 서비스는 사용자 지정 검색 매개 변수를 지원합니다.
복합 검색 매개 변수
FHIR의 복합 검색을 사용하면 요소 쌍을 논리적으로 연결된 단위로 검색할 수 있습니다. 예를 들어 환자의 높이가 60인치를 초과하는 관찰을 검색하는 경우 관찰의 단일 속성에 높이 코드 와 60인치보다 큰 값이 포함되어 있는지 확인하려고 합니다(값은 높이에만 관련되어야 합니다). 예를 들어 높이 코드와 팔 길이 코드가 60인치를 넘는 관찰에서 양수 일치를 원하지 않을 수 있습니다. 복합 검색 매개 변수는 값이 모두 양수 일치가 발생하도록 검색 조건을 충족해야 하는 미리 지정된 요소 쌍을 검색하여 이 문제를 방지합니다.
Azure Health Data Services의 FHIR 서비스는 복합 검색에 대해 다음과 같은 검색 매개 변수 형식 페어링을 지원합니다.
- 참조, 토큰
- 토큰, 날짜
- 토큰, 숫자, 숫자
- 토큰, 수량
- 토큰, 문자열
- 토큰, 토큰
자세한 내용은 HL7 복합 검색 매개 변수 설명서를 참조하세요.
참고 항목
복합 검색 매개 변수는 FHIR 사양에 따라 한정자를 지원하지 않습니다.
한정자 및 접두사
한정자를 사용하면 추가 조건으로 검색 매개 변수를 한정할 수 있습니다. 다음은 FHIR 서비스에 대한 FHIR 한정자와 해당 지원의 표입니다.
| 한정자 | Azure Health Data Services의 FHIR 서비스 | FHIR용 Azure API | Comment(설명) |
|---|---|---|---|
:missing |
예 | 예 | |
:exact |
예 | 예 | |
:contains |
예 | 예 | |
:text |
예 | 예 | |
:type (참조) |
예 | 예 | |
:not |
예 | 예 | |
:below (uri) |
예 | 예 | |
:above (uri) |
예 | 예 | |
:in (토큰) |
아니요 | 아니요 | |
:below (토큰) |
아니요 | 아니요 | |
:above (토큰) |
아니요 | 아니요 | |
:not-in (토큰) |
아니요 | 아니요 | |
:identifier |
아니요 | 아니요 |
특정 순서(숫자, 날짜 및 수량)가 있는 검색 매개 변수의 경우 매개 변수 값 앞에 접두사를 사용하여 검색 조건을 구체화할 수 있습니다(예Patient?_lastUpdated=gt2022-08-01: 접두사는 gt "보다 큼"을 의미함). Azure Health Data Services의 FHIR 서비스는 FHIR 표준에 정의된 모든 접두사를 지원합니다.
검색 결과 매개 변수
FHIR은 검색에서 반환된 정보를 관리하는 데 도움이 되는 검색 결과 매개 변수 집합을 지정합니다. FHIR에서 검색 결과 매개 변수를 사용하는 방법에 대한 자세한 내용은 HL7 웹 사이트를 참조하세요. 다음은 FHIR 검색 결과 매개 변수 및 FHIR 서비스에서의 지원 표입니다.
| 검색 결과 매개 변수 | Azure Health Data Services의 FHIR 서비스 | FHIR용 Azure API | Comment(설명) |
|---|---|---|---|
_elements |
예 | 예 | |
_count |
예 | 예 | _count 는 1000개의 리소스로 제한됩니다. 1000보다 높게 설정된 경우 1000개만 반환되고 번들에 경고가 포함됩니다. |
_include |
예 | 예 | 검색된 _include 항목은 100으로 제한됩니다. _include Azure Cosmos DB의 PaaS 및 OSS에서는 지원 :iterate 되지 않습니다(#2137). |
_revinclude |
예 | 예 | 검색된 _revinclude 항목은 100으로 제한됩니다. _revinclude Azure Cosmos DB의 PaaS 및 OSS에서는 지원 :iterate 되지 않습니다(#2137). 잘못된 요청에 대한 잘못된 상태 코드도 있습니다. #1319. |
_summary |
예 | 예 | |
_total |
부분 | 부분 | _total=none 및 _total=accurate |
_sort |
부분 | 부분 | sort=_lastUpdated 는 FHIR 서비스에서 지원됩니다. FHIR 서비스 및 OSS SQL DB FHIR 서버의 경우 문자열 및 dateTime 필드를 기준으로 정렬이 지원됩니다. 2021년 4월 20일 이후에 만든 Azure API for FHIR 및 OSS Azure Cosmos DB 데이터베이스의 경우 이름, 성, 생년월일 및 임상 날짜에 정렬이 지원됩니다. |
_contained |
아니요 | 아니요 | |
_containedType |
아니요 | 아니요 | |
_score |
아니요 | 아니요 |
고:
- 기본적으로
_sort레코드를 오름차순으로 정렬합니다. 접두-사를 사용하여 내림차순으로 정렬할 수도 있습니다. FHIR 서비스를 사용하면 한 번에 하나의 필드에만 정렬할 수 있습니다. - FHIR 서비스는 revinclude를 사용하여 와일드카드 검색을 지원합니다. revinclude 쿼리에 "." 쿼리 매개 변수를 추가하면 FHIR 서비스가 원본 리소스에 매핑된 모든 리소스를 참조하도록 지시합니다.
기본적으로 Azure Health Data Services의 FHIR 서비스는 관대한 처리로 설정됩니다. 즉, 서버는 알 수 없거나 지원되지 않는 매개 변수를 무시합니다. 엄격한 처리를 사용하려는 경우 헤더를 Prefer 포함하고 설정할 handling=strict수 있습니다.
연결된 검색 및 역방향 연결 검색
연결된 검색을 사용하면 다른 리소스에 대한 참조가 있는 리소스에 대해 세부 대상 쿼리를 수행할 수 있습니다. 예를 들어 환자의 이름이 Jane인 경우를 찾으려면 다음을 사용합니다.
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
. 위의 요청에서 연결된 검색의 경로를 대상 매개 변수(name이 경우)로 조정합니다.
마찬가지로 매개 변수를 사용하여 역방향 체인 검색을 _has 수행할 수 있습니다. 이렇게 하면 관심 있는 리소스를 참조하는 다른 리소스에 대한 조건을 지정하여 리소스 인스턴스를 검색할 수 있습니다. 연결 및 역방향 체인 검색의 예는 FHIR 검색 예제 페이지를 참조 하세요 .
페이지 매김
앞에서 설명한 대로 FHIR 검색의 결과는 번들에 제공된 searchset 링크에서 페이지를 매긴 형태로 사용할 수 있습니다. 기본적으로 FHIR 서비스는 페이지당 10개의 검색 결과를 표시하지만 매개 변수를 설정 _count 하여 늘리거나 줄일 수 있습니다. 한 페이지에 맞는 것보다 더 많은 일치 항목이 있는 경우 번들에는 링크가 next 포함됩니다. 링크에서 반복적으로 페치하면 next 결과의 후속 페이지가 생성됩니다. 매개 변수 값은 _count 1000을 초과할 수 없습니다.
현재 Azure Health Data Services의 FHIR 서비스는 링크만 지원 next 하며 검색에서 반환된 번들의 링크 또는 previous 링크를 지원하지 lastfirst않습니다.
FAQ
R4 지원되지 않는 검색 매개 변수에서 "부분 지원"은 무엇을 의미하나요?
리소스별 검색 매개 변수 중 일부는 둘 이상의 데이터 형식을 포함하며, Azure Health Data Services의 FHIR 서비스는 이러한 데이터 형식 중 하나에서만 해당 검색 매개 변수를 지원할 수 있습니다. 예를 들어 Condition-abatement-age 및 Condition-onset-age는 Age 및 Range라는 두 가지 데이터 형식을 다룹니다. 그러나 Azure Health Data Services의 FHIR 서비스는 Range에서 두 개의 검색 매개 변수를 지원하지만 Age에서는 지원하지 않습니다.
관찰에 대한 $lastn 작업이 지원되는가요?
이는 지원되지 않습니다. 다른 방법은 _count 사용하여 페이지당 반환되는 리소스를 제한하고 결과를 내림차순으로 제공하는 _sort 것입니다.
다음 단계
이제 FHIR 검색의 기본 사항에 대해 알아보았으므로 검색 매개 변수, 한정자 및 기타 FHIR 검색 방법을 사용하여 검색하는 방법에 대한 자세한 내용은 검색 샘플 페이지를 참조하세요.
참고 항목
FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.