다음을 통해 공유

Azure API for FHIR의 검색 개요

  • 아티클

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 서비스를 관리할 수 있도록 하는 Azure API for FHIR의 진화된 버전입니다.

FHIR®(Fast Healthcare Interoperability Resources) 사양은 FHIR 리소스 검색의 기본 사항을 정의합니다. 이 문서에서는 FHIR에서 리소스를 검색하는 몇 가지 주요 측면을 안내합니다. FHIR 리소스 검색에 대한 자세한 내용은 HL7 FHIR 사양의 검색을 참조하세요. 이 문서에서는 검색 구문의 예를 제공합니다. 각 검색은 일반적으로 URL https://<FHIRSERVERNAME>.azurewebsites.net이 있는 FHIR 서버에 대한 것입니다. 예제에서는 이 URL에 자리 표시자 {{FHIR_URL}}를 사용합니다.

FHIR 검색은 특정 리소스 종류, 지정된 구획 또는 모든 리소스에 대해 수행할 수 있습니다. FHIR에서 검색을 실행하는 가장 간단한 방법은 요청을 사용하는 GET 것입니다. 예를 들어 데이터베이스의 모든 환자를 끌어오려면 다음 요청을 사용할 수 있습니다.

GET {{FHIR_URL}}/Patient

쿼리 문자열이 긴 경우 유용한 를 사용하여 POST검색할 수도 있습니다. 검색 POST하려면 검색 매개 변수를 양식 본문으로 제출할 수 있습니다. 이렇게 하면 쿼리 문자열에서 보고 이해하기 어려울 수 있는 더 길고 복잡한 일련의 쿼리 매개 변수를 사용할 수 있습니다.

검색 요청이 성공하면 형식 searchset이 포함된 FHIR 번들 응답을 받게 됩니다. 검색에 실패하면 검색에 실패한 이유를 이해하는 데 도움이 되는 오류 세부 정보를 OperationOutcome 찾을 수 있습니다.

다음 섹션에서는 검색과 관련된 다양한 측면을 다룹니다. 이러한 세부 정보를 검토한 후에는 Azure API for FHIR에서 수행할 수 있는 검색 예제가 있는 샘플 페이지를 참조하세요.

검색 매개 변수

검색은 리소스의 다양한 특성을 기반으로합니다. 이러한 특성을 검색 매개 변수라고 합니다. 각 리소스에는 정의된 검색 매개 변수 집합이 있습니다. 검색 매개 변수를 성공적으로 검색하려면 데이터베이스에서 검색 매개 변수를 정의하고 인덱싱해야 합니다.

각 검색 매개 변수에는 정의된 데이터 형식이 있습니다. 다음 표에서는 다양한 데이터 형식에 대한 지원을 간략하게 설명합니다.

Warning

현재 연결된 검색과 함께 Azure API for FHIR을 사용할 _sort 때 문제가 있습니다. 자세한 내용은 오픈 소스 문제 #2344를 참조하세요. 이는 2021년 12월 릴리스 중에 해결될 예정입니다.

검색 매개 변수 유형 FHIR용 Azure API Azure Health Data Services의 FHIR 서비스 Comment(설명)
번호 예 예
date 예 예
string Yes 예
token 예 예
reference 예 예
복합 부분 부분 지원되는 복합 형식 목록은 이 문서의 뒷부분에 설명되어 있습니다.
quantity 예 예
uri 예 예
특별한 아니요 아니요

일반적인 검색 매개 변수

모든 리소스에 적용되는 일반적인 검색 매개 변수가 있습니다. 이러한 항목은 Azure API for FHIR 내의 지원과 함께 다음 목록에 나와 있습니다.

일반 검색 매개 변수 FHIR용 Azure API Azure Health Data Services의 FHIR 서비스 Comment(설명)
_id 예 예
_lastUpdated 예 예
_태그 예 예
_type 예 예
_안전 예 예
_윤곽 예 예
_has 부분 예 _has 지원은 Azure API for FHIR 및 Azure Cosmos DB에서 지원하는 OSS 버전의 MVP에 있습니다. 자세한 내용은 다음 연결 섹션에 포함되어 있습니다.
_쿼리 아니요 아니요
_필터 아니요 아니요
_목록 아니요 아니요
_문자 메시지 아니요 아니요
_콘텐츠 아니요 아니요

리소스별 매개 변수

Azure API for FHIR을 사용하면 FHIR 사양에 정의된 거의 모든 리소스별 검색 매개 변수 를 지원합니다. 지원되지 않는 유일한 검색 매개 변수는 다음 링크에서 사용할 수 있습니다.

다음 요청을 사용하여 FHIR 기능 문에서 검색 매개 변수에 대한 현재 지원을 볼 수도 있습니다.

GET {{FHIR_URL}}/metadata

capability 문 CapabilityStatement.rest.resource.searchParam 에서 검색 매개 변수를 보려면 각 리소스에 대한 검색 매개 변수를 확인하고 모든 리소스 CapabilityStatement.rest.searchParam 에 대한 검색 매개 변수를 찾습니다.

참고 항목

Azure API for FHIR은 FHIR 사양에 의해 정의되지 않은 검색 매개 변수를 자동으로 만들거나 인덱싱하지 않습니다. 그러나 사용자 고유 의 검색 매개 변수를 정의할 수 있도록 지원합니다.

복합 검색 매개 변수

복합 검색을 사용하면 값 쌍을 검색할 수 있습니다. 예를 들어 사람이 60인치인 높이 관찰을 검색하는 경우 관찰의 단일 구성 요소에 높이 코드와 값 60이 포함되어 있는지 확인하려고 합니다. 다른 구성 요소 섹션에서만 값 60 및 높이 코드에 적합한 항목이 관찰되더라도 60의 무게와 높이 48이 저장된 위치를 관찰하고 싶지는 않을 것입니다.

Azure API for FHIR을 사용하면 다음과 같은 검색 매개 변수 형식 페어링이 지원됩니다.

  • 참조, 토큰
  • 토큰, 날짜
  • 토큰, 숫자, 숫자
  • 토큰, 수량
  • 토큰, 문자열
  • 토큰, 토큰

자세한 내용은 HL7 복합 검색 매개 변수를 참조하세요.

참고 항목

복합 검색 매개 변수는 FHIR 사양에 따라 한정자를 지원하지 않습니다.

한정자 및 접두사

한정자를 사용하면 검색 매개 변수를 수정할 수 있습니다. 다음 표는 모든 FHIR 한정자와 Azure API for FHIR의 지원에 대한 개요입니다.

한정자 FHIR용 Azure API Azure Health Data Services의 FHIR 서비스 Comment(설명)
:없어진 예 예
:정확한 예 예
:포함 예 예
text: 예 예
:type(참조) 예 예
:안 예 예
:below(uri) 예 예
:above(uri) 예 예
:in(토큰) 아니요 아니요
:below(토큰) 아니요 아니요
:above(토큰) 아니요 아니요
:not-in(토큰) 아니요 아니요

특정 순서(숫자, 날짜 및 수량)가 있는 검색 매개 변수의 경우 매개 변수의 접두사를 사용하여 일치 항목을 찾는 데 도움이 될 수 있습니다. Azure API for FHIR은 모든 접두사를 지원합니다.

검색 결과 매개 변수

반환된 리소스를 관리하기 위해 사용할 수 있는 검색 결과 매개 변수가 있습니다. 각 검색 결과 매개 변수를 사용하는 방법에 대한 자세한 내용은 HL7 웹 사이트를 참조하세요.

검색 결과 매개 변수 FHIR용 Azure API Azure Health Data Services의 FHIR 서비스 Comment(설명)
_요소 예 예
_세다 예 예 _count 1,000개의 리소스로 제한됩니다. 1000보다 높게 설정하면 1000개만 반환되고 번들에 경고가 반환됩니다.
_포함하다 예 예 포함된 항목은 100으로 제한됩니다. Azure Cosmos DB의 PaaS 및 OSS에 대한 _include :iterate 지원 (#2137)을 포함하지 않습니다.
_revinclude 예 예 포함된 항목은 100으로 제한됩니다. Azure Cosmos DB의 PaaS 및 OSS에 대한 _revinclude :iterate 지원 (#2137)을 포함하지 않습니다. 잘못된 요청 #1319에 대한 잘못된 상태 코드도 있습니다.
_요약 예 예
_합계 부분 부분 _total=none 및 _total=정확도
_종류 부분 부분 sort=_lastUpdated Azure API for FHIR 및 FHIR 서비스에서 지원됩니다. 2021년 4월 20일 이후에 만든 Azure API for FHIR 및 OSS Azure Cosmos DB 데이터베이스의 경우 이름, 성, 생년월일 및 임상 날짜에 정렬이 지원됩니다.
_포함 아니요 아니요
_containedType 아니요 아니요
_점수 아니요 없음

참고 항목

기본적으로 _sort 레코드를 오름차순으로 정렬합니다. 접두 '-' 사를 사용하여 내림차순으로 정렬할 수 있습니다. 또한 FHIR 서비스 및 Azure API for FHIR을 사용하면 한 번에 하나의 필드에만 정렬할 수 있습니다.

기본적으로 Azure API for FHIR은 관대한 처리로 설정됩니다. 즉, 서버는 알 수 없거나 지원되지 않는 매개 변수를 무시합니다. 엄격한 처리를 사용하려는 경우 Prefer 헤더를 사용하고 설정할 handling=strict수 있습니다.

연결된 검색 및 역방향 연결 검색

연결된 검색을 사용하면 다른 리소스에서 참조하는 리소스에서 검색 매개 변수를 사용하여 검색할 수 있습니다. 예를 들어 환자의 이름이 Jane인 경우를 찾으려면 다음을 사용합니다.

GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane.

마찬가지로 역방향 연결된 검색을 수행할 수 있습니다. 이를 통해 참조하는 다른 리소스에 조건을 지정하는 리소스를 가져올 수 있습니다. 연결된 검색 및 역방향 체인 검색에 대한 자세한 예제는 FHIR 검색 예제 페이지를 참조 하세요 .

참고 항목

Azure API for FHIR 및 Azure Cosmos DB에서 지원되는 오픈 소스 체인 및 역방향 체인 검색에 필요한 각 하위 쿼리가 1000개 항목만 반환하는 제한 사항이 있습니다. 1000개 이상의 항목을 찾은 경우 다음과 같은 오류 메시지가 표시됩니다. "연결된 식의 하위 쿼리는 1000개 이상의 결과를 반환할 수 없습니다. 더 많은 선택적 조건을 사용하세요." 성공적인 쿼리를 얻으려면 찾고 있는 항목에 대해 더 구체적으로 설명해야 합니다.

페이지 매김

앞에서 설명한 것처럼 검색 결과는 페이징된 번들입니다. 기본적으로 검색은 페이지당 10개의 결과를 반환하지만 이를 지정 _count하여 늘리거나 줄일 수 있습니다. 번들 내에는 검색의 현재 결과가 포함된 자체 링크가 있습니다. 추가 일치 항목이 있는 경우 번들에 다음 링크가 포함됩니다. 다음 링크를 계속 사용하여 결과의 후속 페이지를 가져올 수 있습니다. _count 는 1,000개 이하의 항목으로 제한됩니다.

번들의 다음 링크에는 연속 토큰 크기 제한이 3KB입니다. 헤더 x-ms-documentdb-responsecontinuationtokenlimitinkb를 사용하여 연속 토큰 크기를 1KB에서 3KB 사이로 유연하게 조정할 수 있습니다.

현재 Azure API for FHIR은 번들의 다음 링크만 지원하며 첫 번째, 마지막 또는 이전 링크를 지원하지 않습니다.

다음 단계

이제 검색의 기본 사항에 대해 배웠으므로 다른 검색 매개 변수, 한정자 및 기타 FHIR 검색 시나리오를 사용하여 검색하는 방법에 대한 자세한 내용은 검색 샘플 페이지를 참조하세요.

FHIR 검색 예제

참고 항목

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