你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为 Azure API for FHIR 定义自定义的搜索参数

项目
10/04/2024

重要

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 API for FHIR 的演化版本，可让客户管理 FHIR、DICOM 和医疗技术服务，并集成到其他 Azure 服务。

Fast Healthcare 互操作性资源（FHIR®）规范定义一组特定于资源的所有资源和搜索参数的搜索参数。但是，在某些情况下，你可能想要针对未由 FHIR 规范定义为标准搜索参数的资源中的元素进行搜索。本文介绍如何定义你自己的、要在 Azure API for FHIR 中使用的搜索参数。

注意

每次创建、更新或删除搜索参数时，都需要运行一个重新编制索引作业来启用要在生产环境中使用的搜索参数。本文将概述如何在重新编制整个 FHIR 服务器索引之前测试搜索参数。

创建新搜索参数

若要创建新搜索参数，请通过 POST 将 SearchParameter 资源发布到数据库。下面的代码示例演示如何将 US Core Race SearchParameter 添加到Patient资源。

POST {{FHIR_URL}}/SearchParameter

{
  "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"
}

注意

在将搜索参数发布到数据库并为数据库重新编制索引后，新搜索参数将显示在 FHIR 服务器的功能语句中。只能通过查看功能语句中的 SearchParameter 来判断 FHIR 服务器是否支持某个搜索参数。如果可以找到搜索参数，但在功能语句中看不到它，则仍需为搜索参数编制索引。在触发重新编制索引操作之前，可以发布多个搜索参数。

重要元素 SearchParameter 包括以下内容。

url：用于描述搜索参数的唯一键。许多组织（如 HL7）对定义的搜索参数使用标准 URL 格式，如之前在美国核心竞赛搜索参数中所示。
代码：存储在代码中的值是在搜索时使用的值。对于前面的示例，你将搜索 GET {FHIR_URL}/Patient?race=<code> 以获取特定比赛的所有患者。搜索参数应用于的资源的代码必须是唯一的。
base：描述搜索参数应用于哪些资源。如果搜索参数应用到所有资源，则你可以使用 Resource；否则，你可以列出所有相关资源。
type：描述搜索参数的数据类型。类型受限于对 Azure API for FHIR 的支持。这意味着不能定义特殊类型的搜索参数或定义复合搜索参数，除非它是受支持的组合。
expression：描述如何计算搜索值。描述搜索参数时，必须包含表达式，即使规范不需要它。这是因为需要表达式或 xpath 语法，Azure API for FHIR 会忽略 xpath 语法。

测试搜索参数

虽然在运行重新编制索引作业之前无法使用生产中的搜索参数，但在重新编制整个数据库索引之前，可以测试搜索参数。

首先，可以测试新的搜索参数，以查看返回的值。通过针对特定资源实例运行以下命令（通过输入其 ID），可以获取一个值对列表，其中包含搜索参数名称和为特定患者存储的值。这包括资源的所有搜索参数。可以滚动浏览返回的列表以查找创建的搜索参数。运行此命令不会更改 FHIR 服务器中的任何行为。

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_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

运行此项设置为为该资源类型定义的特定资源的任何搜索参数的索引。这确实会更新 FHIR 服务器。现在，可以搜索并使用部分索引标头设置为 true，这意味着它将返回任何已为搜索参数编制索引的资源的结果，即使并非所有该类型的资源都为其编制索引。

继续我们的示例，可以编制一个患者索引，以启用美国核心竞赛 SearchParameter ，如下所示。

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

然后搜索具有特定种族的患者：

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

满足于搜索参数按预期工作后，请运行或计划重新编制索引作业，以便可在 FHIR 服务器中将搜索参数用于生产用例。

更新搜索参数

若要更新某个搜索参数，请使用 PUT 创建该搜索参数的新版本。必须在 PUT 请求正文的 id 元素中以及 PUT 调用中包含 SearchParameter ID。

注意

如果你不知道搜索参数的 ID，可以搜索此 ID。使用 GET {{FHIR_URL}}/SearchParameter 将返回所有自定义搜索参数，你可以滚动浏览列表以查找所需的搜索参数。还可以按名称限制搜索。使用以下示例，可以使用搜索名称 USCoreRace: 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 的，版本递增。

警告

更新已在数据库中编制索引的 SearchParameter 时请小心。更改现有 SearchParameter 的行为可能会影响预期行为。建议立即运行重新编制索引作业。

删除搜索参数

如果需要删除搜索参数，请使用以下内容。

Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}

警告

删除已在数据库中编制索引的 SearchParameter 时请小心。更改现有 SearchParameter 的行为可能会影响预期行为。建议立即运行重新编制索引作业。

后续步骤

本文介绍了如何创建搜索参数。接下来，可以了解如何为 FHIR 服务器重新编制索引。

如何运行重新编制索引作业

注意

FHIR® 是 HL7 的注册商标，经 HL7 许可使用。

通过