Compartilhar via

Obtenha o contexto específico do Teams para seu bot

  • Artigo

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()}");
    }
}

Exemplos de bot do Teams

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 Este exemplo mostra como utilizar diferentes eventos de conversação de bot disponíveis no bot framework v4 para o âmbito pessoal e de equipas. View View View View
Autenticação com OAuthPrompt Este exemplo mostra a autenticação e as mensagens básicas no Bot Framework v4. View View View View
Carregamento de ficheiros do Teams Este exemplo mostra como utilizar ficheiros com um bot numa conversação um-para-um. View View View View
Caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x) Este exemplo mostra como utilizar uma caixa de diálogo e valores de cartões na mesma para uma extensão de mensagem. View View View View
Iniciar um novo thread num canal Este exemplo mostra como utilizar um novo thread num canal com o bot. View View View View
Localização de aplicações do Teams Este exemplo mostra como utilizar a localização de aplicações do Teams com o bot e o separador. View View NA View

Próxima etapa

Enviar e receber arquivos usando o bot

Confira também