练习 - 将 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 代理工具包扩展。
在 “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 文件。

在修复处理程序函数中，找到以下拒绝所有未授权请求的行：

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 项目变量的值，并将其注册到保管库中。然后，它获取保管库条目 ID 并将其写入环境文件 env/.env.local。此任务的结果是名为 APIKEY_REGISTRATION_ID 的环境变量。 Microsoft 365 Agents Toolkit 将此变量的值写入包含插件定义的 appPackages/ai-plugin.json 文件。在运行时，加载 API 插件的声明性代理使用此 ID 从保管库检索 API 密钥，并安全地调用 API。

配置用于本地开发的 API 密钥

在测试项目之前，需要为 API 定义 API 密钥。然后，将 API 密钥存储在保管库中，并在 API 插件中记录保管库条目 ID。对于本地开发，请将 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 Agents Toolkit 都会自动更新保管库中的 API 密钥，并使用保管库条目 ID 更新项目。

在智能 Microsoft 365 Copilot 副驾驶® 中使用 API 插件测试声明性代理

最后一步是使用智能 Microsoft 365 Copilot 副驾驶® 中的 API 插件测试声明性代理。

在 Visual Studio Code：

在活动栏中，激活 Microsoft 365 代理工具包 扩展。
在 Microsoft 365 代理工具包 扩展面板中的 “帐户 ”部分中，确保已登录到启用了 Copilot 的 Microsoft 365 租户。
在活动栏中，切换到“运行和调试”视图。
从配置列表中，选择 “在 Copilot (Edge) 中调试 ”，然后按播放按钮开始调试。

Visual Studio Code使用智能 Microsoft 365 Copilot 副驾驶®打开新的 Web 浏览器。如果出现提示，请使用 Microsoft 365 帐户登录。