Compartilhar via

Obtenha o contexto específico do Teams para seu bot

Importante

Os exemplos de código nesta secção baseiam-se na versão 4.6 e versões posteriores do SDK do Bot Framework. Se estiver à procura de documentação para versões anteriores, veja a secção bots – SDK v3 na pasta SDKs Legados da documentação.

Um bot pode acessar dados de contexto adicionais sobre uma equipe ou chat onde está instalado. Essas informações podem ser usadas para enriquecer a funcionalidade do bot e fornecer uma experiência mais personalizada.

Buscar a lista ou perfil de usuário

O bot pode consultar a lista de membros e os respetivos perfis de utilizador básicos, incluindo IDs de utilizador do Teams e informações de Microsoft Entra, como o nome e o objectId. Você pode usar essas informações para correlacionar identidades de usuários. Por exemplo, para marcar se um utilizador iniciou sessão num separador através de Microsoft Entra credenciais é membro da equipa. Para obter membros da conversa, o tamanho mínimo ou máximo da página depende da implementação. Tamanho de página menor que 50, são tratados como 50 e maiores que 500, são limitados a 500. Mesmo se você usar a versão não paginada, ela não é confiável em grandes equipes e não deve ser usada. Para obter mais informações, alterações nas APIs de Bot do Teams para buscar membros da equipe ou de chat.

Observação

  • A paginação está disponível numa equipa e num canal.
  • A paginação não é suportada em chats. Para conversas, todo o plantel é sempre devolvido.

O código de amostra a seguir usa o ponto de extremidade paginado para buscar a lista:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var members = new List<TeamsChannelAccount>();
        string continuationToken = null;

        do
        {   
            // Gets a paginated list of members of one-on-one, group, or team conversation.
            var currentPage = await TeamsInfo.GetPagedMembersAsync(turnContext, 100, continuationToken, cancellationToken);
            continuationToken = currentPage.ContinuationToken;
            members.AddRange(currentPage.Members);
         }
         while (continuationToken != null);
     }
}

Depois de buscar a lista ou perfil de usuário, você pode obter detalhes de um único membro. Para obter informações para um ou mais membros de uma conversa ou equipa, utilize as APIs TeamsInfo.GetMembersAsync de bot do Microsoft Teams para C# ou TeamsInfo.getMembers para APIs TypeScript.

Obter detalhes de membro único

Também pode obter os detalhes de um determinado utilizador com o respetivo ID de utilizador, UPN ou Microsoft Entra ID de Objeto do Teams.

O código de exemplo a seguir é usado para obter detalhes de um único membro:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {   
        // Gets the account of a single conversation member.
        // This works in one-on-one, group, and team scoped conversations.
        var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
    }
}

Depois de obter detalhes de um único membro, você pode obter detalhes da equipe. Para obter informações para uma equipa, utilize as APIs TeamsInfo.GetMemberDetailsAsync de bot do Teams para C# ou TeamsInfo.getTeamDetails para TypeScript.

Obter detalhes da equipe

Quando instalado numa equipa, o bot pode consultar metadados sobre essa equipa, incluindo o Microsoft Entra ID do grupo.

O código de exemplo a seguir é usado para obter os detalhes da equipe:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Gets the details for the given team id. This only works in team scoped conversations.
        // TeamsGetTeamInfo: Gets the TeamsInfo object from the current activity.
        TeamDetails teamDetails = await TeamsInfo.GetTeamDetailsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
        if (teamDetails != null) {
            await turnContext.SendActivityAsync($"The groupId is: {teamDetails.AadGroupId}");
        }
        else {
            // Sends a message activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync($"Message did not come from a channel in a team.");
        }
    }
}

Depois de obter os detalhes da equipe, você pode obter a lista de canais em uma equipe. Para obter informações para uma lista de canais numa equipa, utilize as APIs TeamsInfo.GetTeamChannelsAsync de bot do Teams para C# ou TeamsInfo.getTeamChannels para APIs TypeScript.

Obter a lista de canais em uma equipe

Seu bot pode consultar a lista de canais em uma equipe.

Observação

  • O nome do canal geral padrão é retornado como null para permitir a localização.
  • A ID do canal para o canal Geral sempre corresponde à ID da equipe.

O código de exemplo a seguir é usado para obter a lista de canais em uma equipe:

public class MyBot : TeamsActivityHandler
{
    // Override this in a derived class to provide logic specific to Message activities.
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Returns a list of channels in a Team. This only works in team scoped conversations.
        IEnumerable<ChannelInfo> channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"The channel count is: {channels.Count()}");
    }
}

Exemplo de código

Para obter exemplos de trabalho completos que demonstram a funcionalidade, veja os seguintes exemplos do Teams para o Bot Framework:

Nome de exemplo Descrição .NET Node.js Python Manifesto
Bot de conversas do Teams Esta aplicação demonstra eventos de conversação de bots, suportando Cartões Ajustáveis, recibos de leitura e eventos de atualização de mensagens. Inclui suporte de leitura envolvente para acessibilidade. View View View View
Autenticação com OAuthPrompt Esta aplicação de exemplo demonstra como um Bot pode utilizar a autenticação do Teams. View View View View
Carregamento de ficheiros do Teams Este exemplo de bot para o Teams demonstra as capacidades de carregamento de ficheiros com o Bot Framework v4, permitindo que os utilizadores carreguem ficheiros e vejam imagens inline em chats. View View View View
Caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x) Esta aplicação de exemplo demonstra como utilizar caixas de diálogo (referidas como módulos de tarefas no TeamsJS v1.x) com o Bot Framework v4 View View View View
Iniciar um novo thread num canal Esta aplicação demonstra como iniciar um thread de conversação num canal específico do Teams com o Bot Framework v4. View View View View
Localização de aplicações do Teams Este exemplo demonstra como implementar a localização para aplicações do Microsoft Teams com Bots e Separadores. View View NA View

Próxima etapa

Enviar e receber arquivos usando o bot

Confira também

  • Last updated on