Bot de notificação interativo no Teams

Artigo
06/26/2024

O Microsoft Teams Toolkit permite-lhe criar aplicações que capturam eventos e as enviam como notificações interativas para um chat pessoal, de grupo ou um canal no Microsoft Teams. Pode enviar notificações como texto simples ou Cartões Ajustáveis. O modelo de bot de notificação cria uma aplicação que envia uma mensagem para o Teams com Cartões Ajustáveis acionados por http post request.

O modelo de aplicação é criado com o SDK do TeamsFx, que fornece um conjunto simples de funções através do Microsoft Bot Framework para implementar os seus requisitos. Por exemplo, uma agência de viagens cria uma aplicação no Teams para que os seus utilizadores as mantenham atualizadas com a previsão meteorológica. No fluxograma seguinte, uma aplicação do Teams notifica sobre a previsão meteorológica para os utilizadores que utilizam um Cartão Ajustável:

Pode enviar uma notificação de bot nos seguintes cenários:

Pretende notificar todas as pessoas num canal ou conversar sobre o mesmo conteúdo ou conteúdo relacionado.
IU altamente personalizável num Cartão
Precisa de resposta rápida, incluir conteúdo multimédia ou botões de ação.
Enviar notificações agendadas
Destaques duplos claros sobre Atividade e Chat, Canal ou Aplicação
Adicionar modelo no código fonte.
Processar a localização manualmente.

Vantagens

Facilita as notificações para um chat pessoal, de grupo e num canal, através de APIs do SDK do TeamsFx.
Melhora a experiência do utilizador ao personalizar a notificação com um Cartão Ajustável.
Fornece vários mecanismos para acionar notificações, como HTTP e acionador de temporizador de agendamento com as Funções do Azure.
Um cartão de notificação integra-se facilmente com um bot e proporciona uma experiência de utilizador consistente na aplicação Bot.

Observação

A aplicação bot tem de ser instalada com o âmbito correspondente antes de enviar a notificação.

Voltar ao início

Notificação baseada em eventos

O SDK do Bot Framework fornece a funcionalidade para enviar mensagens proativamente no Teams. O SDK do TeamsFx fornece a funcionalidade para gerir as referências de conversação do bot quando um evento de bot é acionado. O SDK do TeamsFx reconhece os seguintes eventos de bot:

Event	Comportamento
A primeira vez que instalar um bot numa pessoa, grupo ou Equipa.	Adicione a referência de conversação de destino ao armazenamento.
Quando o bot é desinstalado de uma pessoa, grupo ou Equipa.	Remova a referência de conversação de destino do armazenamento.
Quando a equipa instalada pelo bot é eliminada.	Remova a referência de conversação de destino do armazenamento.
Quando a equipa instalada pelo bot é restaurada.	Adicione a referência de conversação de destino ao armazenamento.
Quando o bot envia mensagens.	Quando a referência de conversação de destino não existir, adicione-a ao armazenamento.

novo exemplo de evento de notificação

Quando envia notificações, o SDK do TeamsFx cria uma nova conversação a partir da referência de conversação selecionada e, em seguida, envia uma mensagem. Para uma utilização avançada, pode aceder diretamente à referência de conversação para executar a sua própria lógica de bot:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // call Bot Framework's adapter.continueConversationAsync()
    await target.adapter.continueConversationAsync(
        target.botAppId,
        target.conversationReference,
        async (context) => {
            // your own bot logic
            await context...
        }
    );
}

   // list all installation targets
    foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // call Bot Framework's adapter.ContinueConversationAsync()
    await target.Adapter.ContinueConversationAsync(
        target.BotAppId,
        target.ConversationReference,
        async (context, ctx) =>
        {
            // your own bot logic
            await context...
        },
        cancellationToken);
}

Voltar ao início

Instalação do bot de notificação

Um bot de notificação tem de ser instalado numa equipa, numa conversa de grupo ou como aplicação pessoal, consoante o âmbito necessário. Tem de selecionar o destino da instalação antes de adicionar o bot à sua aplicação.

adicionar âmbito de instalação

Para obter mais opções de instalação, veja Configurar opções de instalação predefinidas. Para desinstalar, consulte Remover uma aplicação do Teams.

Voltar ao início

Personalizar notificação

Pode fazer as seguintes personalizações para expandir o modelo de notificação de acordo com as suas necessidades empresariais:

Personalizar o ponto de acionador a partir da origem de eventos
Personalizar o conteúdo da notificação
Personalizar para onde as notificações são enviadas

Personalizar o ponto de acionador a partir da origem de eventos

Pode personalizar os seguintes acionadores:

Restify notificação baseada em:
- Quando um pedido HTTP é enviado para o src/index.js ponto de entrada, a implementação predefinida envia um Cartão Ajustável para o Teams. Pode personalizar este evento ao modificar src/index.js. Uma implementação típica pode chamar uma API para obter eventos, dados ou ambos que podem enviar um Cartão Ajustável conforme necessário. Pode efetuar o seguinte para adicionar mais acionadores:
  - Crie um novo encaminhamento: server.post("/api/new-trigger", ...).
  - Adicione acionadores de temporizador a partir de pacotes npm amplamente utilizados, como cron, agendamento de nós ou de outros pacotes.
  Observação
  
  Por predefinição, o Teams Toolkit estrutura um único restify ponto de entrada no src/index.js.
Notificação baseada nas Funções do Azure:
- Quando seleciona timer acionador, o acionador src/timerTrigger.ts de temporizador predefinido da Função do Azure implementado envia um Cartão Ajustável a cada 30 segundos. Pode editar o ficheiro *Trigger/function.json para personalizar a schedule propriedade. Para obter mais informações, veja Documentação da Função do Azure.
- Quando seleciona http acionador, o pedido HTTP aciona a notificação e a implementação predefinida envia um Cartão Ajustável para o Teams. Pode alterar este evento ao personalizar src/*Trigger.ts. Esta implementação pode chamar uma API para obter eventos, dados ou ambos, que podem enviar um Cartão Ajustável conforme necessário.
Acionadores da Função do Azure:
- Event Hub acionador para enviar notificações quando um evento é emitido para o Hub de Eventos do Azure.
- Cosmos DB acionador para enviar notificações quando um documento do Cosmos é criado ou atualizado.

Para obter mais informações sobre os acionadores de suporte, veja Acionadores de suporte das Funções do Azure.

Personalizar o conteúdo da notificação

O ficheiro src/adaptiveCards/notification-default.json define o Cartão Ajustável predefinido. Pode utilizar o estruturador de Cartões Ajustáveis para ajudar a estruturar visualmente a IU do Cartão Ajustável. Define src/cardModels.ts uma estrutura de dados que é utilizada para carregar dados para o Cartão Ajustável. O enlace entre o modelo de cartão e o Cartão Ajustável é efetuado por nome correspondente, como CardData.title mapas ${title} , no Cartão Ajustável. Pode adicionar, editar ou remover propriedades e os respetivos enlaces para personalizar o Cartão Ajustável conforme necessário.

Também pode adicionar novos cartões, se necessário. Para obter mais informações sobre como criar diferentes tipos de Cartões Ajustáveis com uma lista ou índice dinâmico com ColumnSet o e FactSet, veja Exemplo de notificação de Cartão Adaptável.

Personalizar para onde as notificações são enviadas

Pode personalizar o envio da notificação para os seguintes destinos:

Notificações para um chat pessoal:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // "Person" means this bot is installed as Personal app
    if (target.type === "Person") {
        // Directly notify the individual person
        await target.sendAdaptiveCard(...);
    }
}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Person" means this bot is installed as Personal app
    if (target.Type == NotificationTargetType.Person)
    {
        // Directly notify the individual person
        await target.SendAdaptiveCard(...);
    }
}

Notificações para um chat de grupo:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // "Group" means this bot is installed to a Group Chat
    if (target.type === "Group") {
        // Directly notify the Group Chat
        await target.sendAdaptiveCard(...);

            // List all members in the Group Chat then notify each member
            const members = await target.members();
            for (const member of members) {
                await member.sendAdaptiveCard(...);
            }
        }

}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Group" means this bot is installed to a Group Chat
    if (target.Type == NotificationTargetType.Group)
    {
        // Directly notify the Group Chat
        await target.SendAdaptiveCard(...);
    // List all members in the Group Chat then notify each member
        var members = await target.GetMembersAsync();
        foreach (var member in members) {
            await member.SendAdaptiveCard(...);
        }
    }
}

Notificações para um canal:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // "Channel" means this bot is installed to a Team (default to notify General channel)
    if (target.type === "Channel") {
        // Directly notify the Team (to the default General channel)
        await target.sendAdaptiveCard(...);

        // List all members in the Team then notify each member
        const members = await target.members();
        for (const member of members) {
            await member.sendAdaptiveCard(...);
        }

        // List all channels in the Team then notify each channel
        const channels = await target.channels();
        for (const channel of channels) {
            await channel.sendAdaptiveCard(...);
        }
    }
}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Channel" means this bot is installed to a Team (default to notify General channel)
    if (target.Type == NotificationTargetType.Channel)
    {
        // Directly notify the Team (to the default General channel)
        await target.SendAdaptiveCard(...);

        // List all members in the Team then notify each member
        var members = await target.GetMembersAsync();
        foreach (var member in members) {
            await member.SendAdaptiveCard(...);
        }

        // List all channels in the Team then notify each channel
        var channels = await target.GetChannelsAsync();
        foreach (var channel in channels) {
            await channel.SendAdaptiveCard(...);
        }
    }
}

Notificações para um canal específico:

// find the first channel when the predicate is true.
const channel = await notificationApp.notification.findChannel(c => Promise.resolve(c.info.name === "MyChannelName"));

// send adaptive card to the specific channel.
await channel?.sendAdaptiveCard(...);

Observação

Para impedir uma saída indefinida, certifique-se de que instala a aplicação bot no canal Geral de uma Equipa.

Notificações para uma pessoa específica:

// find the first person when the predicate is true.
const member = await notificationApp.notification.findMember(m => Promise.resolve(m.account.name === "Bob"));

// send adaptive card to the specific person. 
await member?.sendAdaptiveCard(...);

Observação

Para impedir um resultado indefinido e uma notificação em falta, tem de incluir a pessoa específica no âmbito da instalação de notificação.

Voltar ao início

Personalizar inicialização

Tem de criar ConversationBot para enviar uma notificação.

Observação

O código é gerado no projeto.

JavaScript/TypeScript
C#

/** Javascript/Typescript: src/internal/initialize.*s **/
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
    },
});

/** .NET: Program.cs or Startup.cs **/
// Create the Conversation with notification feature enabled.
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        // To use your own CloudAdapter
        Adapter = sp.GetService<CloudAdapter>(),
        Notification = new NotificationOptions
        {
            BotAppId = builder.Configuration["MicrosoftAppId"],
        },
    };

    return new ConversationBot(options);
});

Voltar ao início

Personalizar adaptador

Pode personalizar ao criar o seu próprio adaptador ou personalizar o adaptador após a inicialização. Segue-se o exemplo de código para criar o adaptador:

// Create your own adapter
const adapter = new CloudAdapter(...);

// Customize your adapter, e.g., error handling
adapter.onTurnError = ...

const notificationApp = new ConversationBot({
    // use your own adapter
    adapter: adapter;
    ...
});

// Or, customize later
notificationApp.adapter.onTurnError = ...

Voltar ao início

Adicionar armazenamento

O armazenamento pode ser utilizado para implementar ligações de notificação. Pode adicionar o seu próprio armazenamento com a ajuda do seguinte exemplo de código:

TypeScript
C#

// implement your own storage
class MyStorage implements NotificationTargetStorage {...}
const myStorage = new MyStorage(...);

// initialize ConversationBot with notification enabled and customized storage
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
        storage: myStorage,
    },
});

// implement your own storage
public class MyStorage : INotificationTargetStorage {...}

// initialize ConversationBot with notification enabled and customized storage
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        Adapter = sp.GetService<CloudAdapter>(),
        Notification = new NotificationOptions
        {
            BotAppId = builder.Configuration["MicrosoftAppId"],
            // Use your own storage
            Storage = new MyStorage(),
        },
    };

    return new ConversationBot(options);
});

Se o armazenamento não for fornecido, pode utilizar um armazenamento de ficheiros local predefinido, que armazena ligações de notificação em:

.notification.localstore.json se estiver a ser executado localmente.
${process.env.TEMP}/.notification.localstore.json, se process.env.RUNNING_ON_AZURE estiver definido como 1.

Se estiver a utilizar o armazenamento de ficheiros local predefinido, a aplicação Web do Azure e as Funções do Azure limpam o ficheiro local durante um reinício ou reimplementação. Também pode desinstalar o bot do Teams e, em seguida, instalá-lo para adicionar novamente ligações ao armazenamento.

O NotificationTargetStorage é diferente do armazenamento personalizado do SDK do Bot Framework. O armazenamento de notificações readrequer , write, deletee list funcionalidades, mas o armazenamento do SDK do Bot Framework tem read, writee delete funcionalidades e não tem a list funcionalidade.

Para obter mais informações sobre o armazenamento de blobs do Azure, veja o exemplo de implementação do armazenamento de notificações.

Observação

Recomenda-se que utilize o seu próprio armazenamento partilhado para o ambiente de produção.
Se implementar o armazenamento do seu próprio SDK do Bot Framework, por exemplo, botbuilder-azure-blobs.BlobsStorage, terá de implementar outro armazenamento para notificação. Pode partilhar a mesma Cadeia de Ligação de Blobs com contentores diferentes.

Voltar ao início

Adicionar autenticação para a API de notificação

Se selecionar acionador HTTP, a API de notificação estruturada não tem autenticação ou autorização ativada. Certifique-se de que adiciona autenticação ou autorização à API antes de a utilizar para produção. Pode efetuar uma das seguintes ações:

Utilize uma chave de API. Pode utilizar chaves de acesso de função se selecionar Funções do Azure para alojar o seu bot de notificação.
Utilize um token de acesso emitido pelo Microsoft Entra ID. Para obter mais informações, veja Configure SSO for your bot in Microsoft Entra ID (Configurar o SSO para o bot no Microsoft Entra ID).

Pode haver mais soluções de autenticação ou autorização para uma API. Pode selecionar conforme necessário.

Voltar para o início

Ligar a APIs existentes

Se não tiver o SDK necessário e quiser invocar APIs externas no seu código, o comando Teams: Ligar a uma API na extensão Microsoft Visual Studio Code Teams Toolkit ou o comando teamsfx add api-connection na CLI do TeamsFx pode ser utilizado para iniciar o código de arranque para chamar APIs de destino. Para obter mais informações, veja Integrar APIs de terceiros existentes.

Aplicação de bot do Teams ou Webhook de Receção do Teams

O TeamsFx suporta duas formas de o ajudar a enviar notificações do seu sistema para o Teams:

Crie uma aplicação de bot do Teams.
Crie o Webhook de Receção do Teams.

Na tabela seguinte, pode ver a comparação das duas formas diferentes:

	Aplicação de bot do Teams	Webhook de Receção do Teams
Enviar mensagem a uma pessoa individual	✔️	❌
Chat do grupo de mensagens	✔️	❌
Canal público de mensagens	✔️	✔️
Canal privado de mensagens	❌	✔️
Enviar mensagem de cartão	✔️	✔️
Enviar mensagem de boas-vindas	✔️	❌
Obter contexto do Teams	✔️	❌
Exigir passos de instalação no Teams	✔️	❌
Exigir o recurso do Azure	Azure Bot Service	❌

Notificação de Webhook recebido

Os Webhooks Recebidos ajudam a postar mensagens de aplicativos para o Teams. Se os Webhooks recebidos estiverem ativados para uma Equipa em qualquer canal, expõe o ponto final HTTPS, que aceita JSON corretamente formatado e insere as mensagens nesse canal. Por exemplo, você pode criar um Webhook de entrada em seu canal DevOps, configurar sua compilação e, simultaneamente, implantar e monitorar serviços para enviar alertas. O TeamsFx fornece-lhe um exemplo de notificação de Webhook recebido que o ajuda a:

Crie um Webhook recebido no Teams.
Enviar notificações através de Webhooks recebidos com Cartões Ajustáveis.

Voltar ao início

Enviar notificações de feed de atividades

Se quiser enviar notificações do feed de atividades para a sua aplicação, pode utilizar as APIs de notificação do feed de atividades no Microsoft Graph. Para obter mais informações, consulte Enviar notificações do feed de atividades aos utilizadores no Microsoft Teams.

Perguntas frequentes

Porque é que as instalações de notificação estão vazias, apesar de a aplicação de bot estar instalada no Teams?

O Teams envia um evento apenas na primeira instalação. Se a aplicação de bot já estiver instalada antes de o serviço de bot de notificação ser iniciado, o evento de instalação não chegou ao serviço de bot ou é omitido.

Pode resolver este problema das seguintes formas:

Envie uma mensagem para o seu bot pessoal ou mencione o bot no chat ou canal de grupo, o que o ajuda a aceder novamente ao serviço de bot com as informações de instalação corretas.
Desinstale a aplicação de bot do Teams e, em seguida, volte a depurá-la ou reiniciá-la. Pode reenviar o evento de instalação para o serviço de bot.

As ligações de destino de notificação são armazenadas no armazenamento de persistência. Se estiver a utilizar o armazenamento de ficheiros local predefinido, todas as instalações são armazenadas em .notification.localstore.json.

Observação

Para obter mais informações sobre como adicionar o seu próprio armazenamento, veja Adicionar armazenamento.

Por que motivo ocorre um erro de Pedido Incorreto ou Argumento Incorreto ao enviar a notificação?

Se a instalação da notificação não corresponder ao ID ou palavra-passe do bot, poderá obter um erro Falha ao desencriptar o ID da conversação . Uma causa possível para este erro é o ID ou palavra-passe do bot ser alterado devido à limpeza do estado local ou ao reaprovisionamento.

Pode resolver este problema ao limpar o armazenamento de notificações. Após a limpeza, notifique no Teams para reinstalar o bot e certifique-se de que a nova instalação está atualizada. Cada instalação de notificação armazenada está vinculada a um bot. Se conseguir verificar o armazenamento de notificações, o respetivo campo de bot deverá corresponder ao bot que está a executar, como o ID do bot com o mesmo GUID.

Observação

No caso do armazenamento local, a localização predefinida é .notification.localstore.json.

Por que motivo o destino de notificação é perdido após reiniciar ou reimplementar a aplicação de bot?

As ligações de destino de notificação são armazenadas no armazenamento de persistência. Se estiver a utilizar o armazenamento de ficheiros local predefinido, a aplicação Web do Azure e as Funções do Azure limpam o ficheiro local durante um reinício ou reimplementação. Também pode desinstalar o bot do Teams e, em seguida, instalá-lo para adicionar novamente ligações ao armazenamento. Recomenda-se que utilize o seu próprio armazenamento partilhado para o ambiente de produção.

Por que motivo é devolvido um erro indefinido ao utilizar a API "findChannel"()?

Pode deparar-se com um erro indefinido quando a aplicação de bot é instalada noutros canais em vez do General canal. Para corrigir este erro, pode desinstalar a aplicação de bot do Teams e redepurar e relançá-la. Depois de ter redepurado e reiniciado, certifique-se de que a aplicação de bot está instalada no General canal.

Posso saber todos os destinos onde o meu bot está instalado dentro e fora do projeto de notificação?

Existem APIs do Microsoft Graph para listar aplicações instaladas numa equipa, grupo ou chat. Se necessário, itere a sua equipa, grupo ou conversa numa aplicação instalada para ser direcionada. No projeto de notificação, utiliza o armazenamento de persistência para armazenar destinos de instalação. Para obter mais informações, veja notificação baseada em eventos.

Como personalizar as portas de escuta do Azurite?

Se o Azurite sair devido à porta em utilização, pode especificar outra porta de escuta e atualizar a cadeia de ligação de AzureWebJobsStorage em local.settings.json.

Como expandir o meu bot de notificação para suportar o comando e a resposta?

Aceda a e atualize a bot\src\internal\initialize.ts(js)conversationBot inicialização para ativar a funcionalidade de notificação:
Para adicionar o comando ao bot, siga as instruções no Bot de comandos no Teams.

Como expandir o meu bot de notificação ao adicionar ações de Cartão Adaptável do bot de fluxo de trabalho?

A funcionalidade processador de ações cartão ajustável permite que a aplicação responda a ações de Cartão Adaptável que são acionadas pelos utilizadores finais para concluir um fluxo de trabalho sequencial. Um Cartão Ajustável fornece um ou mais botões no cartão para pedir a entrada do utilizador, como chamar algumas APIs. Em seguida, o Cartão Ajustável envia outro Cartão Ajustável na conversação para responder à ação do cartão.

Para obter mais informações sobre como adicionar ações de cartões ajustáveis ao bot de comandos, veja Bot de fluxo de trabalho no Teams.

Voltar ao início

Guias passo a passo

Siga o guia passo a passo para criar o bot de notificação do Teams.

Compartilhar via

Bot de notificação interativo no Teams

Notificação baseada em eventos

Instalação do bot de notificação

Personalizar notificação

Personalizar o ponto de acionador a partir da origem de eventos

Personalizar o conteúdo da notificação

Personalizar para onde as notificações são enviadas

Personalizar inicialização

Personalizar adaptador

Adicionar armazenamento

Adicionar autenticação para a API de notificação

Ligar a APIs existentes

Aplicação de bot do Teams ou Webhook de Receção do Teams

Notificação de Webhook recebido

Enviar notificações de feed de atividades

Perguntas frequentes

Guias passo a passo

Confira também

Comentários

Recursos adicionais