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

# 匯入 OpenAPI 檔案以更新現有的 API 定義
<a name="api-gateway-import-api-update"></a>

 您可以匯入 API 定義只更新現有的 API，無需變更其端點組態，以及階段與階段變數，或參考 API 金鑰。

 匯入到更新操作可在兩種模式下進行：合併或覆寫。

當 API (`A`) 合併到另一個 (`B`)，如果兩個 API 不共用任何衝突的定義，則產生的 API 會保留 `A` 和 `B` 兩者的定義。發生衝突時，合併 API (`A`) 之方法定義會覆寫被合併 API (`B`) 的對應方法定義。例如，假設 `B` 已宣告以下列方法傳回 `200` 和 `206` 回應：

```
GET /a
POST /a
```

而 `A` 宣告以下列方法傳回 `200` 和 `400` 回應：

```
GET /a
```

當 `A` 合併到 `B`，產生的 API 會產出以下方法：

```
GET /a
```

傳回 `200` 和 `400` 回應，且 

```
POST /a
```

傳回 `200` 和 `206` 回應。

合併 API 適用於您已將外部 API 定義分解成多個更小的組件，而且一次只想要套用其中一個組件的變更時。例如，如果多個小組負責 API 的不同組件並有不同速率的變更時，則可能會出現此情況。在此模式下，現有 API 中的項目若在已匯入的定義中沒有特別定義，則會保持不變。

當 API (`A`) 覆寫另一個 API (`B`)，產生的 API 會採用覆寫的 API (`A`) 之定義。覆寫 API 適用於外部 API 定義包含完整的 API 定義時。在此模式下，現有 API 中的項目若在已匯入的定義中沒有特別定義，則會遭到刪除。

 若要合併 API，請將 `PUT` 請求提交給 `https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=merge`。`restapi_id` 路徑參數值指定要與所提供的 API 定義合併的 API。

 下列程式碼片段顯示 `PUT` 請求範例，其中會將 JSON 中的 OpenAPI API 定義做為承載與 API Gateway 中已指定的 API 合併。

```
PUT /restapis/<restapi_id>?mode=merge
Host:apigateway.<region>.amazonaws.com
Content-Type: application/json
Content-Length: ...

An OpenAPI API definition in JSON
```

 合併更新操作可將兩個完整的 API 定義合併在一起。對於小型累加變更，您可以使用​[資源更新](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)操作。

 若要覆寫 API，請將 `PUT` 請求提交給 `https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=overwrite`。`restapi_id` 路徑參數指定要使用所提供 API 定義覆寫的 API。

 下列程式碼片段顯示使用 JSON 格式 OpenAPI 定義的承載覆寫請求的範例：

```
PUT /restapis/<restapi_id>?mode=overwrite
Host:apigateway.<region>.amazonaws.com
Content-Type: application/json
Content-Length: ...

An OpenAPI API definition in JSON
```

 未指定 `mode` 查詢參數時，會假設使用合併。

**注意**  
 `PUT` 操作為等冪，但不可部分完成。這表示如果在處理到一半時發生系統錯誤，API 最後可能會是錯誤狀態。不過，重複此操作會成功將 API 放到相同的最終狀態，就像是成功進行的第一個操作。