기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 에서 FHIR 리소스 검색 AWS HealthLake FHIR [https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search) 상호 작용을 사용하여 일부 필터 기준에 따라 HealthLake 데이터 스토어에서 FHIR 리소스 세트를 검색합니다. 상호 `search` 작용은 `GET` 또는 `POST` 요청을 사용하여 수행할 수 있습니다. 개인 식별 정보(PII) 또는 보호 대상 건강 정보(PHI)가 포함된 검색의 경우 PII 및 PHI가 `POST` 요청 본문의 일부로 추가되고 전송 중에 암호화되므로 요청을 사용하는 것이 좋습니다. **참고** 이 장에서 설명하는 FHIR `search` 상호 작용은 의료 데이터 교환을 위한 HL7 FHIR R4 표준을 준수하도록 구축되었습니다. HL7 FHIR 서비스의 표현이므로 AWS CLI 및 AWS SDKs 통해 제공되지 않습니다. 자세한 내용은 **FHIR R4 RESTful API 설명서**[https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search)의 섹션을 참조하세요. HealthLake는 FHIR R4 검색 파라미터의 하위 집합을 지원합니다. 자세한 내용은 [HealthLake에 대한 FHIR R4 검색 파라미터](reference-fhir-search-parameters.md) 단원을 참조하십시오. **Topics** + [GET으로 검색](searching-fhir-resources-get.md) + [POST로 검색](searching-fhir-resources-post.md) + [검색 일관성 수준](searching-fhir-consistency-levels.md) # GET을 사용하여 FHIR 리소스 검색 `GET` 요청을 사용하여 HealthLake 데이터 스토어를 검색할 수 있습니다. `GET`를 사용하는 경우 HealthLake는 URL의 일부로 검색 파라미터를 제공하는 것을 지원하지만 요청 본문의 일부로는 제공하지 않습니다. 자세한 내용은 [HealthLake에 대한 FHIR R4 검색 파라미터](reference-fhir-search-parameters.md) 단원을 참조하십시오. **중요** 개인 식별 정보(PII) 또는 보호 대상 건강 정보(PHI)가 포함된 검색의 경우 PII 및 PHI가 `POST` 요청 본문의 일부로 추가되고 전송 중에 암호화되므로 보안 모범 사례는 요청을 사용하기 위해를 호출합니다. 자세한 내용은 [POST를 사용하여 FHIR 리소스 검색](searching-fhir-resources-post.md) 단원을 참조하십시오. 다음 절차에는를 사용하여 HealthLake 데이터 스토어를 `GET` 검색하는 예제가 나와 있습니다. **를 사용하여 HealthLake 데이터 스토어를 검색하려면 `GET`** 1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오. 1. 연결된 `id` 값을 검색하고 수집할 FHIR 리소스 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오. 1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. FHIR `Resource` 유형과 지원되는 [검색 파라미터](reference-fhir-search-parameters.md)도 포함합니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다. ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource{?[parameters]{&_format=[mime-type]}} ``` 1. FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART를 사용하여 `GET` 요청을 보냅니다. 다음 `curl` 예시에서는 HealthLake 데이터 스토어의 총 `Patient` 리소스 수를 반환합니다. 전체 예제를 보려면 **복사** 버튼을 스크롤합니다. ------ #### [ SigV4 ] SigV4 권한 부여 ``` curl --request GET \ 'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_total=accurate' \ --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 ] [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다. ``` { "AuthorizationStrategy": "SMART_ON_FHIR", "FineGrainedAuthorizationEnabled": true, "IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name", "Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}" } ``` 호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오. ------ #### [ AWS Console ] **참고** HealthLake 콘솔은 SigV4 권한 부여만 지원합니다. SMART on FHIR 권한 부여는 AWS CLI 및 AWS SDKs 통해 지원됩니다. 1. HealthLake 콘솔의 [쿼리 실행](https://console.aws.amazon.com/healthlake/home#/crud) 페이지에 로그인합니다. 2. **쿼리 설정** 섹션에서 다음을 선택합니다. + **데이터 스토어 ID** - 쿼리 문자열을 생성할 데이터 스토어 ID를 선택합니다. + **쿼리 유형** -를 선택합니다`Search with GET`. + **리소스 유형** - 검색할 FHIR [리소스 유형을](reference-fhir-resource-types.md) 선택합니다. + **검색 파라미터** - [검색 파라미터](reference-fhir-search-parameters.md) 또는 검색 파라미터 조합을 선택하여 쿼리를 특정 레코드에 집중합니다. 3. **쿼리 실행**을 선택합니다. ------ ## 예: GET으로 검색 다음 탭은를 사용하여 특정 FHIR 리소스 유형을 검색하는 예제를 제공합니다`GET`. 이 예제에서는 요청 URLs에서 검색 파라미터를 지정하는 방법을 보여줍니다. **참고** HealthLake 콘솔은 SigV4 권한 부여만 지원합니다. SMART on FHIR 권한 부여는 AWS CLI 및 AWS SDKs 통해 지원됩니다. HealthLake는 FHIR R4 검색 파라미터의 하위 집합을 지원합니다. 자세한 내용은 [검색 파라미터](reference-fhir-search-parameters.md) 단원을 참조하십시오. ------ #### [ Patient (age) ] 수명은 FHIR에서 정의된 리소스 유형이 아니지만 [https://hl7.org/fhir/R4/patient.html](https://hl7.org/fhir/R4/patient.html) 리소스 유형의 요소로 캡처됩니다. 다음 예제를 사용하여 1997년에 태어난 개인을 검색하기 위해 [birthDate](https://hl7.org/fhir/R4/patient-definitions.html#Patient.birthDate) 요소와 `eq` [검색 비교](reference-fhir-search-parameters.md#search-comparators)기를 사용하여 [https://hl7.org/fhir/R4/patient.html](https://hl7.org/fhir/R4/patient.html) 리소스 유형에 대한 `GET`기반 검색을 요청합니다. ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?birthdate=eq1997 ``` ------ #### [ Condition ] 다음 예제를 사용하여 [https://hl7.org/fhir/R4/condition.html](https://hl7.org/fhir/R4/condition.html) 리소스 유형을 `GET` 요청합니다. 검색은 HealthLake 데이터 스토어에서 로 변환`72892002`되는 SNOMED 의료 코드가 포함된 조건을 찾습니다`Normal pregnancy`. ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Condition?code=72892002 ``` ------ #### [ DocumentationReference ] 다음 예제는 (`Patient`s)에 대한 [https://hl7.org/fhir/R4/documentreference.html](https://hl7.org/fhir/R4/documentreference.html) 리소스 유형에 대해 연쇄상 알균 진단을 받고 아목시실린도 처방받은에 대한 `GET` 요청을 생성하는 방법을 보여줍니다. ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/DocumentReference?_lastUpdated=le2021-12-19&infer-icd10cm-entity-text-concept-score;=streptococcal|0.6&infer-rxnorm-entity-text-concept-score=Amoxicillin|0.8 ``` ------ #### [ Location ] 다음 예제를 사용하여 [https://hl7.org/fhir/R4/location.html](https://hl7.org/fhir/R4/location.html) 리소스 유형을 `GET` 요청합니다. 다음 검색은 주소의 일부로 도시 이름 보스턴이 포함된 HealthLake 데이터 스토어의 위치를 찾습니다. ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Location?address=boston ``` ------ #### [ Observation ] 다음 예제를 사용하여 [https://hl7.org/fhir/R4/observation.html](https://hl7.org/fhir/R4/observation.html) 리소스 유형에 대한 `GET`기반 검색 요청을 수행합니다. 이 검색은 `value-concept` [검색 파라미터를](reference-fhir-search-parameters.md) 사용하여 로 변환`266919005`되는 의료 코드를 찾습니다`Never smoker`. ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Observation?value-concept=266919005 ``` ------ # POST를 사용하여 FHIR 리소스 검색 FHIR [https://hl7.org/fhir/R4/search.html](https://hl7.org/fhir/R4/search.html) 상호 작용을 `POST` 요청과 함께 사용하여 HealthLake 데이터 스토어를 검색할 수 있습니다. `POST`를 사용하는 경우 HealthLake는 URL 또는 요청 본문에서 검색 파라미터를 지원하지만 단일 요청에서 둘 다 사용할 수는 없습니다. **중요** 개인 식별 정보(PII) 또는 보호 대상 건강 정보(PHI)가 포함된 검색의 경우 PII 및 PHI가 `POST` 요청 본문의 일부로 추가되고 전송 중에 암호화되므로 보안 모범 사례는 요청을 사용하기 위해를 호출합니다. 다음은 FHIR R4 상호 `search` 작용을 사용하여 HealthLake 데이터 스토어`POST`를 검색하는 예제입니다. 이 예제에서는 JSON 요청 본문에서 검색 파라미터를 지정하는 방법을 보여줍니다. **를 사용하여 HealthLake 데이터 스토어를 검색하려면 `POST`** 1. HealthLake `region` 및 `datastoreId` 값을 수집합니다. 자세한 내용은 [데이터 스토어 속성 가져오기](managing-data-stores-describe.md) 단원을 참조하십시오. 1. 연결된 `id` 값을 검색하고 수집할 FHIR 리소스 유형을 결정합니다. 자세한 내용은 [조건 키](reference-fhir-resource-types.md) 단원을 참조하십시오. 1. HealthLake `region` 및에 대해 수집된 값을 사용하여 요청에 대한 URL을 구성합니다`datastoreId`. FHIR `Resource` 유형 및 `_search` 상호 작용도 포함합니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다. ``` POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/_search ``` 1. 검색할 FHIR 데이터를 지정하여 요청에 대한 JSON 본문을 구성합니다. 이 절차의 목적상 `Observation` 리소스를 검색하여 담배를 피운 적이 없는 환자를 찾습니다. 의료 코드 상태를 지정하려면 JSON 요청 본문`value-concept=266919005`에서를 `Never smoker`설정합니다. 파일을 `search-observation.json`(으)로 저장합니다. ``` value-concept=266919005 ``` 1. 요청을 보냅니다. FHIR `search` 상호 작용은 FHIR 권한 부여 시 [AWS 서명 버전 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 또는 SMART와 함께 `GET` 요청을 사용합니다. **참고** `POST` 요청 본문에 검색 파라미터를 사용하여 요청할 때는를 헤더의 `Content-Type: application/x-www-form-urlencoded` 일부로 사용합니다. 다음 `curl` 예제에서는 `Observation` 리소스 유형에 대한 POST 기반 검색 요청을 수행합니다. 요청은 [https://hl7.org/fhir/R4/observation.html#search](https://hl7.org/fhir/R4/observation.html#search) 검색 파라미터를 사용하여 값을 `266919005` 나타내는 의료 코드를 찾습니다`Never smoker`. 전체 예제를 보려면 **복사** 버튼을 스크롤합니다. ------ #### [ SigV4 ] SigV4 권한 부여 ``` curl --request POST \ 'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Observation/_search' \ --aws-sigv4 'aws:amz:region:healthlake' \ --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \ --header "x-amz-security-token:$AWS_SESSION_TOKEN" \ --header "Content-Type: application/x-www-form-urlencoded" --header "Accept: application/json" --data @search-observation.json ``` ------ #### [ SMART on FHIR ] [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 데이터 형식에 대한 SMART on FHIR 권한 부여 예제입니다. ``` { "AuthorizationStrategy": "SMART_ON_FHIR", "FineGrainedAuthorizationEnabled": true, "IdpLambdaArn": "arn:aws:lambda:your-region:your-account-id:function:your-lambda-name", "Metadata": "{\"issuer\":\"https://ehr.example.com\", \"jwks_uri\":\"https://ehr.example.com/.well-known/jwks.json\",\"authorization_endpoint\":\"https://ehr.example.com/auth/authorize\",\"token_endpoint\":\"https://ehr.token.com/auth/token\",\"token_endpoint_auth_methods_supported\":[\"client_secret_basic\",\"foo\"],\"grant_types_supported\":[\"client_credential\",\"foo\"],\"registration_endpoint\":\"https://ehr.example.com/auth/register\",\"scopes_supported\":[\"openId\",\"profile\",\"launch\"],\"response_types_supported\":[\"code\"],\"management_endpoint\":\"https://ehr.example.com/user/manage\",\"introspection_endpoint\":\"https://ehr.example.com/user/introspect\",\"revocation_endpoint\":\"https://ehr.example.com/user/revoke\",\"code_challenge_methods_supported\":[\"S256\"],\"capabilities\":[\"launch-ehr\",\"sso-openid-connect\",\"client-public\",\"permission-v2\"]}" } ``` 호출자는 권한 부여 Lambda에 권한을 할당할 수 있습니다. 자세한 내용은 [OAuth 2.0 범위](reference-smart-on-fhir-oauth-scopes.md) 단원을 참조하십시오. ------ ## 예: POST로 검색 다음 탭은를 사용하여 특정 FHIR 리소스 유형을 검색하는 예제를 제공합니다`POST`. 이 예제에서는 URLs에서 요청을 지정하는 방법을 보여줍니다. **참고** HealthLake 콘솔은 SigV4 권한 부여만 지원합니다. SMART on FHIR 권한 부여는 AWS CLI 및 AWS SDKs 통해 지원됩니다. HealthLake는 FHIR R4 검색 파라미터의 하위 집합을 지원합니다. 자세한 내용은 [검색 파라미터](reference-fhir-search-parameters.md) 단원을 참조하십시오. ------ #### [ Patient (age) ] 수명은 FHIR에서 정의된 리소스 유형이 아니지만 [https://hl7.org/fhir/R4/patient.html](https://hl7.org/fhir/R4/patient.html) 리소스 유형의 요소로 캡처됩니다. 다음 예제를 사용하여 `Patient` 리소스 유형에 대한 `POST`기반 검색을 요청합니다. 다음 검색 예제에서는 `eq` [검색 비교](reference-fhir-search-parameters.md#search-comparators)기를 사용하여 1997년에 태어난 개인을 검색합니다. ``` POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/_search ``` 검색에서 1997년을 지정하려면 요청 본문에 다음 요소를 추가합니다. ``` birthdate=eq1997 ``` ------ #### [ Condition ] 다음을 사용하여 `Condition` 리소스 유형을 `POST` 요청합니다. 이 검색은 HealthLake 데이터 스토어에서 의료 코드가 포함된 위치를 찾습니다`72892002`. 요청 URL과 요청 본문을 지정해야 합니다. 다음은 요청 URL의 예입니다. ``` POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Condition/_search ``` 검색하려는 의료 코드를 지정하려면 요청 본문에 다음 JSON 요소를 추가합니다. ``` code=72892002 ``` ------ #### [ DocumentReference ] `DocumentReference` 리소스 유형에 대해 `POST` 요청할 때 HealthLake의 통합 자연어 처리(NLP) 결과를 보려면 다음과 같이 요청의 형식을 지정합니다. ``` POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/DocumentReference/_search ``` 참조할 `DocumentReference` 검색 파라미터를 지정하려면 섹션을 참조하세요[검색 파라미터 유형](reference-fhir-search-parameters.md#search-parameter-types). 다음 쿼리 문자열은 여러 검색 파라미터를 사용하여 통합 NLP 결과를 생성하는 데 사용되는 Amazon Comprehend Medical API 작업을 검색합니다. ``` _lastUpdated=le2021-12-19&infer-icd10cm-entity-text-concept-score;=streptococcal|0.6&infer-rxnorm-entity-text-concept-score=Amoxicillin|0.8 ``` ------ #### [ Location ] 다음 예제를 사용하여 `Location` 리소스 유형을 `POST` 요청합니다. 검색은 주소의 일부로 도시 이름 보스턴이 포함된 HealthLake 데이터 스토어의 위치를 찾습니다. 요청 URL과 요청 본문을 지정해야 합니다. 다음은 요청 URL의 예입니다. ``` POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Location/_search ``` 검색`Boston`에서를 지정하려면 요청 본문에 다음 요소를 추가합니다. ``` address=Boston ``` ------ #### [ Observation ] 다음 예제를 사용하여 `Observation` 리소스 유형에 대한 `POST`기반 검색을 요청합니다. 검색은 `value-concept` 검색 파라미터를 사용하여를 `266919005` 나타내는 의료 코드를 찾습니다`Never smoker`. ``` POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Observation/_search ``` 상태를 지정하려면 JSON 본문`value-concept=266919005`에 `Never smoker`를 설정합니다. ``` value-concept=266919005 ``` ------ # FHIR 검색 일관성 수준 AWS HealthLake의 검색 인덱스는 `GET` 및 `POST` SEARCH 작업에 대한 최종 일관성 모델에서 작동합니다. 최종 일관성을 위해 리소스에 대해 보류 중인 검색 인덱스 업데이트가 있는 경우 인덱스 업데이트가 완료될 때까지 검색 결과에 리소스의 버전 N-1이 제외됩니다. AWS HealthLake에는 이제 업데이트된 리소스에 대한 일관성 모델의 작동 방식을 선택할 수 있는 기능이 포함되어 있습니다. 개발자는 '이벤트 일관성', 위에서 설명한 기본 동작 또는 '강력한 일관성'을 포함할 수 있습니다. 강력한 일관성은 대기 중인 검색 인덱스 업데이트가 있는 리소스에 대한 리소스의 N-1 버전을 검색 결과에 포함할 수 있도록 허용합니다. 검색 인덱스 업데이트가 아직 완료되지 않은 경우에도 결과에 모든 리소스가 필요한 사용 사례 시나리오에 사용할 수 있습니다. 고객은 `x-amz-fhir-history-consistency-level` 요청 헤더를 사용하여이 동작을 제어할 수 있습니다. ## 일관성 수준 강력한 일관성 대기 중인 검색 인덱스 업데이트가 있는 레코드를 포함하여 일치하는 모든 레코드를 반환`x-amz-fhir-history-consistency-level: strong`하도록 설정합니다. 업데이트 직후 리소스를 검색해야 하는 경우이 옵션을 사용합니다. 최종 일관성 검색 인덱스 업데이트를 완료한 레코드만 반환`x-amz-fhir-history-consistency-level: eventual`하도록 설정합니다. 일관성 수준이 지정되지 않은 경우의 기본 동작입니다. ## 사용 예 1. 리소스를 업데이트할 때: ``` POST /Patient Content-Type: application/fhir+json x-amz-fhir-history-consistency-level: strong { "resourceType": "Patient", "id": "123", "meta": { "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"] }, "identifier": [ { "system": "http://example.org/identifiers", "value": "123" } ], "active": true, "name": [ { "family": "Smith", "given": ["John"] } ], "gender": "male", "birthDate": "1970-01-01" } ``` 1. 후속 검색: ``` GET /Patient?_id=123 ``` ## 모범 사례 + 최근에 업데이트된 리소스를 즉시 검색해야 하는 경우 강력한 일관성 사용 + 즉각적인 가시성이 중요하지 않은 일반 쿼리에 최종 일관성 사용 + 즉각적인 가시성과 잠재적 성능 영향 간의 장단점을 고려하세요. **참고** 일관성 수준 설정은 업데이트된 리소스가 검색 결과에 표시되는 속도에 영향을 주지만 리소스의 실제 스토리지에는 영향을 주지 않습니다. 선택적 `x-amz-fhir-history-consistency-level` 헤더를 '강력'으로 설정하면 리소스당 쓰기 용량 소비가 두 배로 늘어납니다. 이 기능은 버전 기록이 활성화된 데이터 스토어에만 적용됩니다(2024년 10월 25일 이후에 생성된 모든 데이터 스토어에는 기본적으로 활성화되어 있음).