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

Azure API for FHIR 的 FHIR REST API 功能

项目
06/01/2023

本文介绍 Azure API for FHIR 的 RESTful 交互的一些细微差别。

条件创建/更新

Azure API for FHIR 支持 FHIR 规范定义的创建、条件创建、更新和条件更新。在这些方案中，一个有用的标头是 If-Match 标头。使用 If-Match 标头，并将在进行更新之前验证要更新的版本。 ETag如果与预期的 ETag不匹配，它将生成错误消息 412 前置条件失败。

删除和条件删除

Azure API for FHIR 提供两种删除类型。有 Delete，也称为硬删除 + 软删除和条件删除。

删除 (硬删除 + 软删除)

FHIR 规范定义的删除要求在删除资源后，资源的后续非版本特定读取将返回 410 HTTP 状态代码。因此，无法再通过搜索找到资源。此外，使用 Azure API for FHIR 可以完全删除 (包括资源) 所有历史记录。若要完全删除资源，可以将参数设置 hardDelete 传递给 true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true)。如果未传递此参数或将设置为 hardDelete false，则资源的历史版本仍然可用。

注意

如果只想删除历史记录，Azure API for FHIR 支持名为的 $purge-history自定义操作。此操作允许删除资源的历史记录。

条件删除

条件删除允许传递搜索条件以删除资源。默认情况下，条件删除允许一次删除一项。还可以指定参数， _count 一次最多删除 100 个项目。下面是使用条件删除的一些示例。

若要使用条件删除删除单个项，必须指定返回单个项的搜索条件。

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704

可以执行相同的搜索，但也可以包括 hardDelete=true 以删除所有历史记录。

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true

若要删除多个资源，请包含 _count=100 参数。此参数将删除最多 100 个与搜索条件匹配的资源。

DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100

恢复已删除的文件

如果不使用硬删除参数，则 Azure API for FHIR 中 () 的记录应仍然存在。可以通过对资源执行历史记录搜索并查找包含数据的最后一个版本来查找记录 () 。

如果已删除的资源的 ID 已知，请使用以下 URL 模式：

<FHIR_URL>/<resource-type>/<resource-id>/_history

例如： https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history

如果资源 ID 未知，请对整个资源类型执行历史记录搜索：

<FHIR_URL>/<resource-type>/_history

例如： https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history

找到要还原的记录后，使用 PUT 操作重新创建具有相同 ID 的资源，或使用 POST 操作创建具有相同信息的新资源。

注意

历史记录/软删除数据没有基于时间的过期时间。删除历史记录/软删除数据的唯一方法是使用硬删除或清除历史记录操作。

修补程序和条件修补程序

只需更新 FHIR 资源的一部分时，修补程序是一项有价值的 RESTful 操作。使用 patch 可以指定要在资源中更新的元素 () ，而无需更新整个记录。 FHIR 定义了三种修补资源的方法：JSON 修补程序、XML 修补程序和 FHIRPath 修补程序。 FHIR 服务支持 JSON 修补程序和 FHIRPath 修补程序以及条件 JSON 修补程序和条件 FHIRPath 修补程序 (这允许你根据搜索条件（而不是资源 ID) ）修补资源。若要演练一些示例，请参阅示例 FHIRPath Patch REST 文件和 JSON Patch REST 文件，了解每种方法。有关更多详细信息，请阅读使用 FHIR 进行修补操作的 HL7 文档。

注意

针对 STU3 使用 PATCH 时，如果请求历史记录捆绑包，则修补的资源的 Bundle.entry.request.method 映射到 PUT。这是因为 STU3 不包含 HTTPVerb 值集中谓PATCH词的定义。

使用 FHIRPath 修补程序进行修补

此修补方法最强大，因为它利用 FHIRPath 选择要面向的元素。一种常见方案是在不知道列表顺序的情况下使用 FHIRPath Patch 更新列表中的元素。例如，如果要在不知道索引的情况下删除患者的家庭电信信息，可以使用以下示例。

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Content-type： application/fhir+json

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "operation",
            "part": [
                {
                    "name": "type",
                    "valueCode": "delete"
                },
                {
                    "name": "path",
                    "valueString": "Patient.telecom.where(use = 'home')"
                }
            ]
        }
    ]
}

任何 FHIRPath Patch 操作都必须设置 application/fhir+json Content-Type 标头。 FHIRPatch 修补程序支持添加、插入、删除、删除和移动操作。 FHIRPatch Patch 操作也可以轻松集成到捆绑包中。有关更多示例，请查看示例 FHIRPath 修补程序 REST 文件。

使用 JSON 修补程序进行修补

FHIR 服务中的 JSON 修补程序符合 Internet 工程任务组定义的常用规范。有效负载格式不使用 FHIR 资源，而是使用利用元素选择JSON-Pointers的 JSON 文档。 JSON 修补程序更紧凑，并且具有一个测试操作，使你可以在执行修补之前验证条件是否为 true。例如，如果仅当患者尚未标记为已故时，才希望将患者设置为已故，则可以使用以下示例。

PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Content-type： application/json-patch+json

[
	{
		"op": "test",
		"path": "/deceasedBoolean",
		"value": false
	},
	{
		"op": "replace",
		"path": "/deceasedBoolean",
		"value": true
	}
]

任何 JSON Patch 操作都必须设置 application/json-patch+json Content-Type 标头。 JSON 修补程序支持添加、删除、替换、复制、移动和测试操作。有关更多示例，请查看示例 JSON 修补程序 REST 文件。

捆绑包中的 JSON 修补程序

默认情况下，捆绑包资源不支持 JSON 修补程序。这是因为捆绑包仅支持 FHIR 资源，而 JSON 修补程序有效负载不是 FHIR 资源。为了解决此问题，我们将使用内容类型为的 "application/json-patch+json" 二进制资源，并使用捆绑包中 JSON 有效负载的 base64 编码。有关此解决方法的信息，请在 FHIR 聊天 Zulip 上查看此主题。

在下面的示例中，我们希望将患者的性别更改为女性。我们已获取 JSON 修补程序 [{"op":"replace","path":"/gender","value":"female"}] 并将其编码为 base64。

POST https://{FHIR-SERVICE-HOST-NAME}/
Content-Type：application/json

{
	"resourceType": "Bundle",
	"id": "bundle-batch",
	"type": "batch",
	"entry": [
		{
			"fullUrl": "Patient/{PatientID}",
			"resource": {
				"resourceType": "Binary",
				"contentType": "application/json-patch+json",
				"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
			},
			"request": { 
				"method": "PATCH",
				"url": "Patient/{PatientID}"
			}
		}
	]
}

后续步骤

本文介绍了 Azure API for FHIR 的一些 REST 功能。接下来，可以详细了解在 FHIR 中搜索资源的关键方面。

在 Azure API for FHIR 中进行搜索的概述

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