Ejercicio: Integración de un complemento de API con una API protegida con una clave

  • 9 minutos

Los complementos de API para Microsoft 365 Copilot le permiten integrarse con API protegidas con una clave. Para proteger la clave de API, regístrela en el almacén de Teams. En tiempo de ejecución, Microsoft 365 Copilot ejecuta el complemento, recupera la clave de API del almacén y la usa para llamar a la API. Al seguir este proceso, la clave de API permanece segura y nunca se expone al cliente.

Crear un proyecto

Empiece por crear un nuevo complemento de API para Microsoft 365 Copilot. Abrir Visual Studio Code.

En Visual Studio Code:

  1. En la barra de actividad (barra lateral), active la extensión Microsoft 365 Agents Toolkit.
  2. En el panel de extensión microsoft 365 Agents Toolkit , elija Crear una nueva aplicación.
  3. En la lista de plantillas de proyecto, elija Agente de Copilot.
  4. En la lista de características de la aplicación, elija Agente declarativo.
  5. Elija la opción Agregar complemento .
  6. Elija la opción Iniciar con una nueva API .
  7. En la lista de tipos de autenticación, elija Clave de API (autenticación de token de portador).
  8. Como lenguaje de programación, elija TypeScript.
  9. Elija una carpeta para almacenar el proyecto.
  10. Asigne al proyecto el nombre da-repairs-key.

Microsoft 365 Agents Toolkit crea un nuevo proyecto que incluye un agente declarativo, un complemento de API y una API protegida con una clave.

Examen de la configuración de autenticación de clave de API

Antes de continuar, examine la configuración de autenticación de clave de API en el proyecto generado.

Examen de la definición de API

En primer lugar, examine cómo se define la autenticación de clave de API en la definición de API.

En Visual Studio Code:

  1. Abra el archivo appPackage/apiSpecificationFile/repair.yml . Este archivo contiene la definición de OpenAPI para la API.

  2. En la sección components.securitySchemes , observe la propiedad apiKey :

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

    La propiedad define un esquema de seguridad que usa la clave de API como token de portador en el encabezado de solicitud de autorización.

  3. Busque la propiedad paths./repairs.get.security . Observe que hace referencia al esquema de seguridad apiKey .

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

Examen de la implementación de API

A continuación, vea cómo la API valida la clave de API en cada solicitud.

En Visual Studio Code:

  1. Abra el archivo src/functions/repairs.ts .

  2. En la función de controlador de reparaciones , busque la siguiente línea, que rechaza todas las solicitudes no autorizadas:

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

  3. La función isApiKeyValid se implementa aún más en el archivo repairs.ts:

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

    La función comprueba si el encabezado de autorización contiene un token de portador y lo compara con la clave de API definida en la variable de entorno API_KEY .

Este código muestra una implementación simplista de la seguridad de claves de API, pero muestra cómo funciona la seguridad de claves de API en la práctica.

Examen de la configuración de la tarea del almacén

En este proyecto, usará Microsoft 365 Agents Toolkit para agregar la clave de API al almacén. Microsoft 365 Agents Toolkit registra la clave de API en el almacén mediante una tarea especial en la configuración del proyecto.

En Visual Studio Code:

  1. Abra el archivo ./teampsapp.local.yml .

  2. En la sección de aprovisionamiento , busque la tarea 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

    La tarea toma el valor de la variable de proyecto SECRET_API_KEY , almacenada en el archivo env/.env.local.user y la registra en el almacén. A continuación, toma el identificador de entrada del almacén y lo escribe en el archivo de entorno env/.env.local. El resultado de esta tarea es una variable de entorno denominada APIKEY_REGISTRATION_ID. Microsoft 365 Agents Toolkit escribe el valor de esta variable en el archivo appPackages/ai-plugin.json que contiene la definición del complemento. En tiempo de ejecución, el agente declarativo que carga el complemento de API, usa este identificador para recuperar la clave de API del almacén y llamar a la API de forma segura.

Configuración de la clave de API para el desarrollo local

Para poder probar el proyecto, debe definir una clave de API para la API. A continuación, almacene la clave de API en el almacén y registre el identificador de entrada del almacén en el complemento de API. Para el desarrollo local, almacene la clave de API en el proyecto y use Microsoft 365 Agents Toolkit para registrarla en el almacén automáticamente.

En Visual Studio Code:

  1. Abra el panel Terminal .

  2. En una línea de comandos:

    1. Restaure las dependencias del proyecto mediante la ejecución de npm install.
    2. Genere una nueva clave de API mediante la ejecución de: npm run keygen.
    3. Copie la clave generada en el Portapapeles.

  3. Abra el archivo env/.env.local.user .

  4. Actualice la propiedad SECRET_API_KEY a la clave de API recién generada. La propiedad actualizada tiene el siguiente aspecto:

    SECRET_API_KEY=your_key

  5. Guarde los cambios.

Cada vez que compila el proyecto, Microsoft 365 Agents Toolkit actualiza automáticamente la clave de API en el almacén y actualiza el proyecto con el identificador de entrada del almacén.

Pruebe el agente declarativo con el complemento de API en Microsoft 365 Copilot

El último paso consiste en probar el agente declarativo con el complemento de API en Microsoft 365 Copilot.

En Visual Studio Code:

  1. En la barra de actividad, active la extensión Microsoft 365 Agents Toolkit .

  2. En el panel de extensión microsoft 365 Agents Toolkit , en la sección Cuentas , asegúrese de que ha iniciado sesión en su inquilino de Microsoft 365 con Copilot habilitado.

    Captura de pantalla de Microsoft 365 Agents Toolkit que muestra el estado de la conexión a Microsoft 365.

  3. En la barra de actividad, cambie a la vista Ejecutar y depurar.

  4. En la lista de configuraciones, elija Depurar en Copilot (Edge) y presione el botón reproducir para iniciar la depuración.

    Captura de pantalla de la opción de depuración en Visual Studio Code.

    Visual Studio Code abre un nuevo explorador web con Microsoft 365 Copilot. Si se le solicita, inicie sesión con la cuenta de Microsoft 365.

En el explorador web:

  1. En el panel lateral, seleccione el agente da-repairs-keylocal .

    Captura de pantalla del agente personalizado que se muestra en Microsoft 365 Copilot.

  2. En el cuadro de texto del símbolo del sistema, escriba What repairs are assigned to Karin? y envíe el mensaje.

  3. Confirme que desea enviar datos al complemento de API mediante el botón Permitir siempre .

    Captura de pantalla del símbolo del sistema para permitir el envío de datos a la API.

  4. Espere a que el agente responda.

    Captura de pantalla de la respuesta del agente personalizado al mensaje del usuario.

Detenga la sesión de depuración en Visual Studio Code cuando haya terminado de realizar las pruebas.