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

定义自定义搜索参数

项目
07/27/2023

FHIR 规范定义了一组适用于所有资源的搜索参数。此外，FHIR 还定义了许多特定于某些资源的搜索参数。但是，在某些情况下，你可能希望针对 FHIR 规范未定义为标准搜索参数的资源中的元素进行搜索。本文介绍如何定义自己的自定义搜索参数，以便在 Azure Health Data Services 的 FHIR 服务中使用。

注意

每次创建、更新或删除搜索参数时，都需要运行重新编制索引作业，以便为实时生产启用搜索参数。下面，我们将概述如何在重新编制整个 FHIR 服务数据库索引之前测试搜索参数。

创建新搜索参数

若要创建新的搜索参数，需要将POSTSearchParameter资源指向 FHIR 服务数据库。

POST {{FHIR_URL}}/SearchParameter

下面的示例演示如何创建新的自定义搜索参数

在实现指南中为每个定义创建新的搜索参数

下面的代码示例演示如何将 US Core Race 搜索参数添加到 Patient FHIR 服务数据库中的资源类型。

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

为具有引用类型的资源属性创建新的搜索参数

该代码示例演示如何创建自定义搜索参数，以根据分配位置搜索 MedicationDispense 资源。这是为引用类型添加自定义搜索参数的示例。

{
 "resourceType": "SearchParameter",
  "id": "a3c28d46-fd06-49ca-aea7-5f9314ef0497",
  "url": "{{An absolute URI that is used to identify this search parameter}}",
  "version": "1.0",
  "name": "MedicationDispenseLocationSearchParameter",
  "status": "active",
  "description": "Search parameter for MedicationDispense by location",
  "code": "location",
  "base": ["MedicationDispense"],
  "target": ["Location"],
  "type": "reference",
  "expression": "MedicationDispense.location"
}

注意

将搜索参数添加到数据库并重新编制数据库索引后POST，新的搜索参数将显示在 FHIR 服务的功能语句中。 SearchParameter查看功能语句中的是判断 FHIR 服务中是否支持搜索参数的唯一方法。如果在功能语句中找不到 SearchParameter ，则仍需要重新编制数据库索引以激活搜索参数。在触发重新编制索引操作之前，可以 POST 有多个搜索参数。

资源的重要元素 SearchParameter ：

url：描述搜索参数的唯一键。 HL7 等组织为其定义的搜索参数使用标准 URL 格式，如上述 US Core Race 搜索参数所示。
code：代码元素中存储的值是包含在 API 调用中时用于搜索参数的名称。对于上述具有“US Core Race”扩展的示例，你将使用 GET {{FHIR_URL}}/Patient?race=<code> 从指定编码系统设置的值中的 where <code> 进行搜索。此调用将检索特定种族的所有患者。
base：描述搜索参数) (适用的资源类型。如果搜索参数适用于所有资源，则可以使用 Resource;否则，可以列出所有相关资源类型。
target：描述搜索参数 () 匹配的资源类型。
type：描述搜索参数的数据类型。类型受 FHIR 服务中数据类型支持的限制。这意味着，除非它是受支持的组合，否则无法定义类型为 Special 的搜索参数或定义复合搜索参数。
expression：描述如何计算搜索的值。描述搜索参数时，必须包含表达式，即使规范不要求表达式也是如此。这是因为需要表达式或 xpath 语法，而 FHIR 服务会忽略 xpath 语法。

测试新的搜索参数

虽然在运行重新编制索引作业之前不能在生产环境中使用新的搜索参数，但在重新编制整个数据库的索引之前，有几种方法可以测试自定义搜索参数。

首先，可以测试新的搜索参数，以查看将返回哪些值。通过通过提供资源 ID) 对特定资源实例运行以下命令 (，可以返回一个值对列表，其中包含搜索参数名称和存储在相应元素中的值。此列表包括资源的所有搜索参数。可以滚动浏览以查找创建的搜索参数。运行此命令不会更改 FHIR 服务中的任何行为。

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

运行此 POST 调用为请求中指定的资源实例定义的任何搜索参数设置索引。此调用确实对 FHIR 服务数据库进行更改。现在，可以搜索并将标头设置为 x-ms-use-partial-indicestrue，这会导致 FHIR 服务返回已编制搜索参数索引的任何资源的结果，即使并非所有该类型的资源实例都为其编制了索引。

继续我们的示例，可以为一名患者编制索引以启用 SearchParameter：

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

然后执行测试搜索

对于按种族分类的患者：

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

对于“位置 (引用类型) ：

{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

测试新的搜索参数并确认其按预期工作后，运行或计划重新编制索引作业，以便新的搜索参数 () 可以在实时生产中使用。

有关如何对 FHIR 服务数据库重新编制索引的信息，请参阅运行重新编制索引作业。

更新搜索参数

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

注意

如果不知道搜索参数的 ID，可以使用进行搜索 GET {{FHIR_URL}}/SearchParameter。这将返回所有自定义和标准搜索参数，你可以滚动浏览列表以查找所需的搜索参数。还可以按名称限制搜索。如以下示例请求所示，自定义 SearchParameter 资源实例的名称为 USCoreRace。可以使用按名称GET {{FHIR_URL}}/SearchParameter?name=USCoreRace搜索此SearchParameter资源。

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 的资源。

警告

更新搜索参数时要小心。更改现有搜索参数可能会影响预期行为。建议立即运行重新编制索引作业。

删除搜索参数

如果需要删除搜索参数，请使用以下命令：

DELETE {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

警告

删除搜索参数时要小心。删除现有搜索参数可能会影响预期行为。建议立即运行重新编制索引作业。

后续步骤

本文介绍了如何创建自定义搜索参数。接下来，可以了解如何为 FHIR 服务数据库重新编制索引。有关详细信息，请参阅

如何运行重新索引作业

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