本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# OpenAPI 規格整合
透過 OpenAPI 規格整合，您可以根據 OpenAPI 結構描述建立自訂整合。這可讓您連線到任何提供 OpenAPI 規格的 API。此整合僅支援動作執行，且需要 Amazon Quick Pro 層或更高版本。
## 您可以做什麼
OpenAPI 規格整合提供結構描述型連線，協助您使用自訂 APIs。
**動作連接器**
根據 OpenAPI 規格執行動作。根據提供的結構描述，透過動態產生的動作執行 API 呼叫、管理資源，以及與自訂服務互動。
**結構描述型組態**
匯入 OpenAPI 規格以自動產生可用的動作和動作。支援 JSON 結構描述驗證和參數映射。
## 開始之前
設定 OpenAPI 規格整合之前，請確定您有下列項目：
+ 目標 API 的 OpenAPI 規格 (3.0.0 版或更新版本）。
+ API 身分驗證登入資料 (API 金鑰、OAuth 或其他）。
+ Amazon Quick Author 或更新版本。
+ API 文件和端點存取。
## 準備 OpenAPI 規格和身分驗證
在 Amazon Quick 中設定整合之前，請準備您的 OpenAPI 規格和身分驗證憑證。您的 OpenAPI 規格必須符合特定要求，才能成功整合。
### 基本要求
您的 OpenAPI 規格必須符合這些基本要求。
+ **OpenAPI 版本** - 需要 3.0.0 版或更新版本。
+ **檔案格式** - 僅限 JSON 格式 (application/json)。
+ **檔案大小限制** - 整個 OpenAPI 規格的上限為 1MB。
+ **操作限制** - 每個連接器最少 1 個，最多 100 個 API 操作。
### 必要的結構描述欄位
您的 OpenAPI 規格必須包含這些必要的區段。
**Openapi**
正在使用的 OpenAPI 版本 （必須為「3.0.0」或更新版本）。
**info**
服務資訊，包括標題、描述和版本。
**伺服器**
API 連線的基本 URL 和伺服器資訊。
**路徑**
具有 HTTP 方法和操作的 API 端點定義。
### 支援的身分驗證機制
根據 OpenAPI 規格中支援的身分驗證方法準備身分驗證憑證。
**OAuth 2.0**
同時支援授權碼授予和用戶端登入資料授予流程。需要安全機制中的 authorizationUrl、tokenUrl 和範圍定義。
**API 金鑰**
在查詢參數或標頭中傳遞的 API 金鑰身分驗證。
**無身分驗證**
規格中未定義任何安全機制時的預設選項。
**注意**
OpenAPI 規格中不支援的身分驗證機制將被忽略，連接器預設為無身分驗證。
## 設定 OpenAPI 規格整合
準備 OpenAPI 規格和身分驗證憑證之後，請依照下列步驟建立 OpenAPI 規格整合。
1. 在 Amazon Quick 主控台中，選擇**整合**。
1. 按一下**新增** （加 "\$1" 按鈕）。
1. 在新增結構描述頁面上，選取**匯入結構描述**，然後選擇要匯入的結構描述。
1. 選取**下一步**。
1. 填寫整合詳細資訊，包括名稱和描述。
1. 檢閱從 OpenAPI 規格產生的可用動作。
1. 選取**建立並繼續**。
1. 選擇要與之共用整合的使用者。
1. 按一下 **Next (下一步)**。
### 預期的結果
成功設定後，您的 OpenAPI 規格整合會顯示在整合清單中，其中包含根據您的結構描述動態產生的動作。整合可用於 Amazon Quick 工作流程、自動化和 AI 代理器，以及與 OpenAPI 規格中定義的端點對應的任務。
## 格式和模式需求
您的 OpenAPI 規格必須遵循這些格式要求。
+ **路徑模式** - 必須遵循模式： `^/[^/]*(/[^/]*)*$`並以正斜線 (/) 開頭。
+ **操作 IDs** - 必須遵循模式：`^[a-zA-Z0-9_ ]{1,256}$`。
+ **描述** - 所有操作和參數都需要，最多 5000 個字元。
+ **內容類型** - 請求和回應內文僅支援應用程式/json。
## 不支援的功能
不支援下列 OpenAPI 功能，這會導致驗證錯誤。
+ **陣列類型** - 不支援具有陣列類型的結構描述 （例如 `{"type": "array", "items": {"string"}}`)。
+ **合成關鍵字** - 不支援 allOf、oneOf、anyOf 和非關鍵字。
+ **循環參考** - 不支援循環參考 (\$1ref 內的 \$1ref)。
+ **複雜巢狀結構** - 盡可能避免深度巢狀物件結構。
## 結構描述最佳實務
建立 OpenAPI 規格時，請遵循這些最佳實務。
### 撰寫有效的描述
使用這些準則來撰寫清楚且實用的描述。
+ **操作描述** - 描述操作的功能、使用時機，以及其行為。
+ **參數描述** - 簡要說明參數的目的和對操作行為的影響。
+ **獨立內容** - 確保描述提供足夠的指引，無需外部參考。
+ **相依性清晰度** - 在描述中明確地建立操作之間的相依性。
+ **操作參考** - 在參考其他操作時使用 operationId，而不是 API 路徑。
### 參數結構建議
建構您的參數以獲得最佳可用性。
+ **扁平化複雜物件** - 使用不同的參數 （例如 start\$1date、start\$1time、end\$1date、end\$1time)，而非巢狀物件。
+ **使用標準格式** - 針對 ISO-8601 日期和時間使用標準格式值，例如 "date-time" 或 "date"。
+ **清除參數名稱** - 使用明確指出其用途的描述性參數名稱。
+ **必要欄位標記** - 根據 API 行為，將參數正確標記為必要或選用。
## 支援的擴充功能
我們支援自訂 OpenAPI 擴充功能，以增強使用者體驗。
**x-amzn-form-display-name**
在參數層級使用 來覆寫確認表單中顯示的預設欄位名稱。目前僅支援請求內文參數。
```
"x-amzn-form-display-name": "User Name"
```
**x-amzn-operation-type**
定義操作是否應視為「讀取」或「寫入」。根據預設，GET 方法為「讀取」操作，所有其他 HTTP 方法為「寫入」操作。
```
"x-amzn-operation-type": "read"
```
## 結構描述驗證和錯誤處理
當您上傳 OpenAPI 規格時，我們會執行全面的驗證。
+ **檔案大小驗證** - 確保規格不超過 1MB。
+ **操作計數驗證** - 已定義 1-100 個操作之間的驗證。
+ **結構描述結構驗證** - 檢查必要欄位和適當的格式。
+ **安全機制驗證** - 驗證支援的身分驗證方法。
+ **內容類型驗證** - 確保僅使用應用程式/json。
驗證錯誤會顯示在結構描述編輯器下方，必須先解決才能建立整合。常見的驗證問題包括：
+ 缺少必要欄位 (openapi、資訊、伺服器、路徑）。
+ 無效的路徑模式或操作 IDs。
+ 不支援的結構描述功能 （陣列、合成關鍵字）。
+ 缺少描述或描述過長。
+ 結構描述定義中的循環參考。
## 管理 OpenAPI 規格整合
建立 OpenAPI 規格整合之後，您可以透過數個選項來管理它。
### 共用整合
您可以與組織中的其他使用者共用 OpenAPI 規格動作連接器。
1. 從 OpenAPI 整合詳細資訊頁面，選擇**共用**。
1. 設定共用選項：
+ **與特定使用者共用** - 輸入使用者名稱或電子郵件地址。
+ **與組織共用** - 可供組織中的所有使用者使用。
1. 設定共用存取的許可層級。
1. 選擇**共用整合**以套用共用設定。
### 刪除整合
請依照下列步驟永久移除您的 OpenAPI 整合。
1. 從 OpenAPI 整合詳細資訊頁面，選擇**刪除**。
1. 檢閱刪除影響，包括使用此整合的任何工作流程或自動化。
1. 輸入整合名稱以確認刪除。
1. 選擇**刪除整合**以永久移除它。
## 故障診斷 OpenAPI 規格整合
使用這些疑難排解秘訣來解決常見的 OpenAPI 規格整合問題。
結構描述驗證錯誤
確保您的 OpenAPI 規格遵循正確的格式，並包含所有必要欄位。使用 OpenAPI 驗證器在匯入之前檢查您的結構描述。
未產生任何任務
確認您的 OpenAPI 規格包含具有 HTTP 方法和操作 IDs路徑定義。動作會根據結構描述中定義的操作產生。
身分驗證失敗
檢查 OpenAPI 規格中定義的身分驗證機制是否符合實際 API 需求，並正確設定登入資料。
動作執行失敗
檢閱動作參數，並確保它們符合您 OpenAPI 規格中的參數定義，包括必要欄位和資料類型。