Obtenha o contexto específico do Teams para seu bot

  • Artigo
  • 9 minutos para o fim da leitura

Importante

Os exemplos de código nesta seção são baseados na versão 4.6 e versões posteriores do SDK do Bot Framework. Se você estiver procurando documentação para versões anteriores, consulte a seção bots – v3 SDK na pasta SDKs Herdados 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

Seu bot pode consultar a lista de membros e seus perfis de usuário básicos, incluindo IDs de usuário do Teams e informações do Microsoft Azure Active Directory (Azure AD), como nome e objectId. Você pode usar essas informações para correlacionar identidades de usuários. Por exemplo, para verificar se um usuário conectado a uma guia por meio de Azure AD credenciais é um membro da equipe. 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 em uma equipe e em um canal.
  • Não há suporte para paginação em chats. Para chats, toda a lista sempre é retornada.

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. Atualmente, para recuperar informações de um ou mais membros de um chat ou equipe, use as APIs de bot do Microsoft Teams TeamsInfo.GetMembersAsync para C# ou TeamsInfo.getMembers para APIs TypeScript.

Obter detalhes de membro único

Você também pode recuperar os detalhes de um usuário específico usando sua ID de usuário, UPN ou ID de Objeto do Azure Active Directory 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. Atualmente, para recuperar informações de uma equipe, use as APIs de bot do Teams TeamsInfo.GetMemberDetailsAsync para C# ou TeamsInfo.getTeamDetails para TypeScript.

Obter detalhes da equipe

Quando instalado em uma equipe, seu bot pode consultar metadados sobre essa equipe, incluindo a ID de grupo do Azure Active Directory.

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. Atualmente, para recuperar informações de uma lista de canais em uma equipe, use as APIs de bot do Teams TeamsInfo.GetTeamChannelsAsync 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, consulte os seguintes exemplos do Teams para Bot Framework:

Nome de exemplo Descrição .NET Node.js Python Manifesto
Bot de conversas do Teams Este exemplo mostra como usar diferentes eventos de conversa de bot disponíveis na estrutura do bot v4 para escopo pessoal e de equipes. View View View Exibir
Autenticação com OAuthPrompt Este exemplo mostra autenticação e mensagens básicas no Bot Framework v4. View View View Exibir
Upload de arquivo do Teams Este exemplo mostra como usar arquivos com um bot em uma conversa individual. View View View Exibir
Módulo de tarefa Este exemplo mostra como usar um módulo de tarefa e valores de cartões nele para uma extensão de mensagem. View View View View
Iniciar novo tópico em um canal Este exemplo mostra como usar um novo thread em um canal usando bot. View View View Exibir
Localização do aplicativo Teams Este exemplo mostra como usar a localização do aplicativo teams usando bot e guia. View View NA Exibir

Próxima etapa

Enviar e receber arquivos usando o bot

Confira também