Modifications apportées aux API de robots teams pour la récupération des membres de l’équipe/conversationChanges to Teams Bot APIs for Fetching Team/Chat Members

Actuellement, les développeurs de robots qui souhaitent récupérer des informations pour un ou plusieurs membres d’une conversation ou d’une équipe utilisent les API Microsoft teams bot TeamsInfo.GetMembersAsync (pour C#) ou TeamsInfo.getMembers (pour la machine à écrire/Node.js) (documentée ici).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/Node.js) APIs (documented here). Ces API présentent aujourd’hui plusieurs lacunes :These APIs have several shortcomings today:

  • Pour les grandes équipes, les performances sont médiocres et les délais d’attente sont plus probables.For large teams, performance is poor and timeouts are more likely. La taille maximale de l’équipe a augmenté considérablement depuis la publication de Microsoft teams en début de 2017.The maximum team size has grown considerably since Microsoft Teams was released in early 2017. Étant donné que GetMembersAsync / getMembers renvoie la liste des membres dans son intégralité, l’appel de l’API prend beaucoup de temps pour être renvoyé pour les grandes équipes et n’est pas rare pour l’appel au délai d’expiration et vous devez recommencer.Since GetMembersAsync/getMembers returns the entire member list, it takes a long time for the API call to return for large teams, and it’s not uncommon for the call to time out and you have to try again.
  • L’obtention des détails du profil pour un seul utilisateur est lourde.Getting profile details for a single user is cumbersome. Pour obtenir les informations de profil d’un utilisateur, vous devez récupérer toute la liste de membres, puis Rechercher celle de votre choix.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. True, il y a une fonction d’assistance dans le kit de développement logiciel (SDK) de l’infrastructure pour faciliter sa création, mais sous les couvertures, elle n’est pas efficace.True, there’s a helper function in the Bot Framework SDK to make it simpler, but under the covers it’s not efficient.

Séparément, avec l’introduction de teams à l’échelle de l’organisation, nous avons réalisé qu’il était temps de mieux aligner ces API avec les contrôles de confidentialité Office 365 : les robots utilisés dans les grandes équipes sont en mesure de récupérer des informations de profil de base, qui sont semblables à l' User.ReadBasic.All autorisation Microsoft Graph.Separately, with the introduction of org-wide teams, we realized it was time to better align these APIs with Office 365 privacy controls: bots used in large teams are able to retrieve basic profile information, which is similar to the User.ReadBasic.All Microsoft Graph permission. Les administrateurs clients ont beaucoup de contrôle sur les applications et les robots pouvant être utilisés dans leur client, mais ces paramètres diffèrent de ceux qui régissent 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 than the ones governing Microsoft Graph.

Voici un exemple de représentation JSON de ce qui est renvoyé par ces API dès aujourd’hui.Here’s a sample JSON representation of what’s returned by these APIs today. Voici quelques-uns des champs ci-dessous.I’ll refer to some of the fields below.

[{
    "id": "29:1GcS4EyB_oSI8A88XmWBN7NJFyMqe3QGnJdgLfFGkJnVelzRGos0bPbpsfJjcbAD22bmKc4GMbrY2g4JDrrA8vM06X1-cHHle4zOE6U4ttcc",
    "objectId": "9d3e08f9-a7ae-43aa-a4d3-de3f319a8a9c",
    "givenName": "Larry",
    "surname": "Brown",
    "email": "Larry.Brown@fabrikam.com",
    "userPrincipalName": "labrown@fabrikam.com"
}, {
    "id": "29:1bSnHZ7Js2STWrgk6ScEErLk1Lp2zQuD5H2qQ960rtvstKp8tKLl-3r8b6DoW0QxZimuTxk_kupZ1DBMpvIQQUAZL-PNj0EORDvRZXy8kvWk",
    "objectId": "76b0b09f-d410-48fd-993e-84da521a597b",
    "givenName": "John",
    "surname": "Patterson",
    "email": "johnp@fabrikam.com",
    "userPrincipalName": "johnp@fabrikam.com"
}, {
    "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"
}]

Modifications de l’APIAPI Changes

Voici les modifications d’API à venir :Here are the upcoming API changes:

  • Nous avons créé une nouvelle API TeamsInfo.GetPagedMembersAsync pour récupérer des informations de profil pour les membres d’une conversation/équipe.We've created a new API TeamsInfo.GetPagedMembersAsync for retrieving profile information for members of a chat/team. Cette API est désormais disponible avec le kit de développement logiciel (SDK) de robot Framework 4,8.This API is now available with the Bot Framework 4.8 SDK. Pour le développement dans toutes les autres versions, utilisez la GetConversationPagedMembers méthode.For development in all other versions use the GetConversationPagedMembers method. Remarque: dans la version 3 ou v4, la meilleure mesure consiste à effectuer une mise à niveau vers la version la plus récente (3.30.2 ou 4,8, respectivement).Note: In either v3 or v4, the best action is to upgrade to the latest point release (3.30.2 or 4.8 respectively).
  • Nous avons créé une nouvelle API TeamsInfo.GetMemberAsync pour extraire les informations de profil pour un utilisateur unique.We've created a new API TeamsInfo.GetMemberAsync for retrieving the profile information for a single user. Il prend l’ID de l’équipe/conversation et un UPN ( userPrincipalName , voir ci-dessus), Azure Active Directory Object ID ( objectId , voir ci-dessus) ou l’ID utilisateur Teams ( id voir ci-dessus) comme paramètres et renvoie les informations de profil de cet utilisateur.It takes the ID of the team/chat and a UPN (userPrincipalName, see above), Azure Active Directory Object ID (objectId, see above), or the Teams user ID (id, see above) as parameters and returns the profile information for that user. Remarque: nous modifions objectId pour qu' aadObjectId il corresponde à ce qu’il est appelé dans l' Activity objet d’un message de l’infrastructure bot.Note: We're changing objectId to aadObjectId to match what it's called in the Activity object of a Bot Framework message. La nouvelle API est disponible avec la version 4,8 du kit de développement logiciel (SDK) de l’infrastructure bot.The new API is available with version 4.8 of the Bot Framework SDK. Il sera bientôt disponible dans l’infrastructure de l’extension du kit de développement logiciel (SDK) teams 3. x. en attendant, vous pouvez utiliser le point de terminaison Rest .It will soon be available in the Teams SDK extension Bot Framework 3.x as well; meanwhile you can use the REST endpoint.
  • TeamsInfo.GetMembersAsync(C#) et TeamsInfo.getMembers (machine à écrire/Node.js) est explicitement déconseillée et cessera de fonctionner en fin de 2021.TeamsInfo.GetMembersAsync (C#) and TeamsInfo.getMembers (TypeScript/Node.js) is formally deprecated and will stop working in late 2021. Nous annoncerons un calendrier spécifique en mai 2020 en fonction des commentaires des développeurs.We'll announce a specific timetable in May 2020, based on feedback from developers. Une fois la nouvelle API paginée disponible, les développeurs doivent mettre à jour leurs robots pour l’utiliser.Once the new paged API is available, developers should update their bots to use it. (Ceci s’applique également à l' API REST sous-jacente utilisée par ces API.)(This also applies to the underlying REST API these APIs use.)
  • En fin de 2021, les robots ne pourront pas récupérer de façon proactive les userPrincipalName email Propriétés ou pour les membres d’une équipe de conversation et devront utiliser Microsoft Graph pour les récupérer.By late 2021, bots will not be able to proactively retrieve the userPrincipalName or email properties for members of a chat/team and will need to use Microsoft Graph to retrieve them. Plus précisément userPrincipalName , email les propriétés ne seront pas renvoyées à partir de la nouvelle API à partir du GetConversationPagedMembers 2021.Specifically, userPrincipalName and email properties won't be returned from the new GetConversationPagedMembers API starting in late 2021. Les robots doivent utiliser Microsoft Graph avec un jeton d’accès pour récupérer ces informations.Bots will have to use Microsoft Graph with an access token to retrieve this information. Il s’agit évidemment d’une modification majeure : nous devons permettre aux robots d’obtenir un jeton d’accès plus facilement, et nous devons rationaliser et simplifier le processus de consentement de l’utilisateur final.This is obviously a major change: We must make it easier for bots to get an access token, and we must streamline and simplify the end-user consent process.

Commentaires et informations supplémentairesFeedback and More Information

Nous allons utiliser cette page pour fournir des informations à jour sur ces modifications.We'll use this page for providing up to date information on these changes. Si vous avez des questions, utilisez le commentaire « envoyer des commentaires > sur cette page » dans la section Commentaires ci-dessous.If you have questions, use the "Send feedback > on this page" in the Feedback section below.