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

定义自定义搜索参数

项目
10/16/2024

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 格式，如美国核心竞赛搜索参数中所示。
code：代码元素中存储的值是 API 调用中包含搜索参数时用于搜索参数的名称。对于具有“US Core Race”扩展的前面的示例，你将使用指定编码系统设置的值中的位置<code>进行搜索GET {{FHIR_URL}}/Patient?race=<code>。此调用将检索特定种族的所有患者。
base：描述搜索参数适用的资源类型。如果搜索参数适用于所有资源，则可以使用 Resource;否则，可以列出所有相关资源类型。
target：描述搜索参数匹配的资源类型。
type：描述搜索参数的数据类型。类型受 FHIR 服务中数据类型支持的限制。这意味着不能定义特殊类型的搜索参数或定义复合搜索参数，除非它是受支持的组合。
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-indices 标头 true，这会导致 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和PUT请求字符串的字段中包括搜索参数 IDid。

注意

如果不知道搜索参数的 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 许可使用。

通过