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

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

项目
06/01/2023

快速医疗保健互操作性资源 (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 格式，如上面的 US Core Race 搜索参数中所示。
code：code 中存储的值是搜索时要使用的值。对于上面的示例，你将使用 GET {FHIR_URL}/Patient?race=<code> 进行搜索，以获取特定种族的所有患者。对于搜索参数所应用到的资源，该代码必须是唯一的。
base：描述搜索参数所应用到的资源。如果搜索参数应用到所有资源，则你可以使用 Resource；否则，你可以列出所有相关资源。
type：描述搜索参数的数据类型。类型受限于对 Azure API for FHIR 的支持。这意味着，除非它是受支持的组合，否则无法定义类型为 Special 的搜索参数或定义复合搜索参数。
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 服务器。现在，可以搜索 use partial indices 头并将其设置为 true，这意味着，此命令返回的结果中的任何资源的搜索参数均已编制索引，即使并非所有该类型的资源的搜索参数均已编制索引。

沿用前面的示例，可为一名患者编制索引以启用 US Core Race 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 许可使用。