本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 在中搜索 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 搜索参数的子集。有关更多信息，请参阅 [FHIR R4 的搜索参数为 HealthLake](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 支持将搜索参数作为网址的一部分提供，但不支持作为请求正文的一部分。有关更多信息，请参阅 [FHIR R4 的搜索参数为 HealthLake](reference-fhir-search-parameters.md)。 **重要提示** 对于涉及个人身份信息 (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. 确定要搜索和收集关联`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. 使用[AWS 签名版本 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 ] 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)数据类型的授权示例。 ``` { "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. 选择**运行查询**。 ------ ## 示例：使用 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)资源类型中的一个元素。使用以下示例对[https://hl7.org/fhir/R4/patient.html](https://hl7.org/fhir/R4/patient.html)资源类型提出`GET`基于搜索的请求，使用 B [irthD](https://hl7.org/fhir/R4/patient-definitions.html#Patient.birthDate) ate 元素和`eq`[搜索比较器](reference-fhir-search-parameters.md#search-comparators)来搜索 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 ] 以下示例说明如何根据[https://hl7.org/fhir/R4/documentreference.html](https://hl7.org/fhir/R4/documentreference.html)资源类型为诊断为`Patient`链球菌且同时服用阿莫西林处方的人创建`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 与`POST`请求的[https://hl7.org/fhir/R4/search.html](https://hl7.org/fhir/R4/search.html)交互来搜索HealthLake 数据存储。使用时`POST`， HealthLake 支持在 URL 或请求正文中使用搜索参数，但不能在单个请求中同时使用这两个参数。 **重要提示** 对于涉及个人身份信息 (PII) 或受保护的健康信息 (PHI) 的搜索，安全最佳实践要求使用`POST`请求，因为 PII 和 PHI 是作为请求正文的一部分添加的，并在传输过程中进行加密。 以下过程是使用 FHIR R4 与的`search`交互`POST`来搜索 HealthLake 数据存储的示例。这些示例展示了如何在 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. 为请求构建 JSON 正文，指定要搜索的 FHIR 数据。出于此手术的目的，您将搜索`Observation`资源以发现从未吸烟的患者。要指定医疗代码状态`Never smoker`，请在 JSON 请求正文`value-concept=266919005`中进行设置。将该文件保存为 `search-observation.json`。 ``` value-concept=266919005 ``` 1. 发送 请求。FHIR `search` 交互使用带有[AWS 签名版本 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 或 SMART 的 FHIR 授权`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 授权。通过 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`。 您必须指定请求网址和请求正文。以下是请求网址的示例。 ``` 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 数据存储中查找地址中包含城市名称波士顿的位置。 您必须指定请求 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 ``` 要指定状态`Never smoker`，请在 JSON 的正文`value-concept=266919005`中进行设置。 ``` value-concept=266919005 ``` ------ # FHIR 搜索一致性级别 AWS HealthLake 的搜索索引在搜索`GET`操作的最终一致性模型上运行。`POST`为了最终保持一致性，如果某个资源的搜索索引有待更新，则在索引更新完成之前，搜索结果将排除该资源的 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 日之后创建的所有数据存储均启用该功能）。