Compartilhar via

Criar plug-ins de API a partir de uma API existente para Microsoft 365 Copilot

  • Artigo

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

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 o exemplo pelo menos uma vez para gerar o ficheiro de BudgetTracker.json para a API.

Ativar o desenvolvimento de plug-ins no Teams Toolkit

  1. 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.

  2. 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.

  3. 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.

  4. 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 uma copilotExtensions propriedade que referencia o manifesto do plug-in da API.

  1. 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.

  2. Selecione o ícone Do Teams Toolkit na Barra de Atividade do lado esquerdo.

  3. Selecione Criar uma Nova Aplicação no painel de tarefas do Teams Toolkit.

    Uma captura de ecrã da interface do Teams Toolkit

  4. Selecione Agente e, em seguida, selecione Agente Declarativo.

  5. 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.

  1. Selecione Procurar e navegue para a localização da especificação OpenAPI no exemplo Budget Tracker, localizado em ./openapi/BudgetTracker.json.

  2. Selecione todas as operações a ativar para o plug-in.

    IU do Toolkit do Teams para selecionar operações

  3. Escolha uma localização para o projeto de plug-in da API.

  4. 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

  1. Abra o projeto de plug-in no Visual Studio Code.

  2. Selecione o ícone Do Teams Toolkit na Barra de Atividade do lado esquerdo.

  3. No painel Contas , selecione Iniciar sessão no Microsoft 365. (Se já tiver sessão iniciada, avance para o passo seguinte).

  4. 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.

  5. No painel Ciclo de Vida , selecione Aprovisionar.

  6. Quando lhe for pedido para Introduzir o ID de cliente para o registo OAuth..., introduza o ID de cliente do Plug-in.

  7. Quando lhe for pedido para Introduzir o segredo do cliente para o registo OAuth..., introduza o segredo do cliente do Plug-in.

  8. Leia a mensagem na caixa de diálogo e selecione Confirmar para continuar.

  9. Aguarde que o toolkit comunique o aprovisionamento concluído.

    A mensagem do Teams Toolkit a confirmar o aprovisionamento com êxito

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

  1. Abra o Teams no seu browser e inicie sessão com a conta do Microsoft 365 que utilizou para carregar o plug-in.

  2. Selecione Conversar na Barra de Atividade do lado esquerdo.

  3. Selecione Copilot no painel Chat .

  4. Selecione Budget Tracker (Controlador de Orçamento ) na lista Agents (Agentes), no lado direito. Se a lista não estiver disponível, selecione o ícone Conversas copiais e muito mais no canto superior direito.

    Uma captura de ecrã da lista agentes no Microsoft Teams

  5. 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.

  6. Quando lhe for pedido para iniciar sessão, selecione Iniciar sessão no Budget Tracker.