使用 PATCH 操作修改資源 - AWS HealthLake
使用方式支援的 PATCH 操作請求標頭範例JSON 修補程式路徑語法Behavior (行為)錯誤處理警告

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 PATCH 操作修改資源

AWS HealthLake 現在支援 FHIR 資源的 PATCH 操作，可讓您將要新增、取代或刪除的特定元素設定為目標，以修改資源，而無需更新整個資源。此操作特別適用於遠端用戶端或頻寬有限的用戶端，以降低網路用量。當您需要下列項目時，此操作特別有用：

  • 對大型資源進行目標性更新

  • 減少網路頻寬用量

  • 對特定資源元素執行原子修改

  • 將覆寫並行變更的風險降至最低

使用方式

您可以使用 PATCH HTTP 方法在 FHIR 資源上叫用 PATCH 操作：

受支援的 操作

PATCH [base]/[resource-type]/[id]{?_format=[mime-type]}

支援的 PATCH 操作

HealthLake 根據 RFC 6902 支援下列 JSON 修補程式操作：

作業 描述
add 將新值新增至資源
remove 從資源移除值
replace 取代 資源中的現有值
move 在功能上與「從」位置上的「移除」操作相同，然後立即在目標位置使用剛移除的值進行「新增」操作
copy 將指定位置的值複製到目標位置
test 測試目標位置的值是否等於指定的值

請求標頭

標頭 必要 描述
Content-Type 是 必須為 application/json-patch+json
If-Match 否 使用 ETag 的特定版本條件更新

範例

具有多個操作的修補請求

PATCH [base]/Patient/example
Content-Type: application/json-patch+json
If-Match: W/"1"

[
  {
    "op": "replace",
    "path": "/name/0/family",
    "value": "Smith"
  },
  {
    "op": "add",
    "path": "/telecom/-",
    "value": {
      "system": "phone",
      "value": "************",
      "use": "home"
    }
  },
  {
    "op": "remove",
    "path": "/address/0"
  },
  {
    "op": "move",
    "from": "/name/0/family",
    "path": "/name/1/family"
  },
  {
    "op": "test",
    "path": "/gender",
    "value": "male"
  },
  {
    "op": "copy",
    "from": "/name/0",
    "path": "/name/1"
  }
]
單一操作的修補請求

PATCH [base]/Patient/example
Content-Type: application/json-patch+json

[
  {
    "op": "replace",
    "path": "/active",
    "value": false
  }
]
回應範例

操作會傳回具有新版本資訊的更新資源：

HTTP/1.1 200 OK
Content-Type: application/fhir+json
ETag: W/"2"
Last-Modified: Mon, 05 May 2025 10:10:10 GMT

{
  "resourceType": "Patient",
  "id": "example",
  "active": true,
  "name": [
    {
      "family": "Smith",
      "given": ["John"]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "************",
      "use": "home"
    }
  ],
  "meta": {
    "versionId": "2",
    "lastUpdated": "2025-05-05T10:10:10Z"
  }
}

JSON 修補程式路徑語法

路徑參數使用 JSON 指標語法 (RFC 6901)：

路徑範例 描述
/name/0/family 名字的系列元素
/telecom/- 附加至電信陣列
/active 根層級作用中元素
/address/0/line/1 第一地址的第二行

Behavior (行為)

PATCH 操作：

  1. 根據 RFC 6902 和 RFC 6901 驗證 JSON 修補程式語法

  2. 以原子方式套用操作 - 所有操作成功或全部失敗

  3. 更新資源版本 ID 並建立新的歷史記錄項目

  4. 在套用變更之前，保留歷史記錄中的原始資源

  5. 套用修補程式後驗證 FHIR 資源限制

  6. 支援使用 If-Match 標頭搭配 ETag 進行條件式更新

錯誤處理

操作會處理下列錯誤條件：

  • 400 錯誤的請求：無效的修補程式語法 （不符合的請求或格式錯誤的 JSON 修補程式）

  • 找不到 404：找不到資源 （指定的 ID 不存在）

  • 409 衝突：版本衝突 （提供並行更新或非目前版本 ID)

  • 422 無法處理的實體：修補程式操作無法套用至指定的資源元素

警告

  • 僅支援application/json-patch+json內容類型

  • 不支援使用搜尋條件的條件式 PATCH 操作

如需 PATCH 操作的詳細資訊，請參閱 FHIR R4 PATCH 文件。