Alterações na API de bot do Teams para buscar membros de equipe ou chatTeams bot API changes to fetch team or chat members

Observação

O processo de deprecation para TeamsInfo.getMembers TeamsInfo.GetMembersAsync e APIs foi iniciado.The deprecation process for TeamsInfo.getMembers and TeamsInfo.GetMembersAsync APIs have started. Inicialmente, elas são fortemente aceleradas para cinco solicitações por minuto e retornam um máximo de 10 mil membros por equipe.Initially, they are heavily throttled to five requests per minute and return a maximum of 10K members per team. Isso resulta na lista completa não sendo retornada à medida que o tamanho da equipe aumenta.This results in the full roster not being returned as team size increases. Você deve atualizar para a versão 4.10 ou superior do SDK da Estrutura de Bot e alternar para os pontos de extremidade da API paginada ou para a API de usuário TeamsInfo.GetMemberAsync único.You must update to version 4.10 or higher of the Bot Framework SDK and switch to the paginated API endpoints, or the TeamsInfo.GetMemberAsync single user API. Isso também se aplica ao bot mesmo que você não use essas APIs diretamente, pois os SDKs mais antigos chamam essas APIs durante eventos membersAdded.This also applies to your bot even if you are not directly using these APIs, as older SDKs call these APIs during membersAdded events. Para exibir a lista de alterações futuras, consulte ALTERAÇÕES da API.To view the list of upcoming changes, see API changes.

Atualmente, os desenvolvedores de bot que querem recuperar informações para um ou mais membros de um chat ou equipe usam as APIs de bot do Microsoft Teams para C# ou para TeamsInfo.GetMembersAsync TeamsInfo.getMembers APIs TypeScript ou Node.js.Currently, bot developers who want 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 or Node.js APIs. Para obter mais informações, consulte fetch roster or user profile.For more information, see fetch roster or user profile. Essas APIs têm várias deficiências.These APIs have several shortcomings.

Atualmente, se você deseja recuperar informações para um ou mais membros de um chat ou equipe, pode usar as APIs de bot do Microsoft Teams para C# ou para TYPEScript ou TeamsInfo.GetMembersAsync TeamsInfo.getMembers apIs Node.js.Currently, if you want to retrieve information for one or more members of a chat or team, you can use the Microsoft Teams bot APIs TeamsInfo.GetMembersAsync for C# or TeamsInfo.getMembers for TypeScript or Node.js APIs. Essas APIs têm as seguintes deficiências:These APIs have the following shortcomings:

  • Para equipes grandes, o desempenho é ruim e os tempos limite são mais prováveis: o tamanho máximo da equipe aumentou consideravelmente desde que o Teams foi lançado no início de 2017.For large teams, performance is poor and timeouts are more likely: The maximum team size has grown considerably since Teams was released in early 2017. Como ou retorna toda a lista de membros, leva muito tempo para a chamada da API retornar para equipes grandes, e é comum que a chamada tenha tempo de espera e você precisa GetMembersAsync getMembers tentar novamente.As GetMembersAsync or getMembers returns the entire member list, it takes a long time for the API call to return for large teams, and it is common for the call to time out and you have to try again.
  • Obter detalhes de perfil para 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 o que você deseja.Getting profile details for a single user is difficult: To get the profile information for a single user, you have to retrieve the entire member list and then search for the one you want. Há uma função auxiliar no SDK da Estrutura de Bots para torná-lo mais simples, mas não é eficiente.There is a helper function in the Bot Framework SDK to make it simpler, but it is not efficient.

Com a introdução de equipes de toda a organização, há um requisito para alinhar melhor essas APIs com controles de privacidade do Office 365.With the introduction of organization wide teams, there is a requirement to better align these APIs with Office 365 privacy controls. Bots usados em equipes grandes são capazes de recuperar informações básicas de perfil semelhantes à User.ReadBasic.All permissão do Microsoft Graph.Bots used in large teams are able to retrieve basic profile information similar to the User.ReadBasic.All Microsoft Graph permission. Os administradores de locatários têm um grande controle sobre quais aplicativos e bots podem ser usados em seu locatário, mas essas configurações são diferentes do Microsoft Graph.Tenant administrators have a great deal of control over which apps and bots can be used in their tenant, but these settings are different from Microsoft Graph.

O código a seguir fornece uma representação JSON de exemplo do que é retornado pelas APIs de bot do Teams:The following code provides a sample JSON representation of what is returned by Teams bot APIs:

[{
    "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 APIAPI Changes

A seguir estão as próximas alterações na API:Following are the upcoming API changes:

  • Uma nova API é criada TeamsInfo.GetPagedMembersAsync para recuperar informações de perfil para membros de um chat ou equipe.A new API is created TeamsInfo.GetPagedMembersAsync for retrieving profile information for members of a chat or team. Essa API agora está disponível com o SDK da Estrutura de Bot 4.8.This API is now available with the Bot Framework 4.8 SDK. Para desenvolvimento em todas as outras versões, use o GetConversationPagedMembers método.For development in all other versions, use the GetConversationPagedMembers method.

    Observação

    Em v3 ou v4, a melhor ação é atualizar para a versão de ponto mais recente que é 3.30.2 ou 4.8 respectivamente.In either v3 or v4, the best action is to upgrade to the latest point release that is 3.30.2 or 4.8 respectively.

  • Uma nova API é criada TeamsInfo.GetMemberAsync para recuperar as informações de perfil de um único usuário.A new API is created TeamsInfo.GetMemberAsync for retrieving the profile information for a single user. Ele pega a ID da equipe ou chat e um UPN que é , Azure Active Directory Object ID , ou a ID do usuário do Teams como parâmetros e retorna as informações de perfil para esse userPrincipalName objectId id usuário.It takes the ID of the team or chat and a UPN that is userPrincipalName, Azure Active Directory Object ID objectId, or the Teams user ID id as parameters and returns the profile information for that user.

    Observação

    objectId é alterado para aadObjectId corresponder ao que é chamado no objeto de uma mensagem da Estrutura de Activity Bot.objectId is changed to aadObjectId to match what is called in the Activity object of a Bot Framework message. A nova API está disponível com a versão 4.8 do SDK da Estrutura de Bots.The new API is available with version 4.8 of the Bot Framework SDK. Ele também está disponível na extensão SDK do Teams Bot Framework 3.x.It is also available in the Teams SDK extension Bot Framework 3.x. Enquanto isso, você pode usar o ponto de extremidade REST.Meanwhile, you can use the REST endpoint.

  • TeamsInfo.GetMembersAsync no C# e TeamsInfo.getMembers em TypeScript ou Node.js está formalmente preterido.TeamsInfo.GetMembersAsync in C# and TeamsInfo.getMembers in TypeScript or Node.js is formally deprecated. Depois que a nova API está disponível, você deve atualizar seus bots para usá-la.Once the new API is available, you must update your bots to use it. Isso também se aplica à API REST subjacente que essas APIs usam.This also applies to the underlying REST API that these APIs use.

  • Até o final de 2021, os bots não podem recuperar proativamente as propriedades ou para membros de um userPrincipalName email chat ou equipe.By late 2021, bots cannot proactively retrieve the userPrincipalName or email properties for members of a chat or team. Os bots devem usar o Graph para recuperá-los.Bots must use Graph to retrieve them. As userPrincipalName propriedades e não são email retornadas da nova API a partir do GetConversationPagedMembers final de 2021.The userPrincipalName and email properties are not returned from the new GetConversationPagedMembers API starting in late 2021. Os bots têm que usar o Graph com um token de acesso para recuperar informações.Bots have to use Graph with an access token to retrieve information. Deve ser mais fácil para os bots obterem um token de acesso e simplificarem e simplificarem o processo de consentimento do usuário final.It must be made easier for bots to get an access token and streamline and simplify the end-user consent process.