Partilhar via

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

  • Artigo

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.

Se quiser obter informações para um ou mais membros de uma conversa ou equipa, pode utilizar as APIsTeamsInfo.GetMembersAsync de bot do Microsoft Teams para C# ou TeamsInfo.getMembers para TypeScript ou Node.js APIs. Para obter mais informações, consulte buscar a lista ou perfil do usuário.

Estas APIs têm as seguintes deficiências:

  • Para equipas grandes, o desempenho é fraco e os tempos limite são mais prováveis: o tamanho máximo da equipa cresceu consideravelmente desde que o Teams foi lançado. Como GetMembersAsync ou getMembers devolve toda a lista de membros, a chamada à API demora muito tempo a ser devolvida para equipas grandes e é comum que a chamada exceda o tempo limite e tem de tentar novamente.
  • Obter detalhes de perfil para um único utilizador é difícil: para obter as informações de perfil de um único utilizador, tem de obter toda a lista de membros e, em seguida, procurar a que pretende. Existe uma função auxiliar no SDK do Bot Framework para simplificar, mas não é eficiente.

Com a introdução de equipas de toda a organização, é necessário alinhar melhor estas APIs com os controlos de privacidade do Microsoft 365. 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 à 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

Atualize para a versão mais recente do SDK do Microsoft Bot Framework da seguinte forma:

  • SDK do Bot Framework v3: atualize para a versão 3.30.2 ou posterior.
  • SDK do Bot Framework v4: atualize para a versão 4.8 ou posterior.

  • Uma nova API foi criada TeamsInfo.GetMemberAsync para recuperar as informações de perfil de um único usuário. Utiliza o ID da equipa ou chat e um UPN que é userPrincipalName, Microsoft Entra Object ID objectIdou o ID id de utilizador do Teams como parâmetros e devolve as informações de perfil desse utilizador.

    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.

  • Os bots não podem obter proativamente as userPrincipalName propriedades ou email para os membros de uma conversa ou equipa. Os bots têm de utilizar as Graph APIs para obter as informações necessárias. A nova GetConversationPagedMembers API não pode devolver as userPrincipalName propriedades e email .

    Observação

    Recomendamos que utilize a Graph API com um token de acesso para obter informações.

Confira também