Упражнение. Интеграция подключаемого модуля API с API, защищенным с помощью ключа

  • 9 мин

Подключаемые модули API для Microsoft 365 Copilot позволяют интегрироваться с API, защищенными с помощью ключа. Вы защищаете ключ API, регистрируя его в хранилище Teams. Во время выполнения Microsoft 365 Copilot выполняет подключаемый модуль, извлекает ключ API из хранилища и использует его для вызова API. После выполнения этого процесса ключ API остается безопасным и никогда не предоставляется клиенту.

Создание проекта

Начните с создания подключаемого модуля API для Microsoft 365 Copilot. Откройте Visual Studio Code.

В Visual Studio Code:

  1. На панели действий (боковая панель) активируйте расширение Microsoft 365 Agents Toolkit.
  2. На панели расширения Microsoft 365 Agents Toolkit выберите Создать новое приложение.
  3. В списке шаблонов проектов выберите Агент Copilot.
  4. В списке функций приложения выберите Декларативный агент.
  5. Выберите параметр Добавить подключаемый модуль .
  6. Выберите параметр Начать с нового API .
  7. В списке типов проверки подлинности выберите Ключ API (проверка подлинности маркера носителя).
  8. В качестве языка программирования выберите TypeScript.
  9. Выберите папку для хранения проекта.
  10. Присвойте проекту имя da-repairs-key.

Microsoft 365 Agents Toolkit создает новый проект, включающий декларативный агент, подключаемый модуль API и API, защищенный ключом.

Изучение конфигурации проверки подлинности с помощью ключа API

Прежде чем продолжить, изучите конфигурацию проверки подлинности ключа API в созданном проекте.

Изучение определения API

Во-первых, ознакомьтесь с определением проверки подлинности ключа API в определении API.

В Visual Studio Code:

  1. Откройте файл appPackage/apiSpecificationFile/repair.yml . Этот файл содержит определение OpenAPI для API.

  2. В разделе components.securitySchemes обратите внимание на свойство apiKey :

    components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

    Свойство определяет схему безопасности, которая использует ключ API в качестве маркера носителя в заголовке запроса авторизации.

  3. Найдите свойство paths./repairs.get.security . Обратите внимание, что он ссылается на схему безопасности apiKey .

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

Изучение реализации API

Затем ознакомьтесь с тем, как API проверяет ключ API при каждом запросе.

В Visual Studio Code:

  1. Откройте файл src/functions/repairs.ts .

  2. В функции обработчика исправлений найдите следующую строку, которая отклоняет все несанкционированные запросы:

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

  3. Функция isApiKeyValid реализована далее в файле repairs.ts:

    function isApiKeyValid(req: HttpRequest): boolean {
  const apiKey = req.headers.get("Authorization")?.replace("Bearer ", "").trim();
  return apiKey === process.env.API_KEY;
}

    Функция проверяет, содержит ли заголовок авторизации токен носителя, и сравнивает его с ключом API, определенным в переменной среды API_KEY .

В этом коде показана упрощенная реализация безопасности ключей API, но в нем показано, как работает безопасность ключей API на практике.

Изучение конфигурации задачи хранилища

В этом проекте вы используете Microsoft 365 Agents Toolkit для добавления ключа API в хранилище. Microsoft 365 Agents Toolkit регистрирует ключ API в хранилище с помощью специальной задачи в конфигурации проекта.

В Visual Studio Code:

  1. Откройте файл ./teampsapp.local.yml .

  2. В разделе подготовка найдите задачу 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

    Задача принимает значение переменной проекта SECRET_API_KEY , хранящейся в файле env/.env.local.user, и регистрирует его в хранилище. Затем он принимает идентификатор записи хранилища и записывает его в файл среды 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 Agents Toolkit, чтобы зарегистрировать его в хранилище.

В Visual Studio Code:

  1. Откройте панель Терминал .

  2. В командной строке:

    1. Восстановите зависимости проекта, запустив npm install.
    2. Создайте новый ключ API, выполнив команду : npm run keygen.
    3. Скопируйте созданный ключ в буфер обмена.

  3. Откройте файл env/.env.local.user .

  4. Обновите свойство SECRET_API_KEY до только что созданного ключа API. Обновленное свойство выглядит следующим образом:

    SECRET_API_KEY=your_key

  5. Сохраните изменения.

Каждый раз, когда вы создаете проект, Microsoft 365 Agents Toolkit автоматически обновляет ключ API в хранилище и обновляет проект с помощью идентификатора записи хранилища.

Протестируйте декларативный агент с помощью подключаемого модуля API в Microsoft 365 Copilot

Последним шагом является тестирование декларативного агента с помощью подключаемого модуля API в Microsoft 365 Copilot.

В Visual Studio Code:

  1. На панели действий активируйте расширение Microsoft 365 Agents Toolkit .

  2. На панели расширения Microsoft 365 Agents Toolkit в разделе Учетные записи убедитесь, что вы вошли в клиент Microsoft 365 с включенным Copilot.

    Снимок экрана: набор средств агентов Microsoft 365 с состоянием подключения к Microsoft 365.

  3. На панели действий переключитесь в представление Запуск и отладка.

  4. В списке конфигураций выберите Отладка в Copilot (Edge) и нажмите кнопку воспроизведения, чтобы начать отладку.

    Снимок экрана: параметр отладки в Visual Studio Code.

    Visual Studio Code откроется новый веб-браузер с Microsoft 365 Copilot. При появлении запроса войдите в свою учетную запись Microsoft 365.

В веб-браузере:

  1. На боковой панели выберите агент da-repairs-keylocal .

    Снимок экрана: пользовательский агент, отображаемый в Microsoft 365 Copilot.

  2. В текстовом поле запроса введите What repairs are assigned to Karin? и отправьте запрос.

  3. Убедитесь, что вы хотите отправить данные в подключаемый модуль API с помощью кнопки Всегда разрешать .

    Снимок экрана: запрос на отправку данных в API.

  4. Дождитесь ответа агента.

    Снимок экрана: ответ пользовательского агента на запрос пользователя.

Остановите сеанс отладки в Visual Studio Code после завершения тестирования.