本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 中搜尋 FHIR 資源 AWS HealthLake 使用 FHIR [https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search)互動，根據一些篩選條件在 HealthLake 資料存放區中搜尋一組 FHIR 資源。您可以使用 `GET`或 `POST`請求來執行`search`互動。對於涉及個人身分識別資訊 (PII) 或受保護醫療資訊 (PHI) 的搜尋，建議使用`POST`請求，因為 PII 和 PHI 會新增為請求內文的一部分，並在傳輸中加密。 **注意** 本章所述的 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)。 **Important (重要)** 對於涉及個人身分識別資訊 (PII) 或受保護醫療資訊 (PHI) 的搜尋，安全最佳實務會使用 `POST` 請求，因為 PII 和 PHI 會新增為請求內文的一部分，並在傳輸中加密。如需詳細資訊，請參閱[使用 POST 搜尋 FHIR 資源](searching-fhir-resources-post.md)。 以下程序後面接著使用 `GET`搜尋 HealthLake 資料存放區的範例。 **使用 搜尋 HealthLake 資料存放區 `GET`** 1. 收集 HealthLake `region`和 `datastoreId` 值。如需詳細資訊，請參閱[取得資料存放區屬性](managing-data-stores-describe.md)。 1. 決定要搜尋的 FHIR 資源類型，並收集相關聯的`id`值。如需詳細資訊，請參閱[資源類型](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. 使用 [AWS Signature 第 4 版](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)或 FHIR 上的 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) 資料類型的 FHIR 上的 SMART 授權範例。 ``` { "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 授權。透過 AWS CLI 和 AWS SDKs支援 FHIR 上的 SMART 授權。 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. 選擇 **Run query** (執行查詢)。 ------ ## 範例：使用 GET 搜尋 下列索引標籤提供使用 搜尋特定 FHIR 資源類型的範例`GET`。這些範例示範如何在請求 URLs中指定搜尋參數。 **注意** HealthLake 主控台僅支援 SigV4 授權。透過 AWS CLI 和 AWS SDKs支援 FHIR 上的 SMART 授權。 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)資源類型中的 元素。使用下列範例，使用 [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`以 為基礎的搜尋請求，以搜尋 1997 年出生的個人。 ``` 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 資料存放區中尋找包含 SNOMED 醫療碼 的條件`72892002`，其會轉譯為 `Normal pregnancy`。 ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Condition?code=72892002 ``` ------ #### [ DocumentationReference ] 下列範例示範如何針對具有鏈球菌診斷的 `Patient`() 和也獲開立 amoxicillin 的人員，在[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 或請求內文中的搜尋參數，但您無法在單一請求中使用兩者。 **Important (重要)** 對於涉及個人身分識別資訊 (PII) 或受保護醫療資訊 (PHI) 的搜尋，安全最佳實務會使用 `POST` 請求，因為 PII 和 PHI 會新增為請求內文的一部分，並在傳輸中加密。 以下程序後面是使用 FHIR R4 與 `search`互動`POST`來搜尋 HealthLake 資料存放區的範例。這些範例示範如何在 JSON 請求內文中指定搜尋參數。 **使用 搜尋 HealthLake 資料存放區 `POST`** 1. 收集 HealthLake `region`和 `datastoreId` 值。如需詳細資訊，請參閱[取得資料存放區屬性](managing-data-stores-describe.md)。 1. 決定要搜尋的 FHIR 資源類型，並收集相關聯的`id`值。如需詳細資訊，請參閱[資源類型](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. 為請求建構 JSON 內文，指定要搜尋的 FHIR 資料。基於此程序的目的，您將搜尋`Observation`資源，以探索從未抽過煙的患者。若要指定醫療代碼狀態 `Never smoker`，請在 JSON 請求內文`value-concept=266919005`中設定 。儲存檔案為 `search-observation.json`。 ``` value-concept=266919005 ``` 1. 傳送 請求。FHIR `search`互動使用`GET`請求搭配 [AWS Signature 第 4 版](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)或 FHIR 上的 SMART 授權。 **注意** 在`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) 資料類型的 FHIR 上的 SMART 授權範例。 ``` { "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 授權。 AWS CLI 和 AWS SDKs 支援 FHIR 上的 SMART 授權。 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 ] 若要查看 HealthLake 在`DocumentReference`資源類型上提出`POST`請求時的整合自然語言處理 (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 資料存放區中包含城市名稱 Boston 做為地址一部分的位置。 您必須指定請求 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 的搜尋索引在 SEARCH 操作`POST`的 `GET`和 最終一致性模型上運作。使用最終一致性，如果資源有待定的搜尋索引更新，搜尋結果會排除資源的 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`標頭設定為 'strong' 會使每個資源的寫入容量耗用加倍。 此功能僅適用於已啟用版本歷史記錄的資料存放區 （在 2024 年 10 月 25 日之後建立的所有資料存放區預設為啟用）。