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

# 使用 PATCH 操作修改資源
<a name="managing-fhir-resources-patch"></a>

AWS HealthLake 支援 FHIR 資源的 PATCH 操作，可讓您透過鎖定要新增、取代或刪除的特定元素來修改資源，而無需更新整個資源。當您需要執行下列動作時，此操作特別有用：
+ 對大型資源進行目標性更新
+ 減少網路頻寬用量
+ 對特定資源元素執行原子修改
+ 將覆寫並行變更的風險降至最低
+ 在批次和交易工作流程中更新資源

## 支援的修補程式格式
<a name="patch-supported-formats"></a>

AWS HealthLake 支援兩種標準 PATCH 格式：

### JSON 修補程式 (RFC 6902)
<a name="patch-format-json"></a>

使用 JSON 指標語法，依其在資源結構中的位置來鎖定元素。

**Content-Type：** `application/json-patch+json`

### FHIRPath 修補程式 (FHIR R4 規格）
<a name="patch-format-fhirpath"></a>

使用 FHIRPath 表達式，依其內容和關係來鎖定元素，提供 FHIR 原生的修補方法。

**Content-Type：** `application/fhir+json`

## Usage
<a name="patch-usage"></a>

### 直接修補操作
<a name="patch-usage-direct"></a>

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

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

### 套件中的 PATCH
<a name="patch-usage-bundles"></a>

PATCH 操作可以包含在類型 `batch`或 的 FHIR 套件中作為項目`transaction`，讓您能夠在單一請求中將修補程式操作與其他 FHIR 互動 （建立、讀取、更新、刪除） 結合。
+ **交易套件**：所有項目都會以原子方式成功或失敗
+ **批次套件**：每個項目都會獨立處理

## JSON 修補程式格式
<a name="patch-json-format"></a>

### 受支援的 操作
<a name="patch-json-supported-operations"></a>


| 作業 | Description | 
| --- | --- | 
| add | 將新值新增至資源 | 
| remove | 從資源移除值 | 
| replace | 取代 資源中的現有值 | 
| move | 從一個位置移除值，並將其新增至另一個位置 | 
| copy | 將值從一個位置複製到另一個位置 | 
| test | 測試目標位置的值是否等於指定的值 | 

### 路徑語法
<a name="patch-json-path-syntax"></a>

JSON 修補程式使用 JSON 指標語法 (RFC 6901)：


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

### 範例
<a name="patch-json-examples"></a>

**具有多個操作的直接 JSON 修補程式請求**  


```
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": "555-555-5555",
      "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"
  }
]
```

**使用單一操作的直接 JSON 修補程式請求**  


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

[
  {
    "op": "replace",
    "path": "/active",
    "value": false
  }
]
```

**套件中的 JSON 修補程式**  
使用包含 base64 編碼 JSON 修補程式承載的二進位資源：

```
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [{
    "resource": {
      "resourceType": "Binary",
      "contentType": "application/json-patch+json",
      "data": "W3sib3AiOiJhZGQiLCJwYXRoIjoiL2JpcnRoRGF0ZSIsInZhbHVlIjoiMTk5MC0wMS0wMSJ9XQ=="
    },
    "request": {
      "method": "PATCH",
      "url": "Patient/123"
    }
  }]
}
```

## FHIRPath 修補程式格式
<a name="patch-fhirpath-format"></a>

### 受支援的 操作
<a name="patch-fhirpath-supported-operations"></a>


| 作業 | Description | 
| --- | --- | 
| add | 將新元素新增至資源 | 
| insert | 在清單中的特定位置插入 元素 | 
| delete | 從資源移除 元素 | 
| replace | 取代現有元素的值 | 
| move | 重新排序清單中的元素 | 

### 路徑語法
<a name="patch-fhirpath-path-syntax"></a>

FHIRPath 修補程式使用 FHIRPath 表達式，支援：
+ **索引型存取**： `Patient.name[0]`
+ **使用 篩選`where()`**： `Patient.name.where(use = 'official')`
+ **布林值邏輯**： `Patient.telecom.where(system = 'phone' and use = 'work')`
+ **子設定函數**：`first()`、 `last()`
+ **存在性檢查**：`exists()`、 `count()`
+ **多態導覽**： `Observation.value`

### 範例
<a name="patch-fhirpath-examples"></a>

**Direct FHIRPath 修補程式請求**  


```
PATCH [base]/Patient/123
Content-Type: application/fhir+json
Authorization: ...

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "operation",
    "part": [
      { "name": "type", "valueCode": "add" },
      { "name": "path", "valueString": "Patient" },
      { "name": "name", "valueString": "birthDate" },
      { "name": "value", "valueDate": "1990-01-01" }
    ]
  }]
}
```

**套件中的 FHIRPath 修補程式**  
透過 使用參數資源做為項目資源`method: PATCH`：

```
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [{
    "resource": {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "operation",
        "part": [
          { "name": "type", "valueCode": "add" },
          { "name": "path", "valueString": "Patient" },
          { "name": "name", "valueString": "birthDate" },
          { "name": "value", "valueDate": "1990-01-01" }
        ]
      }]
    },
    "request": {
      "method": "PATCH",
      "url": "Patient/123"
    }
  }]
}
```

## 請求標頭
<a name="patch-request-headers"></a>


| 標頭 | 必要 | 描述 | 
| --- | --- | --- | 
| Content-Type | 是 | application/json-patch\$1json 適用於 JSON 修補程式或application/fhir\$1json適用於 FHIRPath 修補程式 | 
| If-Match | 否 | 使用 ETag 的特定版本條件更新 | 

## 回應範例
<a name="patch-sample-response"></a>

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

```
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": "555-555-5555",
      "use": "home"
    }
  ],
  "meta": {
    "versionId": "2",
    "lastUpdated": "2025-05-05T10:10:10Z"
  }
}
```

## Behavior (行為)
<a name="patch-behavior"></a>

PATCH 操作：
+ 根據適當的規格驗證修補程式語法 (RFC 6902 for JSON Patch、FHIR R4 for FHIRPath Patch)
+ 以原子方式套用操作 - 所有操作成功或全部失敗
+ 更新資源版本 ID 並建立新的歷史記錄項目
+ 在套用變更之前，保留歷史記錄中的原始資源
+ 套用修補程式後驗證 FHIR 資源限制
+ 支援使用 If-Match 標頭搭配 ETag 進行條件式更新

## 錯誤處理
<a name="patch-error-handling"></a>

操作會處理下列錯誤條件：
+ **400 錯誤的請求**：無效的修補程式語法 （不符合的請求或格式錯誤的修補程式文件）
+ **找不到 404**：找不到資源 （指定的 ID 不存在）
+ **409 衝突**：版本衝突 （提供並行更新或非目前版本 ID)
+ **422 無法處理的實體**：修補程式操作無法套用至指定的資源元素

## 功能摘要
<a name="patch-summary-of-capabilities"></a>


| 功能 | JSON 修補程式 | FHIRPath 修補程式 | 
| --- | --- | --- | 
| 內容類型 | application/json-patch\$1json | application/fhir\$1json | 
| 路徑格式 | JSON 指標 (RFC 6901) | FHIRPath 表達式 | 
| Direct PATCH API | 支援 | 支援 | 
| 套件批次 | 支援 （透過二進位） | 支援 （透過參數） | 
| 套件交易 | 支援 （透過二進位） | 支援 （透過參數） | 
| 操作 | 新增、移除、取代、移動、複製、測試 | 新增、插入、刪除、取代、移動 | 

## 限制
<a name="patch-limitations"></a>
+ 不支援使用搜尋條件的條件式 PATCH 操作
+ 套件中的 JSON 修補程式必須使用具有 base64 編碼內容的二進位資源
+ 套件中的 FHIRPath 修補程式必須使用參數資源

## 其他資源
<a name="patch-additional-resources"></a>

如需 PATCH 操作的詳細資訊，請參閱：
+ [FHIR R4 修補文件](https://hl7.org/fhir/http.html#patch)
+ [FHIR R4 FHIRPath 修補程式規格](https://hl7.org/fhir/fhirpatch.html)
+ [RFC 6902 - JSON 修補程式](https://datatracker.ietf.org/doc/html/rfc6902#section-4)
+ [RFC 6901 - JSON 指標](https://datatracker.ietf.org/doc/html/rfc6901)