Criar plug-ins de API a partir de uma API existente para Microsoft 365 Copilot
Importante
Os plug-ins de API só são suportados como ações dentro de agentes declarativos. Não estão ativados no Microsoft 365 Copilot.
Os plug-ins de API ligam a API REST existente ao Microsoft 365 Copilot. Pode utilizar o Toolkit do Teams para gerar um plug-in a partir de uma API REST existente com uma especificação OpenAPI.
Pré-requisitos
- Requisitos especificados em Requisitos para desenvolvimento de plug-ins
- Uma API REST existente com uma especificação OpenAPI (estas instruções utilizam a API de exemplo do Budget Tracker)
- Visual Studio Code com o Teams Toolkit versão 5.9 ou posterior
- Kit de ferramentas do Teams
- Opcional: extensão de Visual Studio Code do Microsoft Kiota
Dica
Para obter os melhores resultados, certifique-se de que a sua especificação OpenAPI segue as diretrizes detalhadas em Como tornar um documento OpenAPI eficaz na expansão do Copilot.
Para acompanhar este guia, transfira a API de exemplo Budget Tracker e configure-a para ser executada no seu computador de desenvolvimento local. Crie e execute o exemplo pelo menos uma vez para gerar o ficheiro de openapi.yml para a API.
Ativar o desenvolvimento de plug-ins no Teams Toolkit
Abra o Visual Studio Code. Se o Teams Toolkit ainda não estiver instalado, consulte Instalar o Teams Toolkit para obter instruções de instalação.
Selecione Ficheiro ->Preferências ->Definições. Na janela Definições , procure para
copilot
localizar a opção Fx-extension: Develop Copilot Plugin ( Desenvolver Plug-in copilot ). Se ainda não estiver ativado, ative a definição.Na janela Definições , procure para
kiota
localizar a opção Fx-extension: Ativar o Microsoft Kiota . Se quiser ativar o Kiota, ative esta opção. Caso contrário, desative-o. Para obter detalhes, veja Benefícios de ativar o Microsoft Kiota.Se tiver efetuado alterações às definições, reinicie Visual Studio Code antes de continuar.
Benefícios da ativação do Microsoft Kiota
Ativar o Microsoft Kiota no Teams Toolkit tem as seguintes vantagens.
- A interface de utilizador para selecionar operações a partir do documento OpenAPI é substituída por um explorador de API mais adequado para documentos OpenAPI grandes.
- O programador consegue procurar descrições públicas de OpenAPI com o comando de pesquisa de Kiota.
Criar o plug-in
Os plug-ins de API são um ficheiro ZIP que contém os seguintes ficheiros.
- A especificação OpenAPI para a API REST.
- Um manifesto de plug-in da API que referencia a especificação openAPI incluída e descreve as operações disponíveis, o método de autenticação e os formatos de resposta.
- Um manifesto de aplicação do Teams (por exemplo,
manifest.json
) com umacopilotExtensions
propriedade que referencia o manifesto do plug-in da API.
Abra o Visual Studio Code. Se o Teams Toolkit ainda não estiver instalado, consulte Instalar o Teams Toolkit para obter instruções de instalação.
Selecione o ícone Do Teams Toolkit na Barra de Atividade do lado esquerdo.
Selecione Criar uma Nova Aplicação no painel de tarefas do Teams Toolkit.
Selecione Copilot Agent e, em seguida, selecione Agente Declarativo.
Selecione Adicionar plug-in e, em seguida, selecione Começar com um Documento de Descrição de OpenAPI.
Os passos seguintes diferem consoante tenha ativado o Microsoft Kiota ou não.
Selecione Procurar e navegue para a localização da especificação OpenAPI no exemplo Budget Tracker, localizado em ./openapi/openapi.yml.
Selecione todas as operações a ativar para o plug-in.
Escolha uma localização para o projeto de plug-in da API.
Introduza
Budget Tracker
como um nome para o plug-in.
Depois de concluir estes passos, o Teams Toolkit gera os ficheiros necessários para o plug-in e abre uma nova janela de Visual Studio Code com o projeto de plug-in carregado.
Observação
Se o servidor de identidades precisar da Chave de Prova para o Code Exchange (PKCE), anule o comentário da seguinte linha no teamsapp.yml no projeto de plug-in da API.
# isPKCEEnabled: true
Empacotar e carregar o plug-in em sideload
Abra o projeto de plug-in no Visual Studio Code.
Selecione o ícone Do Teams Toolkit na Barra de Atividade do lado esquerdo.
No painel Contas , selecione Iniciar sessão no Microsoft 365. (Se já tiver sessão iniciada, avance para o passo seguinte).
Confirme que o Carregamento de Aplicações Personalizadas Ativado e o Acesso Copilot Ativado são apresentados na sua conta do Microsoft 365. Caso contrário, marcar junto do administrador da sua organização. Veja Requisitos para desenvolvimento de plug-ins para obter detalhes.
No painel Ciclo de Vida , selecione Aprovisionar.
Quando lhe for pedido para Introduzir o ID de cliente para o registo OAuth..., introduza o ID de cliente do Plug-in.
Quando lhe for pedido para Introduzir o segredo do cliente para o registo OAuth..., introduza o segredo do cliente do Plug-in.
Leia a mensagem na caixa de diálogo e selecione Confirmar para continuar.
Aguarde que o toolkit comunique o aprovisionamento concluído.
O plug-in está agora disponível para teste com a sua conta de utilizador no Microsoft 365 Copilot no Microsoft Teams.
Utilizar o plug-in
Abra o Teams no seu browser e inicie sessão com a conta do Microsoft 365 que utilizou para carregar o plug-in.
Selecione Conversar na Barra de Atividade do lado esquerdo.
Selecione Copilot no painel Chat .
Selecione Budget Tracker (Controlador de Orçamento ) na lista Copilot agents (Agentes copilot) no lado direito. Se a lista não estiver disponível, selecione o ícone Conversas copiais e muito mais no canto superior direito.
Faça uma pergunta sobre orçamentos. Por exemplo, experimente
How much is left in the Fourth Coffee lobby renovation budget?
. Quando lhe for pedido, selecione Permitir sempre ou Permitir uma vez para continuar.Quando lhe for pedido para iniciar sessão, selecione Iniciar sessão no Budget Tracker.