Alterações na API do bot do Teams para buscar membros da equipe ou chat

Observação

O processo de descontinuação das APIs TeamsInfo.getMembers e TeamsInfo.GetMembersAsync foi iniciado. Inicialmente, eles são fortemente limitados a cinco solicitações por minuto e retornam no máximo 10 mil membros por equipe. Isto faz com que a lista completa não seja retornada à medida que o tamanho da equipe aumenta. Você deve atualizar para a versão 4.10 ou superior do SDK do Bot Framework e alternar para os pontos de extremidade da API paginada, ou para a API de usuário único TeamsInfo.GetMemberAsync. Isso também se aplica ao seu bot, mesmo que você não esteja usando diretamente essas APIs, pois os SDKs mais antigos chamam essas APIs durante os eventos de membersAdded. Para ver a lista de alterações futuras, consulte Alterações da API.

Atualmente, se você quiser recuperar informações para um ou mais membros de um chat ou equipe, poderá usar as APIsTeamsInfo.GetMembersAsync de bot do Microsoft Teams para C# ou TeamsInfo.getMembers para APIs typeScript ou Node.js. Para obter mais informações, consulte buscar a lista ou perfil do usuário.

Estas APIs têm as seguintes deficiências:

  • Para grandes equipes, o desempenho é ruim e os tempos limite são mais prováveis: o tamanho máximo da equipe cresceu consideravelmente desde que o Teams foi lançado no início de 2017. Como GetMembersAsync ou getMembers retorna toda a lista de membros, leva muito tempo para a chamada de API retornar para equipes grandes, e é comum que a chamada tenha um tempo limite e você tenha que tentar novamente.
  • Obter detalhes do perfil de um único usuário é difícil: para obter as informações de perfil de um único usuário, você precisa recuperar toda a lista de membros e, em seguida, pesquisar a que deseja. Há uma função auxiliar no SDK do Bot Framework para torná-la mais simples, mas não é eficiente.

Com a introdução de equipes de toda a organização, há um requisito para alinhar melhor essas APIs com Office 365 controles de privacidade. Os bots usados em grandes equipes podem recuperar informações básicas do perfil semelhantes à permissão do User.ReadBasic.All Microsoft Graph. Os administradores de locatários têm um grande controle sobre quais aplicativos e bots podem ser usados nos seus locatários, mas essas configurações são diferentes do Microsoft Graph.

O código a seguir fornece um exemplo de representação JSON do que é retornado pelas APIs de bot do Teams:

[{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "name": "Anon1 (Guest)",
    "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
 "userRole": "anonymous"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "johnp@fabrikam.com",
    "userPrincipalName": "johnp@fabrikam.com",
    "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
 "userRole": "user"
}, {
    "id": "29:1URzNQM1x1PNMr1D7L5_lFe6qF6gEfAbkdG8_BUxOW2mTKryQqEZtBTqDt10-MghkzjYDuUj4KG6nvg5lFAyjOLiGJ4jzhb99WrnI7XKriCs",
    "objectId": "6b7b3b2a-2c4b-4175-8582-41c9e685c1b5",
    "givenName": "Rick",
    "surname": "Stevens",
    "email": "Rick.Stevens@fabrikam.com",
    "userPrincipalName": "rstevens@fabrikam.com",
    "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47",
 "userRole": "user"
}]

Alterações na API

A seguir estão as próximas alterações na API:

  • Uma nova API foi criada TeamsInfo.GetPagedMembersAsync para recuperar as informações de perfil de membros de um chat ou equipe. Esta API agora está disponível com o SDK do Bot Framework versão 4.8 ou posterior. Para o desenvolvimento em todas as outras versões, utilize o método GetConversationPagedMembers.

    Observação

    Na v3 ou na v4, a melhor ação é atualizar para a versão de ponto mais recente que é 3.30.2 ou 4.8 ou posterior, respectivamente.

  • Uma nova API foi criada TeamsInfo.GetMemberAsync para recuperar as informações de perfil de um único usuário. Ele usa a ID da equipe ou do chat e uma UPN que é userPrincipalName, a ID de objeto do Microsoft Azure Active Directory (Microsoft Azure AD) objectId ou a ID do usuário do Teams id como parâmetros e retorna as informações de perfil desse usuário.

    Observação

    objectId é alterado para aadObjectId para corresponder ao que é chamado no objeto Activity de uma mensagem do Bot Framework. A nova API está disponível com a versão 4.8 ou posterior do SDK do Bot Framework. Ele também está disponível na extensão do SDK do Teams do Bot Framework 3.x. Enquanto isso, você pode utilizar o ponto de extremidade REST.

  • TeamsInfo.GetMembersAsync no C# e TeamsInfo.getMembers no TypeScript ou Node.js estão formalmente preteridos. Uma vez que a nova API esteja disponível, você deve atualizar seus bots para utilizá-la. Isso também se aplica à API REST subjacente que essas APIs usam.

  • Até o final de 2022, os bots não poderão recuperar proativamente as propriedades userPrincipalName ou email para os membros de um chat ou equipe. Os bots devem usar as APIs do Graph para recuperar as informações necessárias. A nova API GetConversationPagedMembers não pode retornar as propriedades userPrincipalName e email do final de 2022.

    Observação

    Recomendamos que você use o API do Graph com um token de acesso para recuperar informações.