Créer un Plugin API TypeSpec

Créez un plugin API TypeSpec complet pour Microsoft 365 Copilot qui s'intègre avec des API REST externes.

Exigences

Générez des fichiers TypeSpec avec :

main.tsp - Définition de l'Agent

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent({
  name: "[Agent Name]",
  description: "[Description]"
})
@instructions("""
  [Instructions for using the API operations]
""")
namespace [AgentName] {
  // Reference operations from actions.tsp
  op operation1 is [APINamespace].operationName;
}

actions.tsp - Opérations API

import "@typespec/http";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Actions;

@service
@actions(#{
    nameForHuman: "[API Display Name]",
    descriptionForModel: "[Model description]",
    descriptionForHuman: "[User description]"
})
@server("[API_BASE_URL]", "[API Name]")
@useAuth([AuthType]) // Optional
namespace [APINamespace] {

  @route("[/path]")
  @get
  @action
  op operationName(
    @path param1: string,
    @query param2?: string
  ): ResponseModel;

  model ResponseModel {
    // Response structure
  }
}

Options d'Authentification

Choisissez selon les exigences de l'API :

1. Pas d'Authentification (API Publiques)

   // No @useAuth decorator needed

2. Clé API

   @useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)

3. OAuth2

   @useAuth(OAuth2Auth<[{
     type: OAuth2FlowType.authorizationCode;
     authorizationUrl: "https://oauth.example.com/authorize";
     tokenUrl: "https://oauth.example.com/token";
     refreshUrl: "https://oauth.example.com/token";
     scopes: ["read", "write"];
   }]>)

4. Référence d'Authentification Enregistrée

   @useAuth(Auth)
   
   @authReferenceId("registration-id-here")
   model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">

Capacités de Fonction

Dialogue de Confirmation

@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Confirm Action",
    body: """
    Are you sure you want to perform this action?
      * **Parameter**: {{ function.parameters.paramName }}
    """
  }
})

Réponse Adaptive Card

@card(#{
  dataPath: "$.items",
  title: "$.title",
  url: "$.link",
  file: "cards/card.json"
})

Raisonnement et Instructions de Réponse

@reasoning("""
  Consider user's context when calling this operation.
  Prioritize recent items over older ones.
""")
@responding("""
  Present results in a clear table format with columns: ID, Title, Status.
  Include a summary count at the end.
""")

Bonnes Pratiques

1. Noms d'Opérations : Utilisez des noms clairs et orientés action (listProjects, createTicket)
2. Modèles : Définissez des modèles TypeScript-like pour les requêtes et réponses
3. Méthodes HTTP : Utilisez les verbes appropriés (@get, @post, @patch, @delete)
4. Chemins : Utilisez des conventions de chemin RESTful avec @route
5. Paramètres : Utilisez @path, @query, @header, @body de manière appropriée
6. Descriptions : Fournissez des descriptions claires pour la compréhension du modèle
7. Confirmations : Ajoutez-les pour les opérations destructrices (suppression, mise à jour de données critiques)
8. Cards : Utilisez-les pour les réponses visuelles enrichies avec plusieurs éléments de données

Flux de Travail

Posez à l'utilisateur :

1. Quelle est l'URL de base de l'API et son objectif ?
2. Quelles opérations sont nécessaires (opérations CRUD) ?
3. Quelle méthode d'authentification l'API utilise-t-elle ?
4. Des confirmations sont-elles requises pour certaines opérations ?
5. Les réponses ont-elles besoin d'Adaptive Cards ?

Puis générez :

• main.tsp complet avec définition d'agent
• actions.tsp complet avec opérations API et modèles
• cards/card.json optionnel si des Adaptive Cards sont nécessaires