API-Based extensão de mensagem para principiantes

As extensões de mensagens criadas com uma API (baseada em API) melhoram significativamente a funcionalidade das suas aplicações do Teams ao permitir que interajam com serviços externos. Ajuda a simplificar os fluxos de trabalho ao reduzir a necessidade de alternar entre diferentes aplicações.

Pode utilizar a extensão de mensagens da API para integrar serviços externos que são normalmente utilizados no fluxo de trabalho de negócio. Por exemplo, uma empresa que utiliza frequentemente um sistema CRM para gestão de clientes pode utilizar uma Extensão de Mensagens para obter e apresentar dados de clientes diretamente do Teams. Ao reduzir a necessidade de alternar entre diferentes aplicações, o utilizador poupa tempo e melhora. A extensão de mensagens baseada em API é suportada em clientes de ambiente de trabalho, Web e móveis do Teams.

Pré-requisitos

• 4 minutos restantes

Eis uma lista das ferramentas de que precisa para criar e implementar as suas aplicações.

Preparar o ambiente de desenvolvimento

Depois de instalar as ferramentas necessárias, configure o ambiente de desenvolvimento.

Instalar o Toolkit do Teams

O Toolkit do Teams ajuda a simplificar o processo de desenvolvimento com ferramentas para aprovisionar e implementar recursos na cloud para a sua aplicação, publicar na Loja Teams e muito mais.

Pode utilizar o toolkit com Visual Studio Code ou a CLI (interface de linha de comandos), denominada Teamsapp.

npm install -g @microsoft/teamsapp-cli

sudo npm install -g --unsafe-perm @microsoft/teamsapp-cli

Configurar o seu inquilino de desenvolvimento do Teams

Um inquilino é como um espaço ou um contentor para a sua organização no Teams, onde conversa, partilha ficheiros e executa reuniões. Este espaço também é onde carrega e testa a sua aplicação personalizada. Vamos verificar se está pronto para programar com o inquilino.

Verificar a opção de carregamento de aplicações personalizadas

Depois de criar o aplicativo, você deve carregar seu aplicativo no Teams sem distribuí-lo. Este processo é conhecido como carregamento de aplicações personalizadas. Inicie sessão na sua conta do Microsoft 365 para ver esta opção.

Já tem um inquilino e tem acesso de administrador? Vamos marcar se realmente o fizer!

Verifique se pode carregar uma aplicação personalizada no Teams:

1. No cliente do Teams, selecione o ícone Aplicações .

2. Selecione Gerenciar seus aplicativos.

3. Selecione Carregar uma aplicação.

4. Procure a opção Carregar uma aplicação personalizada. Se vir a opção, o carregamento de aplicações personalizadas está ativado.

   

   Observação

   Contacte o administrador do Teams se não encontrar a opção para carregar uma aplicação personalizada.

Criar um inquilino gratuito para programadores do Teams (opcional)

Se não tiver uma conta de programador do Teams, pode obtê-la gratuitamente. Adira ao programa de programador do Microsoft 365!

1. Acesse o Programa para desenvolvedores do Microsoft 365.

2. Selecione Aderir Agora e siga as instruções apresentadas no ecrã.

3. No ecrã de boas-vindas, selecione Configurar a subscrição E5.

4. Configurar a conta de administrador. Depois de terminar, é apresentado o ecrã seguinte.

   

5. Inicie sessão no Teams com a conta de administrador que acabou de configurar. Verifique se tem a opção Carregar uma aplicação personalizada no Teams.

Obter uma conta gratuita do Azure

Se quiser alojar a sua aplicação ou aceder a recursos no Azure, tem de ter uma subscrição do Azure. Crie uma conta gratuita antes de começar.

Agora, tem todas as ferramentas para configurar a sua conta. Em seguida, vamos configurar o seu ambiente de desenvolvimento e começar a criar! Selecione a aplicação que pretende criar primeiro.

Criar uma extensão de mensagem baseada em API

• 3 minutos restantes

Depois de configurar a área de trabalho do projeto com o Teams Toolkit, crie o seu projeto de bot. Certifique-se de que tem sessão iniciada na sua conta do Microsoft 365.

Iniciar sessão na sua conta do Microsoft 365

Utilize esta conta para iniciar sessão no Teams. Se estiver a utilizar um inquilino do programa de programador do Microsoft 365, a conta de administrador que configurou durante o registo é a sua conta do Microsoft 365.

Criar documento de Descrição de OpenAPI

A Descrição de OpenAPI (OAD) é a especificação padrão da indústria que descreve como os ficheiros OpenAPI são estruturados e delineados. É um formato agnóstico e legível por humanos para descrever APIs. É fácil para humanos e máquinas lerem e escreverem. O esquema é legível por computador e é representado em YAML ou JSON.

Tem de ter um documento Descrições OpenAPI (OAD) antes de criar uma extensão de mensagem baseada em API. A especificação da API tem de cumprir os seguintes critérios:

• A auth propriedade não pode ser especificada.
• JSON e YAML são os formatos suportados.
• As Versões OpenAPI 2.0 e 3.0.x são suportadas.
• O Teams não suporta as construções oneOf, anyOf, allOf e não (swagger.io).
• 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 corpo do pedido, se estiver presente, tem de ser application/Json para garantir a compatibilidade com uma vasta gama de APIs.
• Defina um URL de servidor de protocolo HTTPS para a servers.url propriedade .
• Só é suportada a pesquisa de parâmetros únicos.
• Só é permitido um parâmetro necessário sem um valor predefinido.
• Apenas os métodos POST e GET HTTP são suportados.
• O documento Descrição de OpenAPI tem de ter um operationId.
• A operação não pode ter os parâmetros Cabeçalho ou Cookie necessários sem valores predefinidos.
• Um comando tem de ter exatamente um parâmetro.
• Certifique-se de que não existem referências remotas no documento Descrição de OpenAPI.
• Um parâmetro necessário com um valor predefinido é considerado opcional.

Utilizámos a seguinte Descrição de OpenAPI como exemplo para este tutorial:

openapi: 3.0.1
info:
  title: OpenTools Plugin
  description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
  version: 'v1'
servers:
- url: https://gptplugin.opentools.ai
paths:
  /tools:
    get:
      operationId: searchTools
      summary: Search for AI Tools
      parameters:
        - in: query
          name: search
          required: true
          schema:
            type: string
          description: Used to search for AI tools by their category based on the keywords. For example, search="tool to create music" gives tools that can create music.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchToolsResponse'
        "400":
          description: Search Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchToolsError'
components:
  schemas:
    searchToolsResponse:
      required:
        - search
      type: object
      properties:
        tools:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the tool.
              opentools_url:
                type: string
                description: The URL to access the tool.
              main_summary:
                type: string
                description: A summary of what the tool is.
              pricing_summary:
                type: string
                description: A summary of the pricing of the tool.
              categories:
                type: array
                items:
                  type: string
                  description: The categories assigned to the tool.
              platforms:
                type: array
                items:
                  type: string
                  description: The platforms that this tool is available on.
          description: The list of AI tools.
    searchToolsError:
      type: object
      properties:
        message:
          type: string
          description: Message of the error.

Agora que tem o documento Descrição de OpenAPI, também requer um modelo de composição de resposta para que a aplicação responda aos pedidos GET ou POST. O modelo de composição de resposta é composto por um modelo de Cartão Ajustável, pré-visualização card modelo e metadados. Se criar uma aplicação com o Teams Toolkit ou o Portal do programador para o Teams, o modelo de composição de resposta é extraído automaticamente do documento Descrição do OpenAPI.

O código seguinte é um exemplo do modelo de composição de resposta:

   {
   "version": "1.0.0",
   "jsonPath": "tools",
   "responseLayout": "list",
   "responseCardTemplate": {
       "type": "AdaptiveCard",
       "version": "1.4",
       "body": [
       {
           "type": "TextBlock",
           "text": "${if(name, name, 'N/A')}",
           "size": "Large",
           "weight": "Bolder",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Categories: ${join(categories, ', ')}",
           "size": "Small",
           "isSubtle": true,
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "${if(main_summary, main_summary, 'N/A')}",
           "size": "Medium",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Supported Platforms: ${join(platforms, ', ')}",
           "size": "Small",
           "isSubtle": true,
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Pricing Summary:",
           "size": "Medium",
           "weight": "Bolder",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "${if(pricing_summary, pricing_summary, 'N/A')}",
           "size": "Small",
           "wrap": true
       }
       ],
       "actions": [
       {
           "type": "Action.OpenUrl",
           "title": "Learn More",
           "url": "${opentools_url}",
           "$when": "${opentools_url != null}"
       },
       {
           "type": "Action.OpenUrl",
           "title": "Chat with Chatbot",
           "url": "${chatbot_short_url}",
           "$when": "${chatbot_short_url != null}"
       }
       ],
       "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
   },
   "previewCardTemplate": {
       "title": "${if(name, name, 'N/A')}"
   }
   }

Agora pode criar uma extensão de mensagem que utiliza o documento Descrição de OpenAPI. Para criar a extensão am message com o documento Descrição de OpenAPI, siga estes passos:

1. Abra o Visual Studio Code.

2. Selecione o ícone Do Teams Toolkit na Barra de Atividade do Visual Studio Code.

3. Selecione Criar uma Nova Aplicação.

   

4. Selecione Extensão da Mensagem.

5. Selecionar Resultados de Pesquisa Personalizados

6. Selecione Iniciar com um Documento de Descrição de OpenAPI.

7. Selecione Procurar e selecione o documento Descrição de OpenAPI que guardou anteriormente. É apresentada uma lista de APIs disponíveis no documento.

8. Selecione as APIs na lista e selecione OK.

9. Selecione Pasta predefinida para armazenar a pasta raiz do projeto na localização predefinida.

   

   Também pode alterar a localização predefinida através dos seguintes passos:

   1. Selecione Procurar.

      

   2. Selecione a localização da área de trabalho do projeto.

   3. Selecione a opção Selecionar Pasta.

      

10. Introduza um nome adequado para a sua aplicação e, em seguida, selecione Enter.

    

    É apresentada uma caixa de diálogo. Selecione Sim, confio nos autores ou Não, não confio nos autores com base no seu requisito.

    

    A sua aplicação teams com uma capacidade de extensão de mensagens baseada em API é criada em poucos segundos.

    

    Após a criação da sua aplicação, o Toolkit do Teams apresenta a seguinte mensagem:

    

    Selecione Depuração local para pré-visualizar o projeto.

Após a conclusão dos andaimes, veja os diretórios e ficheiros do projeto em Explorer no Visual Studio Code.

Aprovisionar a aplicação

Para aprovisionar a sua aplicação no Azure:

1. Aceda a Teams Toolkit e, no painel esquerdo, selecione Executar e Depurar (Ctrl+Shift+D).

2. Selecione Iniciar Remoto no Teams (Edge) no menu pendente iniciar configuração.

   O Toolkit do Teams aprovisiona a sua aplicação no Azure e implementa-a no Teams.

   Observação

   A primeira vez que aprovisionar a sua aplicação, demora alguns minutos a concluir. As disposições subsequentes são mais rápidas.

3. Aceda a uma mensagem de chat e selecione o ícone Ações e aplicações . No menu de opções, procure a sua aplicação.

4. Selecione a aplicação na lista e acione os comandos de pesquisa da área de composição de mensagens.

   

   O Teams envia o resultado da pesquisa como um Cartão Ajustável na mensagem de chat.

   

Desafio completo

• 2 minutos restantes

Encontrou algo assim?

Parabéns!

• 100% concluído!

Você fez isso! Criou uma extensão de mensagem baseada em API.