OpenAPI 規格整合 - Amazon Quick
您可以做什麼開始之前準備 OpenAPI 規格和身分驗證設定 OpenAPI 規格整合格式和模式需求不支援的功能結構描述最佳實務支援的擴充功能結構描述驗證和錯誤處理管理 OpenAPI 規格整合故障診斷 OpenAPI 規格整合

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

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 主控台中，選擇整合。

  2. 按一下新增 （加 "+" 按鈕）。

  3. 在新增結構描述頁面上，選取匯入結構描述，然後選擇要匯入的結構描述。

  4. 選取下一步。

  5. 填寫整合詳細資訊，包括名稱和描述。

  6. 檢閱從 OpenAPI 規格產生的可用動作。

  7. 選取建立並繼續。

  8. 選擇要與之共用整合的使用者。

  9. 按一下 Next (下一步)。

預期的結果

成功設定後，您的 OpenAPI 規格整合會顯示在整合清單中，其中包含根據您的結構描述動態產生的動作。整合可用於 Amazon Quick 工作流程、自動化和 AI 代理器，以及與 OpenAPI 規格中定義的端點對應的任務。

格式和模式需求

您的 OpenAPI 規格必須遵循這些格式要求。

  • 路徑模式 - 必須遵循模式： ^/[^/]*(/[^/]*)*$並以正斜線 (/) 開頭。

  • 操作 IDs - 必須遵循模式：^[a-zA-Z0-9_ ]{1,256}$。

  • 描述 - 所有操作和參數都需要，最多 5000 個字元。

  • 內容類型 - 請求和回應內文僅支援應用程式/json。

不支援的功能

不支援下列 OpenAPI 功能，這會導致驗證錯誤。

  • 陣列類型 - 不支援具有陣列類型的結構描述 （例如 {"type": "array", "items": {"string"}})。

  • 合成關鍵字 - 不支援 allOf、oneOf、anyOf 和非關鍵字。

  • 循環參考 - 不支援循環參考 ($ref 內的 $ref)。

  • 複雜巢狀結構 - 盡可能避免深度巢狀物件結構。

結構描述最佳實務

建立 OpenAPI 規格時，請遵循這些最佳實務。

撰寫有效的描述

使用這些準則來撰寫清楚且實用的描述。

  • 操作描述 - 描述操作的功能、使用時機，以及其行為。

  • 參數描述 - 簡要說明參數的目的和對操作行為的影響。

  • 獨立內容 - 確保描述提供足夠的指引，無需外部參考。

  • 相依性清晰度 - 在描述中明確地建立操作之間的相依性。

  • 操作參考 - 在參考其他操作時使用 operationId，而不是 API 路徑。

參數結構建議

建構您的參數以獲得最佳可用性。

  • 扁平化複雜物件 - 使用不同的參數 （例如 start_date、start_time、end_date、end_time)，而非巢狀物件。

  • 使用標準格式 - 針對 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 整合詳細資訊頁面，選擇共用。

  2. 設定共用選項：

    • 與特定使用者共用 - 輸入使用者名稱或電子郵件地址。

    • 與組織共用 - 可供組織中的所有使用者使用。

  3. 設定共用存取的許可層級。

  4. 選擇共用整合以套用共用設定。

刪除整合

請依照下列步驟永久移除您的 OpenAPI 整合。

  1. 從 OpenAPI 整合詳細資訊頁面，選擇刪除。

  2. 檢閱刪除影響，包括使用此整合的任何工作流程或自動化。

  3. 輸入整合名稱以確認刪除。

  4. 選擇刪除整合以永久移除它。

故障診斷 OpenAPI 規格整合

使用這些疑難排解秘訣來解決常見的 OpenAPI 規格整合問題。

結構描述驗證錯誤

確保您的 OpenAPI 規格遵循正確的格式，並包含所有必要欄位。使用 OpenAPI 驗證器在匯入之前檢查您的結構描述。

未產生任何任務

確認您的 OpenAPI 規格包含具有 HTTP 方法和操作 IDs路徑定義。動作會根據結構描述中定義的操作產生。

身分驗證失敗

檢查 OpenAPI 規格中定義的身分驗證機制是否符合實際 API 需求，並正確設定登入資料。

動作執行失敗

檢閱動作參數，並確保它們符合您 OpenAPI 規格中的參數定義，包括必要欄位和資料類型。