As extensões de mensagens baseadas em API suportam apenas comandos de pesquisa.
As extensões de mensagens baseadas em API não são suportadas no Microsoft 365 Copilot. Se quiser criar extensões de mensagens baseadas em API compatíveis com Microsoft 365 Copilot, veja Agentes de API para Microsoft 365 Copilot.
As extensões de mensagens criadas com a API (baseada em API) utilizam um serviço Web para gerir pedidos e respostas de utilizadores e não necessitam de um registo de bot. As extensões de mensagens baseadas em API são uma capacidade de aplicação do Microsoft Teams que integra APIs externas diretamente no Teams, melhorando a usabilidade da sua aplicação e oferecendo uma experiência de utilizador totalmente integrada. As extensões de mensagens baseadas em API suportam comandos de pesquisa e podem ser utilizadas para obter e apresentar dados de serviços externos no Teams, simplificando os fluxos de trabalho ao reduzir a necessidade de alternar entre aplicações. As extensões de mensagens baseadas em API ajudam as suas aplicações a interagir diretamente com dados, aplicações e serviços de terceiros, melhorando as suas capacidades. Com a extensão de mensagens baseada em API, pode:
Obtenha informações em tempo real, como a cobertura de notícias mais recente num lançamento de produto.
Recupere informações baseadas em conhecimento, por exemplo, os arquivos de design da equipe no Figma.
Veja o vídeo para saber mais sobre a criação de uma extensão de mensagem baseada em API com o Teams Toolkit:
Extensões de mensagens tradicionais baseadas em bots
Extensões de mensagens baseadas em API
Os programadores precisam de criar, implementar e manter um serviço para processar comandos de invocação do cliente do Teams.
Se as APIs do serviço final puderem ser descritas com a Especificação openAPI, os programadores podem eliminar a necessidade do serviço de processamento de camada média.
Este serviço processa a consulta recebida e faz uma chamada para o serviço final do programador.
O Teams pode utilizar diretamente a Especificação openAPI para criar pedidos e comunicar com o serviço final do programador.
As imagens seguintes mostram o fluxo de consultas do utilizador através de extensões de mensagens tradicionais e extensões de mensagens da API:
Fluxo de consulta do utilizador com extensões de mensagens tradicionais. O programador tem de manter um serviço de processador de bots personalizado, que processa os pedidos de um bot do Teams. O serviço de processador envia um pedido ao serviço do programador quando uma consulta é invocada.
Fluxo de consulta de utilizador com Extensões de Mensagens de API. Não é necessário um serviço de processador mantido pelo programador, desde que a interação esteja claramente descrita na Especificação OpenAPI no Pacote de Aplicações.
Eis uma sequência de eventos de alto nível que ocorre durante uma invocação de comandos de consulta:
Quando um utilizador invoca um comando de consulta, os parâmetros do comando de consulta são recebidos pela Serviço de Bot do Teams.
O comando de consulta é definido dentro do ficheiro de manifesto da aplicação. A definição de comando contém uma referência ao operationId ficheiro OpenAPI Specification, juntamente com os detalhes dos parâmetros que o cliente do Teams compõe para esse comando. Para referência, o operationId ficheiro OpenAPI Specification no interior é exclusivo de uma determinada operação HTTP.
O Teams Serviço de Bot, em seguida, utiliza os parâmetros fornecidos pelo utilizador juntamente com a cópia da Especificação openAPI para o associado operationId para criar um pedido HTTP para o ponto final do programador.
Se a autenticação for necessária e estiver configurada no manifesto. É resolvido para o token ou chave adequado. Este token ou chave é utilizado como parte do pedido de saída.
[Opcionalmente]
O serviço de bot do Teams efetua o pedido HTTP ao serviço do programador.
O serviço do programador deve responder de acordo com o esquema descrito na Especificação openAPI. Isto está no formato JSON.
O cliente do Teams tem de mostrar os resultados ao utilizador. Para converter os resultados JSON do passo anterior para a IU, o serviço de bot do Teams utiliza o modelo de Composição de resposta para criar um Cartão Ajustável para cada resultado.
Os Cartões Ajustáveis são enviados para o cliente, o que os compõe na IU.
Pré-requisitos
O pacote de definição de aplicação inclui vários artefactos apelativos que suportam a funcionalidade desta funcionalidade. Antes de começar, certifique-se de que tem uma compreensão básica dos seguintes ficheiros:
O documenat de descrição de OpenAPI é um padrão da indústria adotado para descrever as APIs. Permite-lhe abstrair as SUAS APIs da respetiva implementação, fornecendo definições agnósticas de linguagem que são legíveis por humanos e legíveis por computador. A descrição openAPI descreve as interações que a sua extensão suporta, permitindo ao Teams criar pedidos e comunicar diretamente com o seu serviço sem a necessidade de um serviço de processamento de camada média.
Um documento de descrição openAPI contém detalhes para comunicar com o serviço do programador. Certifique-se de que cumpre as seguintes diretrizes para o documento de Descrição de OpenAPI (OAD):
As versões OpenAPI 2.0 e 3.0.x são suportadas.
JSON e YAML são os formatos suportados.
O corpo do pedido, se estiver presente, tem de ser application/Json.
Defina um URL de servidor de protocolo HTTPS para a servers.url propriedade .
Apenas os métodos POST e GET HTTP são suportados.
O documento Descrição de OpenAPI tem de ter um operationId.
Só é permitido um parâmetro necessário sem um valor predefinido.
Um parâmetro necessário com um valor predefinido é considerado opcional.
Os utilizadores não podem introduzir um parâmetro para um cabeçalho ou cookie.
A operação não pode ter um cabeçalho ou parâmetros de cookie necessários sem valores predefinidos.
Certifique-se de que não existem referências remotas no documento Descrição de OpenAPI.
A construção de matrizes para o pedido não é suportada; no entanto, os objetos aninhados dentro de um corpo de pedido JSON são suportados.
O Teams não suporta as oneOfconstruções , anyOf, allOfe not (swagger.io).
O código seguinte é um exemplo de um documento de Descrição de OpenAPI:
Para obter mais informações sobre como escrever definições openAPI no YAML, veja Estrutura openAPI.
Manifesto do aplicativo
O manifesto de aplicação é um esquema para a sua aplicação Teams, que define como e onde a extensão de mensagem é invocada no cliente do Teams. Inclui os comandos suportados pela extensão e as localizações a partir das quais podem ser acedidos, como a área de composição de mensagens, a barra de comandos e a mensagem. O manifesto liga à Especificação OpenAPI e ao Modelo de Composição de Resposta para garantir a funcionalidade adequada.
O manifesto da aplicação contém a definição do comando de consulta. Certifique-se de que cumpre as seguintes diretrizes para o manifesto da aplicação:
Defina a versão do manifesto da aplicação como 1.17.
Defina composeExtensions.composeExtensionType como apiBased.
Defina composeExtensions.apiSpecificationFile como o caminho relativo para o documento Descrição de OpenAPI na pasta. Isto liga o manifesto da aplicação à especificação da API.
Defina apiResponseRenderingTemplateFile como o caminho relativo para o modelo de composição de resposta. Isto especifica a localização do modelo utilizado para compor respostas da API.
Cada comando tem de ter uma ligação para o modelo de composição de resposta. Esta ação liga cada comando ao respetivo formato de resposta correspondente.
A Commands.id propriedade no manifesto da aplicação tem de corresponder ao operationId no documento Descrição de OpenAPI.
Se um parâmetro necessário não tiver um valor predefinido, o comando parameters.name no manifesto da aplicação tem de corresponder ao parameters.name no documento de descrição OpenAPI.
Se não existir nenhum parâmetro necessário, o comando parameters.name no manifesto da aplicação tem de corresponder ao opcional parameters.name no documento Descrição de OpenAPI.
Certifique-se de que o nome dos parâmetros para cada comando no manifesto da aplicação corresponde exatamente ao nome correspondente do parâmetro definido para a operação no documento Descrição de OpenAPI.
Um modelo de composição de resposta tem de ser definido por comando, que é utilizado para converter respostas de uma API.
As descrições do comando e dos parâmetros não podem exceder os 128 carateres.
Segue-se um exemplo de manifesto de aplicação com definições para extensões de mensagens baseadas em API:
Objeto que captura os detalhes necessários para realizar a autenticação do serviço. Aplicável apenas quando o tipo de autenticação for apiSecretServiceAuth.
ID de registo devolvido quando o programador submete a chave de API através do Portal do Programador.
composeExtensions.apiSpecificationFile
Referencia um ficheiro de Descrição de OpenAPI no pacote de aplicação. Incluir quando o tipo for apiBased.
composeExtensions.commands.id
ID exclusivo que atribui ao comando de pesquisa. A solicitação do usuário inclui essa ID. O ID tem de corresponder ao operationId disponível na Descrição de OpenAPI.
composeExtensions.commands.context
Matriz onde os pontos de entrada para a extensão de mensagem estão definidos. Os valores predefinidos são compose e commandBox.
composeExtensions.commands.parameters
Define uma lista estática de parâmetros para o comando . O nome tem de ser mapeado para na parameters.name Descrição de OpenAPI. Se estiver a referenciar uma propriedade no esquema do corpo do pedido, o nome tem de mapear para properties.name ou consultar parâmetros.
O modelo de composição de respostas é um formato predefinido que dita a forma como os resultados da sua API são apresentados no Teams. Utiliza modelos para criar Cartões Ajustáveis ou outros elementos de IU a partir da resposta da API, garantindo uma experiência de utilizador integrada e integrada no Teams. O modelo define o esquema e o estilo das informações apresentadas, que podem incluir texto, imagens e componentes interativos. Certifique-se de que cumpre as seguintes diretrizes para o modelo de composição de respostas:
Os valores suportados para responseLayout são list e grid, que determinam como a resposta é apresentada visualmente. Para obter mais informações sobre o esquema, veja Responder a pedidos de utilizador.
A jsonPath é necessário para matrizes ou quando os dados do Cartão Ajustável não são o objeto raiz. Por exemplo, se os seus dados estiverem aninhados em productDetails, o caminho JSON seria productDetails.
Defina jsonPath como o caminho para os dados ou matriz relevantes na resposta da API. Se o caminho apontar para uma matriz, cada entrada na matriz vincula-se ao modelo Cartão Ajustável e devolve como um resultado separado.
[Opcional]
Obtenha uma resposta de exemplo para validar o modelo de composição de resposta. Isto serve como um teste para garantir que o seu modelo funciona conforme esperado.
Utilize ferramentas como o Fiddler ou o Postman para chamar a API e garantir que o pedido e a resposta são válidos. Este passo é crucial para resolver problemas e confirmar que a API está a funcionar corretamente.
Pode utilizar o cartão ajustável Designer para vincular a resposta da API ao modelo de composição de resposta e pré-visualizar o Cartão Ajustável. Insira o modelo Cartão Ajustável no EDITOR DE PAYLOAD CARTÃO e insira a entrada de resposta de exemplo no EDITOR DE DADOS DE EXEMPLO.
O código seguinte é um exemplo de um modelo de composição de Resposta:
Um modelo de card de pré-visualização no esquema de modelo de composição de resposta é utilizado para mapear respostas JSON para uma pré-visualização card que os utilizadores veem quando selecionam um resultado de pesquisa. A pré-visualização card, em seguida, expande-se para um Cartão Ajustável na caixa de composição de mensagens. O modelo de card de pré-visualização faz parte do modelo de composição de resposta, que também inclui um modelo de Cartão Ajustável e metadados.
Cartão Ajustável Expandido
Parâmetros
Propriedade
Tipo
Descrição
Obrigatório
version
string
A versão de esquema do modelo de composição de resposta atual.
Sim
jsonPath
string
O caminho para a secção relevante nos resultados aos quais o responseCardTemplate e previewCardTemplate devem ser aplicados. Se não estiver definido, o objeto raiz é tratado como a secção relevante. Se a secção relevante for uma matriz, cada entrada é mapeada para responseCardTemplate e previewCardTemplate.
Não
responseLayout
responseLayoutType
Especifica o esquema dos resultados na lista de opções da extensão de mensagem. Os tipos suportados são list e grid.
Sim
responseCardTemplate
adaptiveCardTemplate
Um modelo para criar um Cartão Ajustável a partir de uma entrada de resultado.
Sim
previewCardTemplate
previewCardTemplate
Um modelo para criar uma pré-visualização card a partir de uma entrada de resultados. O card de pré-visualização resultante é apresentado no menu de lista de opções da extensão de mensagem.
Sim
Caminho Json
O caminho JSON é opcional, mas deve ser utilizado para matrizes ou onde o objeto a ser utilizado como dados para o Cartão Ajustável não é o objeto raiz. O caminho JSON deve seguir o formato definido pela Newtonsoft. Esta ferramenta pode ser utilizada. Pode utilizar a ferramenta JSON para validar se um caminho JSON está correto. Se o caminho JSON apontar para uma matriz, cada entrada nessa matriz está vinculada ao modelo Cartão Ajustável e devolve como resultados separados.
Exemplo Suponhamos que tem o seguinte JSON para uma lista de produtos e quer criar um resultado card para cada entrada.
Como pode ver, a matriz de resultados está em "produtos", que está aninhada em "armazém", pelo que o caminho JSON seria "warehouse.products".
Utilize a Designer de Cartões Ajustáveis para pré-visualizar um Cartão Ajustável ao inserir o modelo no cartão payload Editor. Utilize uma entrada de resposta de exemplo da matriz ou do objeto e insira-a no Editor de Dados de Exemplo. Certifique-se de que o card é composto corretamente e é do seu agrado.
Conversão de esquema OpenAPI
Observação
Enviamos um cabeçalho accept-language no pedido HTTP que é enviado para o ponto final definido no documento de descrição openAPI. A linguagem accept-language baseia-se na região do cliente do Teams e pode ser utilizada pelo programador para devolver uma resposta localizada.
Os seguintes tipos de dados no documento de descrição openAPI são convertidos em elementos dentro de um Cartão Ajustável da seguinte forma:
stringos tipos , number, integerboolean são convertidos num TextBlock.
Exemplo
Esquema de Origem: string, , numberintegereboolean
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.
Comentários do
Platform Docs
O
Platform Docs
é um projeto código aberto. Selecione um link para fornecer comentários:
Saiba mais sobre a extensão de mensagens baseada em Bot através do Bot Framework para interagir com o seu serviço Web a partir de diferentes localizações no cliente do Teams.
Saiba como criar ou criar uma extensão de mensagem baseada em API com o Portal do Programador para Teams, o Teams Toolkit para Visual Studio, Visual Studio Code e a CLI.
Saiba como definir comandos de ação da extensão de mensagens com o manifesto da aplicação no Teams. Exemplo (.NET, Node.js), caixa de diálogo criar (módulo de tarefa), responder à ação de submissão da caixa de diálogo.
Saiba como criar extensões de mensagens e os cenários em que são utilizadas. Explore exemplos sobre extensões de mensagens baseadas em ações e pesquisas.
Saiba como criar e enviar caixas de diálogo (módulos de tarefas). Processe a ação de invocação inicial e responda com uma caixa de diálogo (módulo de tarefa) a partir de um comando de extensão de mensagem de ação.
Saiba como criar e configurar extensões de mensagens baseadas em ações para o Microsoft Teams com o SDK do Bot Framework para permitir que os utilizadores acionem serviços externos.
Neste módulo, saiba mais sobre uma extensão de mensagem com um documento de Descrição openAPI (OAD) com o Teams Toolkit e crie uma extensão de mensagem baseada em API.
Learn how to build message extensions that allow users to interact with external services within their flow of work in Microsoft Teams and Microsoft 365 Copilot.
