사용자 지정 검색 매개 변수 정의

아티클
06/09/2023

FHIR 사양은 모든 리소스에 적용되는 검색 매개 변수 집합을 정의합니다. 또한 FHIR은 특정 리소스와 관련된 많은 검색 매개 변수를 정의합니다. 그러나 FHIR 사양에서 표준 검색 매개 변수로 정의되지 않은 리소스의 요소에 대해 검색할 수 있는 시나리오가 있습니다. 이 문서에서는 Azure Health Data Services의 FHIR 서비스에서 사용할 사용자 지정 검색 매개 변수 를 정의하는 방법을 설명합니다.

참고

검색 매개 변수를 만들거나 업데이트하거나 삭제할 때마다 다시 인덱스 작업을 실행하여 라이브 프로덕션에 대한 검색 매개 변수를 사용하도록 설정해야 합니다. 아래에서는 전체 FHIR 서비스 데이터베이스를 다시 인덱싱하기 전에 검색 매개 변수를 테스트하는 방법을 간략하게 설명합니다.

새 검색 매개 변수 만들기

새 검색 매개 변수를 만들려면 FHIR 서비스 데이터베이스에 대한 리소스가 필요합니다 POSTSearchParameter .

POST {{FHIR_URL}}/SearchParameter

아래 예제에서는 새 사용자 지정 검색 매개 변수를 만드는 방법을 보여 줍니다.

구현 가이드에서 정의당 새 검색 매개 변수 만들기

아래 코드 예제에서는 US Core Race 검색 매개 변수 를 FHIR 서비스 데이터베이스의 Patient 리소스 종류에 추가하는 방법을 보여줍니다.

{
  "resourceType" : "SearchParameter",
  "id" : "us-core-race",
  "url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
  "version" : "3.1.1",
  "name" : "USCoreRace",
  "status" : "active",
  "date" : "2019-05-21",
  "publisher" : "US Realm Steering Committee",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "other",
          "value" : "http://www.healthit.gov/"
        }
      ]
    }
  ],
  "description" : "Returns patients with a race extension matching the specified code.",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "urn:iso:std:iso:3166",
          "code" : "US",
          "display" : "United States of America"
        }
      ]
    }
  ],
  "code" : "race",
  "base" : [
    "Patient"
  ],
  "type" : "token",
  "expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}

참조 형식을 사용하여 리소스 특성에 대한 새 검색 매개 변수 만들기

코드 예제에서는 사용자 지정 검색 매개 변수를 만들어 배포된 위치에 따라 MedicationDispense 리소스를 검색하는 방법을 보여 줍니다. 참조 형식에 대한 사용자 지정 검색 매개 변수를 추가하는 예제입니다.

{
 "resourceType": "SearchParameter",
  "id": "a3c28d46-fd06-49ca-aea7-5f9314ef0497",
  "url": "{{An absolute URI that is used to identify this search parameter}}",
  "version": "1.0",
  "name": "MedicationDispenseLocationSearchParameter",
  "status": "active",
  "description": "Search parameter for MedicationDispense by location",
  "code": "location",
  "base": ["MedicationDispense"],
  "target": ["Location"],
  "type": "reference",
  "expression": "MedicationDispense.location"
}

참고

새 검색 매개 변수는 데이터베이스에 대한 검색 매개 변수를 선택하고 데이터베이스를 다시 인덱싱한 후 POST FHIR 서비스의 capability 문에 표시됩니다. SearchParameter 기능 문에서 를 보는 것은 검색 매개 변수가 FHIR 서비스에서 지원되는지 확인하는 유일한 방법입니다. capability 문에서 를 SearchParameter 찾을 수 없는 경우에도 검색 매개 변수를 활성화하려면 데이터베이스를 다시 인덱싱해야 합니다. 다시 인덱스 작업을 트리거하기 전에 여러 검색 매개 변수를 사용할 수 있습니다 POST .

리소스의 SearchParameter 중요한 요소:

url: 검색 매개 변수를 설명하는 고유 키입니다. HL7과 같은 조직은 US Core Race 검색 매개 변수에 위와 같이 정의하는 검색 매개 변수에 표준 URL 형식을 사용합니다.
code: 코드 요소에 저장된 값은 API 호출에 포함될 때 검색 매개 변수에 사용되는 이름입니다. "US Core Race" 확장이 있는 위의 예제의 경우 지정된 코딩 시스템에서 설정된 값에 있는 where <code> 를 검색 GET {{FHIR_URL}}/Patient?race=<code> 합니다. 이 호출은 특정 인종의 모든 환자를 검색할 것입니다.
base: 검색 매개 변수가 적용되는 리소스 유형을 설명합니다. 검색 매개 변수가 모든 리소스에 적용되는 경우 를 사용할 Resource수 있습니다. 그렇지 않으면 모든 관련 리소스 유형을 나열할 수 있습니다.
target: 검색 매개 변수가 일치하는 리소스 유형을 설명합니다.
type: 검색 매개 변수의 데이터 형식을 설명합니다. 형식은 FHIR 서비스의 데이터 형식 지원에 의해 제한됩니다. 즉, 지원되는 조합이 아니면 Special 형식의 검색 매개 변수를 정의하거나 복합 검색 매개 변수 를 정의할 수 없습니다.
expression: 검색 값을 계산하는 방법을 설명합니다. 검색 매개 변수를 설명할 때는 사양에 필요하지 않더라도 식을 포함해야 합니다. 식 또는 xpath 구문이 필요하고 FHIR 서비스가 xpath 구문을 무시하기 때문입니다.

새 검색 매개 변수 테스트

다시 인덱스 작업을 실행할 때까지 프로덕션 환경에서 새 검색 매개 변수를 사용할 수 없지만 전체 데이터베이스를 다시 인덱싱하기 전에 사용자 지정 검색 매개 변수를 테스트하는 몇 가지 방법이 있습니다.

먼저 새 검색 매개 변수를 테스트하여 반환되는 값을 확인할 수 있습니다. 리소스 ID를 제공하여 특정 리소스 instance 대해 아래 명령을 실행하면 검색 매개 변수 이름과 해당 요소에 저장된 값을 사용하여 값 쌍 목록을 다시 가져옵니다. 이 목록에는 리소스에 대한 모든 검색 매개 변수가 포함됩니다. 스크롤하여 만든 검색 매개 변수를 찾을 수 있습니다. 이 명령을 실행해도 FHIR 서비스의 동작은 변경되지 않습니다.

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

예를 들어 환자에 대한 모든 검색 매개 변수를 찾으려면 다음을 수행합니다.

GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

결과는 다음과 같습니다.

{
  "resourceType": "Parameters",
  "id": "8be24e78-b333-49da-a861-523491c3437a",
  "meta": {
    "versionId": "1"
  },
  "parameter": [
    {
      "name": "deceased",
      "valueString": "http://hl7.org/fhir/special-values|false"
    },
    {
      "name": "language",
      "valueString": "urn:ietf:bcp:47|en-US"
    },
    {
      "name": "race",
      "valueString": "2028-9"
    }
    ]
    ...}

검색 매개 변수가 예상대로 표시되는 것을 확인하면 단일 리소스를 다시 인덱싱하여 새 검색 매개 변수를 사용하여 검색을 테스트할 수 있습니다. 단일 리소스를 다시 인덱싱하려면 다음을 수행합니다.

POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

이 POST 호출을 실행하면 요청에 지정된 리소스 instance 대해 정의된 검색 매개 변수에 대한 인덱스가 설정됩니다. 이 호출은 FHIR 서비스 데이터베이스를 변경합니다. 이제 헤더true를 x-ms-use-partial-indices 검색하고 로 설정하면 해당 형식의 모든 리소스 인스턴스가 인덱싱되지 않더라도 FHIR 서비스가 검색 매개 변수가 인덱싱된 리소스에 대한 결과를 반환합니다.

이 예제를 계속 진행하면서 한 환자를 인덱싱하여 를 사용하도록 설정할 수 있습니다 SearchParameter.

POST {{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

그런 다음, 테스트 검색을 수행합니다.

인종별 환자:

GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true

위치(참조 형식):

{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

새 검색 매개 변수를 테스트하고 예상대로 작동하는지 확인한 후 새 검색 매개 변수를 라이브 프로덕션에서 사용할 수 있도록 다시 인덱스 작업을 실행하거나 예약합니다.

FHIR 서비스 데이터베이스 를 다시 인덱싱 하는 방법에 대한 자세한 내용은 다시 인덱스 작업 실행을 참조하세요.

검색 매개 변수 업데이트

검색 매개 변수를 업데이트하려면 를 사용하여 PUT 새 버전의 검색 매개 변수를 만듭니다. 요청 본문의 필드에 검색 매개 변수 ID id 와 요청 문자열을 PUTPUT 포함해야 합니다.

참고

검색 매개 변수의 ID를 모르는 경우 를 사용하여 GET {{FHIR_URL}}/SearchParameter검색할 수 있습니다. 그러면 모든 사용자 지정 매개 변수와 표준 검색 매개 변수가 반환되며 목록을 스크롤하여 필요한 검색 매개 변수를 찾을 수 있습니다. 이름으로 검색을 제한할 수도 있습니다. 아래 예제 요청에 표시된 것처럼 사용자 지정 SearchParameter 리소스 instance 이름은 입니다USCoreRace. 를 사용하여 이름으로 이 SearchParameter 리소스를 검색할 수 있습니다 GET {{FHIR_URL}}/SearchParameter?name=USCoreRace.

PUT {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

{
  "resourceType" : "SearchParameter",
  "id" : "{{SearchParameter_ID}}",
  "url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
  "version" : "3.1.1",
  "name" : "USCoreRace",
  "status" : "active",
  "date" : "2019-05-21",
  "publisher" : "US Realm Steering Committee",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "other",
          "value" : "http://www.healthit.gov/"
        }
      ]
    }
  ],
  "description" : "New Description!",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "urn:iso:std:iso:3166",
          "code" : "US",
          "display" : "United States of America"
        }
      ]
    }
  ],
  "code" : "race",
  "base" : [
    "Patient"
  ],
  "type" : "token",
  "expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}

위의 요청의 결과는 업데이트 SearchParameter 된 리소스가 됩니다.

경고

검색 매개 변수를 업데이트할 때는 주의해야 합니다. 기존 검색 매개 변수를 변경하면 예상 동작에 영향을 줄 수 있습니다. 다시 인덱스 작업을 즉시 실행하는 것이 좋습니다.

검색 매개 변수 삭제

검색 매개 변수를 삭제해야 하는 경우 다음을 사용합니다.

DELETE {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

경고

검색 매개 변수를 삭제할 때는 주의해야 합니다. 기존 검색 매개 변수를 삭제하면 예상 동작에 영향을 줄 수 있습니다. 다시 인덱스 작업을 즉시 실행하는 것이 좋습니다.

다음 단계

이 문서에서는 사용자 지정 검색 매개 변수를 만드는 방법을 알아보았습니다. 다음으로 FHIR 서비스 데이터베이스를 다시 인덱싱하는 방법을 알아볼 수 있습니다. 자세한 내용은 다음을 참조하세요.

재색인 작업 실행 방법

FHIR®은 HL7의 등록 상표이며 HL7 의 권한으로 사용됩니다.