Obter contexto específico do Teams para seu botGet Teams specific context for your bot

Importante

Os exemplos de código nesta seção são baseados na versão 4.6 e versões posteriores do SDK da Estrutura de Bot.The code samples in this section are based on version 4.6 and later versions of the Bot Framework SDK. Se você estiver procurando documentação para versões anteriores, consulte a seção bots - V3 SDK na pasta Recursos da documentação.If you are looking for documentation for earlier versions, see the bots - v3 SDK section in the Resources folder of the documentation.

Um bot pode acessar dados de contexto adicionais sobre uma equipe ou chat em que está instalado.A bot can access additional context data about a team or chat where it is installed. Essas informações podem ser usadas para enriquecer a funcionalidade do bot e fornecer uma experiência mais personalizada.This information can be used to enrich the bot's functionality and provide a more personalized experience.

Buscar a lista ou o perfil de usuárioFetch the roster or user profile

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 Azure Active Directory (AAD), como nome e objectId.Your bot can query for the list of members and their basic user profiles, including Teams user IDs and Azure Active Directory (AAD) information, such as name and objectId. Você pode usar essas informações para correlacionar identidades de usuário.You can use this information to correlate user identities. Por exemplo, para verificar se um usuário conectado a uma guia por meio de credenciais do AAD é membro da equipe.For example, to check whether a user logged into a tab through AAD credentials, is a member of the team. Para obter membros da conversa, o tamanho mínimo ou máximo da página depende da implementação.For get conversation members, minimum or maximum page size depends on the implementation. O tamanho da página menor que 50, são tratados como 50 e maiores que 500 são limitados a 500.Page size less than 50, are treated as 50, and greater than 500, are capped at 500. Mesmo que você use a versão não páginada, ela não é confiável em equipes grandes e não deve ser usada.Even if you use the non-paged version, it is unreliable in large teams and must not be used. Para obter mais informações, consulte changes to Teams Bot APIs for fetching team or chat members.For more information, see changes to Teams Bot APIs for fetching team or chat members.

O código de exemplo a seguir usa o ponto de extremidade pagedo para buscar a lista:The following sample code uses the paged endpoint for fetching the roster:

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

        do
        {
            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 o perfil de usuário, você pode obter detalhes de um único membro.After you fetch the roster or user profile, you can get details of a single member. Atualmente, para recuperar informações de um ou mais membros de um chat ou equipe, use as APIs de bot do Microsoft Teams para C# ou para TeamsInfo.GetMembersAsync TeamsInfo.getMembers APIs TypeScript.Currently, to retrieve information for one or more members of a chat or team, use the Microsoft Teams bot APIs TeamsInfo.GetMembersAsync for C# or TeamsInfo.getMembers for TypeScript APIs.

Obter detalhes de membro únicoGet single member details

Você também pode recuperar os detalhes de um usuário específico usando sua ID de usuário do Teams, UPN ou ID de objeto AAD.You can also retrieve the details of a particular user using their Teams user ID, UPN, or AAD Object ID.

O código de exemplo a seguir é usado para obter detalhes de membro único:The following sample code is used to get single member details:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        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.After you get details of a single member, you can get details of the team. Atualmente, para recuperar informações de uma equipe, use as APIs de bot do Microsoft Teams para C# TeamsInfo.GetMemberDetailsAsync TeamsInfo.getTeamDetails ou para TypeScript.Currently, to retrieve information for a team, use the Microsoft Teams bot APIs TeamsInfo.GetMemberDetailsAsync for C# or TeamsInfo.getTeamDetails for TypeScript.

Obter detalhes da equipeGet team's details

Quando instalado em uma equipe, seu bot pode consultar metadados sobre essa equipe, incluindo a ID do grupo AAD.When installed in a team, your bot can query for metadata about that team including the AAD group ID.

O código de exemplo a seguir é usado para obter os detalhes da equipe:The following sample code is used to get team's details:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        TeamDetails teamDetails = await TeamsInfo.GetTeamDetailsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);
        if (teamDetails != null) {
            await turnContext.SendActivityAsync($"The groupId is: {teamDetails.AadGroupId}");
        }
        else {
            await turnContext.SendActivityAsync($"Message did not come from a channel in a team.");
        }
    }
}

Depois de obter detalhes da equipe, você pode obter a lista de canais em uma equipe.After you get details of the team, you can get the list of channels in a team. Atualmente, para recuperar informações de uma lista de canais em uma equipe, use as APIs de bot do Microsoft Teams para C# ou para TeamsInfo.GetTeamChannelsAsync TeamsInfo.getTeamChannels APIs TypeScript.Currently, to retrieve information for a list of channels in a team, use the Microsoft Teams bot APIs TeamsInfo.GetTeamChannelsAsync for C# or TeamsInfo.getTeamChannels for TypeScript APIs.

Obter a lista de canais em uma equipeGet the list of channels in a team

Seu bot pode consultar a lista de canais em uma equipe.Your bot can query the list of channels in a team.

Observação

  • O nome do canal Geral padrão é retornado para null permitir a localização.The name of the default General channel is returned as null to allow for localization.
  • A ID do canal para o canal Geral sempre corresponde à ID da equipe.The channel ID for the General channel always matches the team ID.

O código de exemplo a seguir é usado para obter a lista de canais em uma equipe:The following sample code is used to get the list of channels in a team:

public class MyBot : TeamsActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        IEnumerable<ChannelInfo> channels = await TeamsInfo.GetTeamChannelsAsync(turnContext, turnContext.Activity.TeamsGetTeamInfo().Id, cancellationToken);

        await turnContext.SendActivityAsync($"The channel count is: {channels.Count()}");
    }
}

Exemplos de bot do TeamsTeams bot samples

Exemplo de códigoCode sample

Para amostras de trabalho completas que demonstram a funcionalidade, consulte os seguintes exemplos do Teams para Bot Framework:For complete working samples demonstrating the functionality, see the following Teams samples for Bot Framework:

AmostraSample DescriçãoDescription .NET.NET JavaScriptJavaScript PythonPython
Bot de conversas do TeamsTeams conversation bot Manipulação de eventos de mensagens e conversas.Messaging and conversation event handling. ViewView ViewView ViewView
Autenticação com OAuthPromptAuthentication with OAuthPrompt Autenticação e mensagens básicas no Bot Framework v4.Authentication and basic messaging in Bot Framework v4. ViewView ViewView ViewView
Carregamento de arquivo do TeamsTeams file upload Trocar arquivos com um bot em uma conversa um para um.Exchanging files with a bot in a one-to-one conversation. ViewView ViewView ViewView
Módulo de tarefaTask module Recuperar um módulo de tarefa e valores de cartões nele para uma extensão de mensagens.Retrieving a task module and values from cards in it for a messaging extension. ViewView ViewView ViewView
Iniciar novo thread em um canalStart new thread in a channel Criando um novo thread em um canal.Creating a new thread in a channel. ViewView ViewView ViewView

Próxima etapaNext step