練習 -整合 API 外掛程式與使用金鑰保護的 API

9 分鐘

適用於 Microsoft 365 Copilot的 API 外掛程式可讓您與使用金鑰保護的 API 整合。您可以在 Teams 儲存庫中註冊 API 金鑰，以確保其安全。在運行時間，Microsoft 365 Copilot 執行外掛程式、從保存庫擷取 API 金鑰，並使用它來呼叫 API。藉由遵循此程式，API 密鑰會保持安全，且永遠不會向客戶端公開。

建立新專案

從建立適用於 Microsoft 365 Copilot 的新 API 外掛程式開始。開啟 Visual Studio Code。

在 Visual Studio Code：

在 活動列 (側邊欄) 中，啟用 Microsoft 365 Agents Toolkit 擴充功能。
在 [Microsoft 365 代理程式工具組 擴充功能] 面板中，選擇 [ 建立新的應用程式]。
從專案範本清單中，選擇 [Copilot 代理程式]。
從應用程式功能清單中，選擇 [ 宣告式代理程式]。
選擇 [ 新增外掛程式] 選項。
選擇 [ 開始使用新的 API] 選項。
從驗證類型清單中，選擇 [API 金鑰 (持有人令牌驗證) 。
選擇 [ TypeScript] 作為程式設計語言。
選擇要儲存項目的資料夾。
將您的專案命名 為 da-repairs-key。

Microsoft 365 代理程式工具組會建立新的專案，其中包含宣告式代理程式、API 外掛程式，以及使用密鑰保護的 API。

檢查 API 金鑰驗證組態

繼續之前，請檢查所產生專案中的 API 金鑰驗證組態。

檢查 API 定義

首先，請查看如何在 API 定義中定義 API 金鑰驗證。

在 Visual Studio Code：

開啟 appPackage/apiSpecificationFile/repair.yml 檔案。此檔案包含 API 的 OpenAPI 定義。
在 components.securitySchemes 區 段中，注意 apiKey 屬性：
```
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
```
屬性會定義使用 API 金鑰做為授權要求標頭中持有人令牌的安全性配置。

找出 paths./repairs.get.security 屬性。請注意，它會參考 apiKey 安全性配置。

[...]
paths:
  /repairs:
    get:
      operationId: listRepairs
      [...]
      security:
        - apiKey: []
[...]

檢查 API 實作

接下來，請參閱 API 如何在每個要求上驗證 API 金鑰。

在 Visual Studio Code：

開啟 src/functions/repairs.ts 檔案。

在 repairs 處理程式函式中，找出下列會拒絕所有未經授權要求的程式代碼行：

if (!isApiKeyValid(req)) {
  // Return 401 Unauthorized response.
  return {
    status: 401,
  };
}

isApiKeyValid 函式會在repairs.ts檔案中進一步實作：
```
function isApiKeyValid(req: HttpRequest): boolean {
  const apiKey = req.headers.get("Authorization")?.replace("Bearer ", "").trim();
  return apiKey === process.env.API_KEY;
}
```
函式會檢查授權標頭是否包含持有人令牌，並將其與 API_KEY 環境變數中定義的 API 金鑰進行比較。

此程式代碼會示範 API 金鑰安全性的簡單實作，但它說明 API 金鑰安全性在實務上的運作方式。

檢查保存庫工作設定

在此專案中，您會使用 Microsoft 365 代理程式工具組將 API 金鑰新增至保存庫。 Microsoft 365 代理程式工具組會使用項目組態中的特殊工作，在保存庫中註冊 API 密鑰。

在 Visual Studio Code：

開啟 ./teampsapp.local.yml 檔案。
在 [ 布建] 區段中，找出 apiKey/register 工作。
```
# Register API KEY
- uses: apiKey/register
  with:
    # Name of the API Key
    name: apiKey
    # Value of the API Key
    primaryClientSecret: ${{SECRET_API_KEY}}
    # Teams app ID
    appId: ${{TEAMS_APP_ID}}
    # Path to OpenAPI description document
    apiSpecPath: ./appPackage/apiSpecificationFile/repair.yml
  # Write the registration information of API Key into environment file for
  # the specified environment variable(s).
  writeToEnvironmentFile:
    registrationId: APIKEY_REGISTRATION_ID
```
工作會採用儲存在 env/.env.local.user 檔案中的 SECRET_API_KEY 項目變數值，並在保存庫中註冊它。然後，它會取得保存庫項目標識符，並將它寫入環境檔案 env/.env.local。這項工作的結果是名為 APIKEY_REGISTRATION_ID的環境變數。 Microsoft 365 Agents Toolkit 會將此變數的值寫入包含外掛程式定義的 appPackages/ai-plugin.json 檔案。在運行時間，會載入 API 外掛程式的宣告式代理程式會使用此識別元從保存庫擷取 API 金鑰，並安全地呼叫 API。

設定本機開發的 API 金鑰

您必須先為 API 定義 API 金鑰，才能測試專案。然後，將 API 金鑰儲存在儲存庫中，並在您的 API 外掛程式中記錄保存庫項目識別碼。針對本機開發，請將 API 金鑰儲存在您的專案中，並使用 Microsoft 365 代理程式工具組在保存庫中為您註冊。

在 Visual Studio Code：

開啟 [終端機 ] 窗格。
在命令列中：
1. 執行來還原專案的相依性 npm install。
2. 執行來產生新的 API 金鑰： npm run keygen。
3. 將產生的金鑰複製到剪貼簿。
開啟 env/.env.local.user 檔案。
將 SECRET_API_KEY 屬性更新為新產生的 API 金鑰。更新的屬性如下所示：
```
SECRET_API_KEY=your_key
```
儲存變更。

每次建置專案時，Microsoft 365 代理程式工具組都會自動更新保存庫中的 API 金鑰，並使用保存庫專案識別碼更新您的專案。

在 Microsoft 365 Copilot 中使用 API 外掛程式測試宣告式代理程式

最後一個步驟是使用 Microsoft 365 Copilot 中的 API 外掛程式來測試宣告式代理程式。

在 Visual Studio Code：

在活動列中，啟用 Microsoft 365 Agents Toolkit 擴充功能。
在 [Microsoft 365 代理程式工具組 擴充功能] 面板的 [ 帳戶 ] 區段中，確定您已登入已啟用 Copilot 的 Microsoft 365 租使用者。
在 [活動列] 中，切換至 [執行和偵錯] 檢視。
從組態清單中，選擇 [在 Copilot (Edge) 中進行偵錯]，然後按下 [播放] 按鈕以開始偵錯。

Visual Studio Code 會開啟具有 Microsoft 365 Copilot 的新網頁瀏覽器。如果出現提示，請使用您的 Microsoft 365 帳戶登入。

在網頁瀏覽器中：

從側邊面板中，選取 da-repairs-keylocal 代理程式。
在提示文字框中，輸入 What repairs are assigned to Karin? 並提交提示。
確認您想要使用 [ 永遠允許 ] 按鈕將資料傳送至 API 外掛程式。
等候代理程序回應。

當您完成測試時，請在 Visual Studio Code 中停止偵錯會話。

意見反應

此頁面對您有幫助嗎？