Cambios en la API del bot de Teams para capturar miembros del equipo o chat

  • Artículo

Nota:

Se inició el proceso de desuso de las API TeamsInfo.getMembers y TeamsInfo.GetMembersAsync. Inicialmente, están muy limitadas a cinco solicitudes por minuto y devuelven un máximo de 10 000 miembros por equipo. Como resultado, no se devuelve la lista completa a medida que aumenta el tamaño del equipo. Debe actualizar a la versión 4.10 o posterior del SDK de Bot Framework y cambiar a los puntos de conexión de API paginada o a la API de usuario único TeamsInfo.GetMemberAsync. Esto también se aplica al bot incluso si no usa directamente estas API, ya que los SDK más antiguos llaman a estas API durante los eventos de miembros agregados. Para ver la lista de los próximos cambios, consulte Cambios de API.

Actualmente, si desea recuperar información de uno o varios miembros de un chat o equipo, puede usar las API TeamsInfo.GetMembersAsync de bot de Microsoft Teams para C# o TeamsInfo.getMembers para TypeScript o Node.js API. Para obtener más información, vea obtener la lista o el perfil de usuario.

Estas API tienen las siguientes deficiencias:

  • Para equipos grandes, el rendimiento es deficiente y los tiempos de espera son más probables: el tamaño máximo del equipo ha aumentado considerablemente desde que Teams se lanzó a principios de 2017. Como GetMembersAsync o getMembers devuelve toda la lista de miembros, la llamada API tarda mucho tiempo en devolverse para equipos grandes y es habitual que la llamada agote el tiempo de espera y tenga que intentarlo de nuevo.
  • Obtener los detalles del perfil de un solo usuario es difícil: para obtener la información de perfil de un único usuario, tiene que recuperar toda la lista de miembros y, a continuación, buscar la que desee. Hay una función auxiliar en el SDK de Bot Framework para simplificarla, pero no es eficaz.

Con la introducción de los equipos de toda la organización, hay un requisito para alinear mejor estas API con los controles de privacidad de Microsoft 365. Los bots usados en equipos grandes pueden recuperar información de perfil básica similar al permiso User.ReadBasic.All de Microsoft Graph. Los administradores de cuentas empresariales tienen un gran control sobre qué aplicaciones y bots se pueden usar en su cuenta empresarial, pero esta configuración es diferente de Microsoft Graph.

El código siguiente proporciona una representación JSON de ejemplo de lo que devuelven las API de bot de 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"
}]

Cambios en la API

Estos son los próximos cambios en la API:

  • Se crea una nueva API TeamsInfo.GetPagedMembersAsync para recuperar la información de perfil de los miembros de un chat o equipo. Esta API ya está disponible con el SDK de Bot Framework versión 4.8 o posterior. Para el desarrollo en todas las demás versiones, use el método GetConversationPagedMembers.

Nota:

Actualice a la versión más reciente del SDK de Microsoft Bot Framework como se indica a continuación:

  • SDK de Bot Framework v3: actualización a la versión 3.30.2 o posterior.
  • SDK de Bot Framework v4: actualización a la versión 4.8 o posterior.

  • Se crea una nueva API TeamsInfo.GetMemberAsync para recuperar la información de perfil de un solo usuario. Toma el identificador del equipo o chat y un UPN que es userPrincipalName, Microsoft Entra idobjectId. de objeto o el identificador id de usuario de Teams como parámetros y devuelve la información del perfil de ese usuario.

    Nota:

    objectId se cambia a aadObjectId para que coincida con lo que se llama en el objeto Activity de un mensaje Bot Framework. La nueva API está disponible con la versión 4.8 o posterior del SDK de Bot Framework. También está disponible en la extensión del SDK de Bot Framework 3.x de Teams. Mientras tanto, puede usar el punto de conexión de REST.

  • TeamsInfo.GetMembersAsync en C# y TeamsInfo.getMembers en TypeScript o Node.js están en desuso formalmente. Una vez que la nueva API está disponible, debe actualizar los bots para usarla. Esto también se aplica a la API REST subyacente que estas API usan.

  • A finales de 2022, los bots no podrán recuperar proactivamente las propiedades userPrincipalName o email para los miembros de un chat o equipo. Los bots deben usar las API de Graph para recuperar la información necesaria. La nueva API GetConversationPagedMembers no podrá devolver las propiedades userPrincipalName y email a finales de 2022.

    Nota:

    Se recomienda usar el Graph API con un token de acceso para recuperar información.

Vea también