Exercice - Intégrer un plug-in d’API à une API sécurisée avec une clé

9 minutes

Les plug-ins d’API pour Microsoft 365 Copilot vous permettent d’intégrer des API sécurisées avec une clé. Vous sécurisez la clé API en l’inscrivant dans le coffre Teams. Au moment de l’exécution, Microsoft 365 Copilot exécute votre plug-in, récupère la clé API du coffre et l’utilise pour appeler l’API. En suivant ce processus, la clé API reste sécurisée et n’est jamais exposée au client.

Création d’un projet

Commencez par créer un plug-in d’API pour Microsoft 365 Copilot. Ouvrez Visual Studio Code.

Dans Visual Studio Code :

Dans la barre d’activité (barre latérale), activez l’extension Microsoft 365 Agents Toolkit.
Dans le panneau d’extension Microsoft 365 Agents Toolkit , choisissez Créer une application.
Dans la liste des modèles de projet, choisissez Agent Copilot.
Dans la liste des fonctionnalités de l’application, choisissez Agent déclaratif.
Choisissez l’option Ajouter un plug-in .
Choisissez l’option Démarrer avec une nouvelle API .
Dans la liste des types d’authentification, choisissez Clé API (Authentification du jeton du porteur).
En tant que langage de programmation, choisissez TypeScript.
Choisissez un dossier pour stocker votre projet.
Nommez votre projet da-repairs-key.

Microsoft 365 Agents Toolkit crée un projet qui inclut un agent déclaratif, un plug-in d’API et une API sécurisée avec une clé.

Examiner la configuration de l’authentification par clé API

Avant de continuer, examinez la configuration de l’authentification par clé API dans le projet généré.

Examiner la définition de l’API

Tout d’abord, examinez la façon dont l’authentification par clé API est définie dans la définition d’API.

Dans Visual Studio Code :

Ouvrez le fichier appPackage/apiSpecificationFile/repair.yml . Ce fichier contient la définition OpenAPI pour l’API.
Dans la section components.securitySchemes , notez la propriété apiKey :
```
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
```
La propriété définit un schéma de sécurité qui utilise la clé API comme jeton du porteur dans l’en-tête de demande d’autorisation.

Recherchez la propriété paths./repairs.get.security . Notez qu’il fait référence au schéma de sécurité apiKey .

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

Examiner l’implémentation de l’API

Ensuite, découvrez comment l’API valide la clé API sur chaque requête.

Dans Visual Studio Code :

Ouvrez le fichier src/functions/repairs.ts .
Dans la fonction de gestionnaire de réparations , recherchez la ligne suivante qui rejette toutes les demandes non autorisées :
```
if (!isApiKeyValid(req)) {
  // Return 401 Unauthorized response.
  return {
    status: 401,
  };
} 
```
La fonction isApiKeyValid est implémentée plus loin dans le fichier repairs.ts :
```
function isApiKeyValid(req: HttpRequest): boolean {
  const apiKey = req.headers.get("Authorization")?.replace("Bearer ", "").trim();
  return apiKey === process.env.API_KEY;
}
```
La fonction vérifie si l’en-tête d’autorisation contient un jeton du porteur et le compare à la clé API définie dans la variable d’environnement API_KEY .

Ce code montre une implémentation simpliste de la sécurité des clés API, mais il illustre comment la sécurité des clés API fonctionne dans la pratique.

Examiner la configuration de la tâche du coffre

Dans ce projet, vous utilisez microsoft 365 Agents Toolkit pour ajouter la clé API au coffre. Microsoft 365 Agents Toolkit inscrit la clé API dans le coffre à l’aide d’une tâche spéciale dans la configuration du projet.

Dans Visual Studio Code :

Ouvrez le fichier ./teampsapp.local.yml .
Dans la section provision, recherchez la tâche 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 tâche prend la valeur de la variable de projet SECRET_API_KEY , stockée dans le fichier r env/.env.local.useet l’inscrit dans le coffre. Ensuite, il prend l’ID d’entrée du coffre et l’écrit dans le fichier d’environnement env/.env.local. Le résultat de cette tâche est une variable d’environnement nommée APIKEY_REGISTRATION_ID. Microsoft 365 Agents Toolkit écrit la valeur de cette variable dans le fichier appPackages/ai-plugin.json qui contient la définition du plug-in. Au moment de l’exécution, l’agent déclaratif qui charge le plug-in d’API utilise cet ID pour récupérer la clé API du coffre et appeler l’API en toute sécurité.

Configurer la clé API pour le développement local

Avant de pouvoir tester le projet, vous devez définir une clé API pour votre API. Ensuite, stockez la clé API dans le coffre et enregistrez l’ID d’entrée du coffre dans votre plug-in d’API. Pour le développement local, stockez la clé API dans votre projet et utilisez microsoft 365 Agents Toolkit pour l’inscrire dans le coffre à votre place.

Dans Visual Studio Code :

Ouvrez le volet Terminal .
Dans une ligne de commande :
1. Restaurez les dépendances du projet en exécutant npm install.
2. Générez une nouvelle clé API en exécutant : npm run keygen.
3. Copiez la clé générée dans le Presse-papiers.
Ouvrez le fichier env/.env.local.user .
Mettez à jour la propriété SECRET_API_KEY avec la clé API nouvellement générée. La propriété mise à jour se présente comme suit :
```
SECRET_API_KEY=your_key
```
Enregistrez vos modifications.

Chaque fois que vous générez le projet, Microsoft 365 Agents Toolkit met automatiquement à jour la clé API dans le coffre et met à jour votre projet avec l’ID d’entrée du coffre.

Testez l’agent déclaratif avec le plug-in d’API dans Microsoft 365 Copilot

La dernière étape consiste à tester l’agent déclaratif avec le plug-in d’API dans Microsoft 365 Copilot.

Dans Visual Studio Code :

Dans la barre d’activité, activez l’extension Microsoft 365 Agents Toolkit .
Dans le panneau de l’extension Microsoft 365 Agents Toolkit , dans la section Comptes , vérifiez que vous êtes connecté à votre locataire Microsoft 365 avec Copilot activé.
Dans la barre d’activité, basculez vers la vue Exécuter et déboguer.
Dans la liste des configurations, choisissez Déboguer dans Copilot (Edge) et appuyez sur le bouton de lecture pour démarrer le débogage.

Visual Studio Code ouvre un nouveau navigateur web avec Microsoft 365 Copilot. Si vous y êtes invité, connectez-vous à l’aide de votre compte Microsoft 365.

Dans le navigateur web :

Dans le panneau latéral, sélectionnez l’agent da-repairs-keylocal .
Dans la zone de texte de l’invite, tapez What repairs are assigned to Karin? et envoyez l’invite.
Vérifiez que vous souhaitez envoyer des données au plug-in d’API à l’aide du bouton Toujours autoriser .
Attendez que l’agent réponde.

Arrêtez la session de débogage dans Visual Studio Code lorsque vous avez terminé le test.

Commentaires

Cette page a-t-elle été utile ?