秘訣
推薦項目: 從 Work IQ 開發工具 開始,支援專業程式碼宣告式代理程式和外掛程式案例。 請參閱 WIQD 快速入門。 工具組式指示仍然適用於需要工具組的指示的現有專案和工作流程。 在選擇工具之前,請先檢查 功能和目標體驗支援 : WIQD 不會以自訂引擎代理程式為目標。
某些 API 會使用 API 金鑰進行授權。 API 金鑰是用戶端包含在 API 請求中的共用密碼,用於驗證和取得存取權。 API 外掛程式支援以三種方式傳送 API 金鑰:
- 作為標頭中的
Authorization持有人權杖 - 做為自訂標頭中的值
- 做為查詢參數
注意
對於宣告式代理程式動作,API 金鑰驗證適用於從 OpenAPI 文件建置的 API 外掛程式,而不是 MCP 外掛程式。 對於代理程式的 MCP 外掛程式,請使用 OAuth 2.0 (,包括動態用戶端註冊) 或 Microsoft Entra SSO。 套件層級遠端 MCP 連線使用不同的組態;請參閱 應用程式資訊清單中的驗證。
透過兩個步驟設定 API 金鑰驗證:將 API 金鑰新增至 OpenAPI 文件,然後建立 API 金鑰驗證設定。
步驟 1:將 API 金鑰新增至 OpenAPI 文件
Microsoft 365 Copilot 會根據 OpenAPI 文件中的項目決定securitySchemes如何傳送 API 金鑰。
持有人權杖
如果您的 API 接受 API 金鑰作為持有人權杖,請在 OpenAPI 文件中啟用持有人驗證。 如需詳細資訊,請參閱 持有人驗證。
securitySchemes:
BearerAuth:
type: http
scheme: bearer
自訂標頭
如果您的 API 接受自訂標頭中的 API 金鑰,請在 OpenAPI 文件中啟用 API 金鑰驗證,並將in屬性設定為headername標頭名稱。 如需詳細資訊,請參閱 API 金鑰。
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
查詢參數
如果您的 API 接受查詢參數中的 API 金鑰,請將屬性設定為queryname,並將屬性設定為in查詢參數的名稱,以在 OpenAPI 文件中啟用 API 金鑰驗證。 如需詳細資訊,請參閱 API 金鑰。
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
步驟 2:建立 API 金鑰驗證設定
API 金鑰驗證仰賴驗證設定 (驗證設定) - 儲存在 Microsoft Enterprise 權杖存放區中的記錄,當您的外掛程式呼叫 API 時,Microsoft 365 Copilot 使用它來傳送 API 金鑰。 從支援的專業程式碼專案的 WIQD 開始。 工具組和 Microsoft Teams 開發人員入口網站程序仍然可供您使用。 宣告式代理程式開發人員技能不支援 API 金鑰驗證,因為它會建置 MCP 外掛程式。
使用 Work IQ 開發工具 (建議)
對於現有的 API 外掛程式資訊清單,請搭配--plugin-manifest使用 wiqd agent add auth 、 --auth-name和 --auth-type api-key。 設定 --api-key-in 為 header 或 query 和 為 --api-key-name OpenAPI 安全性配置中的名稱。 如果 API 接受其金鑰作為持有人權杖,請選取 --auth-type bearer-token。
從 OpenAPI 文件新增動作時, wiqd agent add action 接受 --api-key API 金鑰或持有人認證。 省略該值時,命令會記錄環境預留位置。 遵循所選命令的認證處理,並完成專案的佈建工作流程。 這些 API 金鑰選項不會為代理程式的 MCP 外掛程式建立 API 金鑰支援。
使用 Microsoft 365 代理程式工具組
當您從 Microsoft 365 Agents Toolkit 中的現有 OpenAPI 文件建立 API 外掛程式時,該工具組會註冊 API 金鑰、建立驗證設定,並為您更新您的外掛程式資訊清單。 您必須在 OpenAPI 文件中定義 securitySchemes 屬性。
使用 Teams 開發人員入口網站
如果您使用 Agents Toolkit,則可選擇是否在 Teams 開發人員入口網站註冊。 使用它手動建立驗證組態,或管理 Agents Toolkit 已建立的驗證組態。
開啟 Teams 開發人員入口網站。 選取 [ 工具] ->API 金鑰註冊。
如果您沒有現有註冊,請選取 [建立 API 金鑰]。 如果您有現有註冊,請選取 新增 API 金鑰。
選取新增 密碼 ,然後輸入 API 金鑰。
填寫下列欄位。
- API 金鑰名稱:註冊的易記名稱。
-
基底 URL:您的 API 基底 URL。 此值應對應至 OpenAPI 文件中陣列中的
servers項目。 - 目標租用戶:限制主要租用戶的 API 存取權,或允許任何租用戶。
- 目標 Teams 應用程式:如果您不知道最終的應用程式識別碼,請選取 任何 Teams 應用程式 。 發佈應用程式之後,請將此註冊與已發佈的應用程式識別碼繫結。
選取 [儲存]。
完成註冊會產生 驗證設定識別碼 , (Teams 開發人員入口網站) 中目前標示為 API 金鑰註冊識別碼 。
將驗證設定識別碼新增至外掛程式資訊清單
當您在 Teams 開發人員入口網站手動建立驗證設定時,請將執行階段驗證物件的屬性設定type為 ApiKeyPluginVault,並將 設定為reference_id驗證設定識別碼。 Agents Toolkit 可以為您執行此動作。
"auth": {
"type": "ApiKeyPluginVault",
"reference_id": "auth config ID"
},