Compartilhar via

Trabalhar com Ações Universais para Cartões Adaptáveis

  • Artigo

As Ações Universais para Cartões Ajustáveis proporcionam uma forma de implementar cenários baseados em Cartões Ajustáveis para o Teams e o Outlook. Este documento abrange os seguintes tópicos:

Guia de início rápido para usar Ações Universais para Cartões Adaptáveis no Teams

  1. Substitua todas as instâncias de Action.Submit por Action.Execute para atualizar um cenário existente no Teams.

  2. Adicione uma cláusula refresh ao seu Cartão Adaptável, se você desejar usar o modelo de atualização automática ou se seu cenário exigir Exibições Específicas do Usuário.

    Observação

    Especifique a userIds propriedade para identificar os utilizadores que recebem atualizações automáticas.

  3. Manipule solicitações de invocação adaptiveCard/action em seu bot.

  4. Use o contexto da solicitação de invocação para responder com cartões criados para um usuário.

    Observação

    Sempre que um bot retorna um novo cartão como resultado do processamento de um Action.Execute, a resposta deve estar de acordo com o formato de resposta.

Esquema de Ações Universais para Cartões Adaptáveis

As Ações Universais para Cartões Ajustáveis são introduzidas na versão 1.5 do esquema cartões ajustáveis. Para utilizar o Cartão Adaptável de forma eficaz, a version propriedade do seu Cartão Ajustável tem de ser definida como 1,5.

Observação

Definir a propriedade como 1,5 torna o version seu Cartão Ajustável incompatível com clientes mais antigos das plataformas ou aplicações, como o Outlook e o Teams, uma vez que não suportam as Ações Universais para Cartões Ajustáveis.

Se definir a versão do cartão para menos de 1,5 e utilizar ambos ou ambos, refresh a propriedade e Action.Execute, acontece o seguinte:

Cliente Comportamento
Teams Seu cartão para de funcionar. O cartão não é atualizado e Action.Execute não é composto consoante a versão do cliente do Teams. Para garantir a compatibilidade máxima no Teams, defina Action.Execute com um Action.Submit na propriedade de fallback.

Para obter mais informações sobre como dar suporte a clientes mais antigos, consulte compatibilidade com versões anteriores.

Action.Execute

Ao criar Cartões Adaptáveis, substitua Action.Submit e Action.Http por Action.Execute. O esquema para Action.Execute é semelhante ao de Action.Submit.

Para obter mais informações, consulte o esquema e as propriedades Action.Execute.

Agora, você pode usar o modelo de atualização para permitir que Cartões Adaptáveis sejam atualizados automaticamente.

Modelo de atualização

Para atualizar automaticamente seu Cartão Adaptável, defina sua propriedade refresh, que insere uma ação do tipo Action.Execute e uma matriz userIds.

Para obter mais informações, consulte atualizar esquema e propriedades.

IDs de usuário na atualização

Estes são os recursos de UserIds na atualização:

  • UserIds é uma matriz de MRIs de usuários, que faz parte da propriedade refresh em Cartões Adaptáveis.

  • Se a propriedade da userIds lista for especificada como userIds: [] na secção de atualização do cartão, o cartão não é atualizado automaticamente. Em vez disso, é apresentada uma opção Atualizar Cartão ao utilizador no menu de pontos triplos no cliente Web ou no ambiente de trabalho do Teams e no menu de contexto de imprensa longa no Teams mobile, ou seja, Android ou iOS para atualizar manualmente o cartão. Em alternativa, pode optar por ignorar userIds completamente a propriedade de atualização caso o cenário envolva <=60 membros em chats ou canais de grupo do Teams. O cliente do Teams invoca automaticamente chamadas de atualização para todos os utilizadores se o grupo ou canal tiver <=60 utilizadores.

  • A propriedade userIds é adicionada porque os canais no Teams podem incluir um número grande de membros. Se todos os membros estão exibindo o canal ao mesmo tempo, uma atualização automática incondicional resultará em muitas chamadas simultâneas para o bot. A propriedade userIds deve sempre ser incluída para identificar quais usuários devem obter uma atualização automática com um máximo de 60 (sessenta) MRIs de usuário.

  • Pode obter as MRIs de utilizador do membro da conversação do Teams. Para obter mais informações sobre como adicionar na lista userIds na secção de atualização do Cartão Ajustável, veja Obter lista ou perfil de utilizador.

Você pode obter a MRI do usuário para o canal, chat em grupo ou chat 1:1 usando o seguinte exemplo:

  1. Usando TurnContext

    userMRI= turnContext.Activity.From.Id

  2. Usando o método GetMemberAsync

    var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);var userMRI = member.Id;

  • Exemplo de MRI de usuário do Teams é 29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk

Observação

A propriedade userIds é ignorada no Outlook e a propriedade refresh é sempre ativada automaticamente. Não há nenhum problema de escala no Outlook porque os usuários exibem o cartão em momentos diferentes.

A próxima etapa é usar a atividade de inovação adaptiveCard/action para entender qual solicitação deve ser feita depois que Action.Execute é executado.

adaptiveCard/action atividade de invocação

Quando Action.Execute é executado no cliente, um novo tipo de Atividade de invocação adaptiveCard/action é realizada no bot.

Para obter mais informações, consulte formato da solicitação e propriedades de uma atividade de invocaçãoadaptiveCard/action típica .

Para obter mais informações, consulte formato de resposta e propriedade de uma atividade de invocação típica adaptiveCard/action com tipos de resposta com suporte.

Em seguida, você pode aplicar a compatibilidade com versões anteriores a clientes mais antigos em diferentes plataformas e tornar seu Cartão Adaptável compatível.

Compatibilidade com versões anteriores

As Ações Universais para Cartões Adaptáveis permitem definir propriedades que habilitam a compatibilidade com versões anteriores do Outlook e do Teams.

Teams

Para garantir a compatibilidade com versões anteriores do Teams nos Cartões Adaptáveis, você deve incluir a propriedade fallback e definir seu valor como Action.Submit. Além disso, o código do bot deve processar Action.Execute e Action.Submit.

Para obter mais informações, consulte compatibilidade com versões anteriores no Teams.

Exemplos de código

Nome do exemplo Descrição .NET Node.js Manifesto
Bot de refeições do Teams Este exemplo mostra um bot que aceita a encomenda de alimentos com Cartões Ajustáveis. View NA NA
Cartões Adaptáveis de Fluxos de Trabalho Sequenciais Este exemplo demonstra a implementação de Fluxos de Trabalho Sequenciais, Vistas Específicas do Utilizador e Cartões Ajustáveis atuais em bots. View View Exibir

Confira também