Criar extensões de mensagens com a API

Observação

As extensões de mensagens baseadas em API só suportam comandos de pesquisa.

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. Pode configurar e implementar extensões de mensagens baseadas em API com o Portal do Programador para o Teams e o Teams Toolkit para Visual Studio Code, a interface de linha de comandos (CLI) ou o Visual Studio. 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.

Pode criar uma extensão de mensagem baseada em API com um documento Descrições OpenAPI (OAD). Depois de criar um documento de Descrição de OpenAPI, utilize o documento Descrição de OpenAPI para gerar e integrar o código de cliente no projeto da sua aplicação. Crie ou gere um modelo de composição de respostas para gerir as respostas da API.

Veja o vídeo para saber mais sobre a criação de uma extensão de mensagem baseada em API com o Teams Toolkit:

Pré-requisitos

Antes de começar, certifique-se de que cumpre os seguintes requisitos:

• Descrição de OpenAPI (OAD)
• Atualizar manifesto do aplicativo

Descrição de OpenAPI

A Descrição de OpenAPI (OAD) é a especificação padrão da indústria que detalha a estrutura e destaque dos ficheiros OpenAPI. É um formato agnóstico e legível por humanos para descrever APIs. Tanto os humanos como as máquinas podem ler e escrever facilmente a Descrição openAPI. O esquema é legível por computador e pode ser representado em YAML ou JSON. É necessário um documento de Descrição de OpenAPI antes de criar uma extensão de mensagem condicionada por API.

Modelo de composição de resposta

Um modelo de composição de resposta mapeia respostas JSON a um cartão de pré-visualização e a um Cartão Ajustável. Quando um utilizador seleciona um resultado de pesquisa, os cartões de pré-visualização são apresentados como resultados. Em seguida, o cartão de pré-visualização expande-se para um Cartão Ajustável na caixa de composição de mensagens.

Cada comando de pesquisa tem de ter um modelo de composição de resposta correspondente e cada comando tem de corresponder a uma operação na Descrição de OpenAPI. No entanto, nem todas as operações definidas numa Descrição openAPI têm de ser um comando. O modelo de composição de resposta consiste num modelo de Cartão Ajustável, modelo de cartão de pré-visualização e metadados e tem de estar em conformidade com o esquema do modelo de composição de resposta alojado em https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.ResponseRenderingTemplate.schema.json.

Atualizar manifesto do aplicativo

Atualize o manifesto da aplicação (anteriormente denominado manifesto da aplicação Teams) com a composeExtensions propriedade . O código seguinte é um exemplo do manifesto da aplicação com a composeExtensions propriedade :

{
  "composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "apiSpecificationFile": "aitools-openapi.yml",
      "commands": [
        {
          "id": "searchTools",
          "type": "query",
          "context": [
            "compose",
            "commandBox"
          ],
          "title": "search for AI tools",
          "description": "search for AI tools",
          "parameters": [
            {
              "name": "search",
              "title": "search query",
              "description": "e.g. search='tool to create music'"
            }
          ],
          "apiResponseRenderingTemplateFile": "response-template.json"
        }
      ]
    }
  ]
}

Próxima etapa

Criar uma extensão de mensagem baseada em API