Aplicaciones para canales compartidos y privados

Los canales compartidos y privados de Microsoft Teams permiten la colaboración flexible dentro de los equipos y entre organizaciones. Actualmente, las aplicaciones de bot y pestaña se admiten en canales compartidos y privados. Con esta actualización, puede experimentar varias ventajas:

• Canales compartidos: permite la comunicación sin problemas con miembros internos o externos, sin cambiar el contexto del usuario. Estos canales garantizan un control de acceso granular seguro y la sincronización de pertenencia en tiempo real.

• Canales privados: proporcione un espacio seguro para que los miembros del equipo seleccionados colaboren en contenido confidencial o confidencial, lo que garantiza la privacidad y las discusiones centradas en el equipo.

Descripción de los canales para la integración de aplicaciones

Los distintos canales determinan la visibilidad de la aplicación, el acceso del usuario y el comportamiento del almacenamiento de datos:

Funcionalidades entre canales

Este es un esquema de los diferentes canales y sus capacidades, en varios parámetros:

Descripción de cómo los distintos canales determinan la funcionalidad de la aplicación

Asegúrese de que entiende que los distintos canales determinan la funcionalidad de la aplicación, la pertenencia, el almacenamiento o la privacidad; de lo contrario, puede dar lugar a una funcionalidad rota o a una exposición de datos no intencionada:

• Uso de API de pertenencia específicas del canal

  No suponga que la pertenencia al equipo es igual a la pertenencia al canal. Solo los miembros que se agregan al canal pueden participar en canales compartidos y privados.

• Distinguir entre usuarios y roles

  Los miembros del canal pueden incluir usuarios, invitados o usuarios entre inquilinos (usuarios externos de otros inquilinos). Si la aplicación necesita distinguir entre varios usuarios para administrar el acceso, la visibilidad de los datos y la disponibilidad de características, debe validar los roles de usuario y los identificadores de inquilino antes de conceder permisos.

• No suponga que un solo sitio de SharePoint está vinculado a un equipo

  A diferencia de los canales estándar, que comparten el sitio de SharePoint con el equipo, los canales privados y compartidos tienen sus propios sitios de SharePoint. Use siempre la dirección URL correcta para cada canal, para evitar que falten archivos o errores de acceso no autorizados.

• Mantener los datos en el ámbito de los canales

  Agregue o publique datos entre canales solo cuando sea necesario para evitar pérdidas accidentales. Por ejemplo, las aplicaciones de análisis no deben incluir datos de canal privado en los informes de todo el equipo a menos que los permisos estén claramente definidos.

Volver a la parte superior

Habilitación de aplicaciones para canales compartidos y privados

La mayoría de las aplicaciones pueden admitir canales compartidos y privados con una actualización de manifiesto simple. En función de cualquiera de los escenarios siguientes, puede decidir el enfoque:

• Aplicaciones sin dependencia de parámetros especificados
• Aplicaciones que dependen de parámetros especificados

Aplicaciones sin dependencia de parámetros especificados

Si la aplicación no lo hace:

• Uso de la pertenencia al canal o al equipo para determinar la entrega de mensajes, la asignación de tareas o los permisos
• Acceso o administración de archivos almacenados en Teams o SharePoint
• Combinar o compartir datos entre varios canales o equipos
• Personalización de la experiencia en función de los usuarios (internos, invitados o miembros externos)

A continuación, solo necesita:

1. Agregar supportsChannelFeatures: tier1 al manifiesto de la aplicación
2. Comprobar el comportamiento esperado y probar la aplicación entre canales

No hay ninguna dependencia del acceso clásico y de administrador para supportsChannelFeatures: tier1.

Aplicaciones que dependen de parámetros especificados

Si la aplicación controla escenarios avanzados o depende de los parámetros especificados que aparecen en la sección Aplicaciones sin dependencia de los parámetros especificados , lea esta guía para conocer las actualizaciones de destino y los procedimientos recomendados. No vuelva a escribir el código.

Obtener contexto para canales compartidos y privados

Al cargar la experiencia del usuario en un canal compartido o privado, use los datos recibidos de la getContext llamada para canales compartidos o privados. La getContext llamada publica dos propiedades nuevas, hostTeamGroupID y hostTenantID, que se usan para recuperar la pertenencia al canal mediante las API de Microsoft Graph. Cada canal se crea dentro de un equipo host. Para obtener más información, vea Obtener contexto en canales compartidos y Obtener contexto para la pestaña para canales privados.

Administrar la pertenencia al canal

Use la allMembers API que administra y supervisa las pertenencias a canales en canales estándar, compartidos y privados. Mejora la precisión al reflejar correctamente los miembros directos e indirectos. Para obtener más información, vea Enumerar todos los miembros.

GET /teams/{team-id}/channels/{channel-id}/allMembers

Identificación de miembros

• Miembros directos: Usuarios que se agregan directamente al canal, incluidos los usuarios de otros inquilinos (entre inquilinos).
• Miembros indirectos: Usuarios que son miembros del equipo, con los que se comparte el canal, incluidos los equipos del mismo inquilino o entre inquilinos.

Puede identificar si un miembro de un canal compartido o privado es directo o indirecto comprobando la @microsoft.graph.originalSourceMembershipUrl anotación. Esta propiedad identifica el origen del acceso de un miembro a los canales:

Administración de la pertenencia indirecta entre canales

Puede administrar la pertenencia indirecta en canales mediante las siguientes API de Microsoft Graph:

• Use la allMembers API para recuperar todos los usuarios que son miembros de un canal específico.

  GET /teams/{team-id}/channels/{channel-id}/allMembers
  

• Use la doesUserHaveAccess API para determinar si el usuario se quita del canal y puede ver todos los accesos de usuario y los permisos pertinentes. Las aplicaciones con permisos de aplicación clásicos y permisos de RSC pueden usar esta API.

  GET /teams/{team-id}/channels/{channel-id}/doesUserHaveAccess(userId='@userid',tenantId='@TenantID',userPrincipalName='@UserPrincipalName')
  

• Use lasharedWithTeams API para enumerar todos los equipos con los que se comparte un canal.

  GET /teams/{team-id}/channels/{channel-id}/sharedWithTeams
  

• Use la allowedMembers API para recuperar usuarios de un equipo compartido que puedan acceder a un canal compartido.

  GET /teams/{team-id}/channels/{channel-id}/sharedWithTeams/{sharewithteamsId}/allowedMembers
  

  Nota:

  La allowedMembers API solo devuelve usuarios recién asociados y no se aplica a eventos no compartidos.

Volver a la parte superior

Obtención de notificaciones de aplicaciones para los cambios de pertenencia a grafos

Las aplicaciones instaladas en canales compartidos y privados reciben notificaciones cuando los usuarios se agregan o quitan de un equipo que comparte el canal.

Para recibir notificaciones de aplicaciones, debe:

1. Instale la aplicación en un equipo host y habilitela para el canal compartido o privado. Para obtener más información sobre cómo instalar la aplicación, consulte Instalación de la aplicación.
2. Cree una suscripción válida de notificación de cambios de Microsoft Graph para supervisar los cambios de pertenencia al equipo asociados y los eventos compartidos o no compartidos mediante las API admitidas.

Para recibir notificaciones de actualización de miembros directas e indirectas, debe incluir ambos parámetros de cadena de consulta al crear una suscripción. Si no se proporcionan las cadenas de consulta, la suscripción solo entrega notificaciones para las actualizaciones directas de miembros. Para obtener más información, consulte Acceso a la pertenencia al canal.

/teams/{team-id}/channels/getAllMembers?notifyOnIndirectMembershipUpdate=true&suppressNotificationWhenSharedUnsharedWithTeam=true

Esta suscripción permite a las aplicaciones supervisar los cambios de pertenencia en los canales y sus equipos asociados. Para obtener más información sobre cómo crear una suscripción de notificación de cambios de Microsoft Graph, consulte Creación de una suscripción.

Obtención de notificaciones de aplicaciones para los cambios de pertenencia a bots

El conversationUpdate evento se envía al bot cuando recibe notificaciones sobre las actualizaciones de pertenencia de los equipos donde se agrega. Para recibir notificaciones de actualización de miembros directas e indirectas, configure el bot con los siguientes requisitos previos:

1. Actualice el manifiesto de la aplicación. Agregar supportsChannelFeatures: tier1 para declarar la preparación de la aplicación.

2. Solicitar permiso de consentimiento Resource-Specific (RSC)

   La aplicación debe solicitar el siguiente permiso de RSC para acceder a la información de pertenencia al canal:

   {
   "authorization": {
   "permissions": {
     "resourceSpecific": [
       {
         "name": "ChannelMember.Read.Group",
         "type": "Application"
       }
     ]
   }
     }
   }
   

3. Asegúrese de que el bot se agrega en el canal compartido.

   Para recibir notificaciones de eventos de miembro, instale el bot en el nivel de equipo y permitirlo manualmente en el canal compartido.

   Este proceso garantiza que el bot está activo y autorizado para recibir notificaciones para los miembros directos e indirectos.

Administrar eventos agregados y quitados de miembros

Se envía un evento agregado de miembro al bot en los siguientes escenarios:

1. Cuando el bot, en sí mismo, se instala y se agrega a una conversación
2. Cuando se agrega un usuario a una conversación en la que está instalado el bot

Se envía un evento quitado de miembro al bot en los siguientes escenarios:

1. Cuando el bot, en sí mismo, se desinstala y se quita de una conversación.
2. Cuando se quita un usuario de una conversación en la que está instalado el bot.

Para obtener más información, consulte Eventos de conversación.

Si el bot está instalado en el equipo o canal, el SDK de Agentes recibe una conversationUpdate actividad a través del OnConversationUpdateActivityAsync método , cuando se agrega un canal compartido a otro equipo.

Cuando se agrega un nuevo miembro a un canal compartido, se llama al OnMembersAddedAsync método . Este método proporciona el contexto y los detalles del usuario que se agregó, lo que permite que el bot responda en consecuencia.

Los siguientes ejemplos del SDK de Agentes se aplican a eventos de adición y eliminación de miembros directos e indirectos.

Evento agregado de miembro

public async Task OnMembersAddedAsync(ITurnContext turnContext, AppState turnState, CancellationToken cancellationToken)
{
    var membersAdded = turnContext.Activity.MembersAdded;

    List<string> addedMembers = new List<string>();
    foreach (var member in membersAdded)
    {
        if (member.Id != turnContext.Activity.Recipient.Id)
        {
            addedMembers.Add($"Member {member.Name} (ID {member.Id}) added.");
        }
    }

    await ActivityUtils.SendAdaptiveCard(
        "Member Added",
        addedMembers,
        new List<object> { "membersAdded", membersAdded },
        turnContext,
        cancellationToken).ConfigureAwait(false);

Evento quitado de miembro

public async Task OnMembersRemovedAsync(ITurnContext turnContext, AppState turnState, CancellationToken cancellationToken)
{
    var membersRemoved = turnContext.Activity.MembersRemoved;

    List<string> removedMembers = new List<string>();
    foreach (var member in membersRemoved)
    {
        if (member.Id != turnContext.Activity.Recipient.Id)
        {
            removedMembers.Add($"Member {member.Name} (ID {member.Id}) removed.");
        }
    }

    await ActivityUtils.SendAdaptiveCard(
        "Member Removed",
        removedMembers,
        new List<object> { "membersRemoved", membersRemoved },
        turnContext,
        cancellationToken).ConfigureAwait(false);
}

Controlar los cambios de pertenencia masiva para el grafo

Si hay cambios en la pertenencia masiva, Teams frena las notificaciones de actualización de pertenencia individual cuando un canal se comparte o no se comparte con un equipo. Para reducir la sobrecarga de notificaciones durante las actualizaciones de pertenencia, como cuando se agrega o quita un canal compartido de un equipo con miles de miembros, use elsharedWithTeams recurso de suscripción:

/teams/{team-id}/channels/{channel-id}/sharedWithTeams

La sharedWithTeams suscripción envía una única notificación cuando un canal se comparte o no se comparte con un equipo. Evita miles de notificaciones por usuario y mejora el rendimiento de las aplicaciones que supervisan los cambios de pertenencia. Asegúrese de actualizar la lista de miembros del canal compartido mediante la API allMembers después de recibir una notificación de equipo compartida con o no compartida .

Validación del acceso de usuario para las actualizaciones de pertenencia a grafos

Cuando una aplicación recibe una notificación quitada de un miembro para una actualización de pertenencia indirecta, es importante comprobar si el usuario se quita del canal, especialmente porque el mismo usuario podría tener pertenencia directa e indirecta. Por ejemplo, si un usuario se quita de un equipo que comparte un canal, la aplicación debe confirmar si se revoca el acceso del usuario al canal compartido. Use la doesUserHaveAccess API para determinar si el usuario se quita del canal compartido. Consulte doesUserHaveAccess API para obtener más información sobre los accesos de usuario y los permisos pertinentes.

GET /teams/{team-id}/channels/{channel-id}/doesUserHaveAccess(userId='@userid',tenantId='@TenantID',userPrincipalName='@UserPrincipalName')

Cuando una aplicación recibe una notificación agregada de miembro para una actualización de pertenencia indirecta, vea la API allMembers para actualizar la lista de todos los miembros.

GET /teams/{team-id}/channels/{channel-id}/allMembers

Clasificación de miembros como inquilinos o fuera de inquilino

Puede clasificar miembros como inquilinos o fuera del inquilino comparando el valor "TenantId" del miembro o equipo con ownerTenantId el siguiente:

1. Obtenga el "TenantId" del miembro que desea comparar.

   GET /teams/{host-team-group-id}/channels/{channel-id}/allMembers
   

2. Llame a microsoftTeams.app.getContext() en la pestaña desde la biblioteca cliente de JavaScript de Teams. La llamada a getContext() devuelve el contexto del canal compartido, que contiene los detalles como displayName, membershipType, ownerGroupIdy ownerTenantId.

3. Compare el TenantId del miembro con la ownerTenantId propiedad y determine si el miembro es un inquilino dentro o fuera del inquilino.

Volver a la parte superior

Descripción de los permisos de aplicación en canales compartidos

Puede colaborar con miembros externos fuera de la organización mediante canales compartidos. Los permisos de aplicación en canales compartidos siguen la lista de aplicaciones del equipo host y la directiva de aplicación del inquilino del host.

Comprobación de la instalación del bot en un canal

Cuando se agrega un canal compartido a otro equipo, el SDK de Agentes recibe una conversationUpdate actividad a través del OnConversationUpdateActivityAsync método , solo si el bot está instalado en el equipo. No hay ninguna API dedicada para comprobar si la aplicación forma parte de un canal. Los bots pueden detectar cuándo se agrega la aplicación a un canal indirectamente.

Use este channelMemberAdded evento para desencadenar lógica específica de la aplicación, como:

• Envío de un mensaje de bienvenida
• Captura de la lista de canales
• Configuración de pestañas
• Inicio de trabajos programados

        protected override async Task OnConversationUpdateActivityAsync(
            ITurnContext<IConversationUpdateActivity> turnContext,
            CancellationToken cancellationToken)
        {
            var tcd = turnContext.Activity.GetChannelData<TeamsChannelData>();
            var eventType = tcd?.EventType?.ToLowerInvariant();

            var extended = turnContext.Activity.GetChannelData<SharedChannelChannelData>();

            var raw = turnContext.Activity.ChannelData as JObject
                      ?? (turnContext.Activity.ChannelData != null
                          ? JObject.FromObject(turnContext.Activity.ChannelData)
                          : new JObject());

            _logger.LogInformation("ConversationUpdate eventType={EventType}, channelId={ChannelId}, teamId={TeamId}",
                eventType, tcd?.Channel?.Id, tcd?.Team?.Id);

            switch (eventType)
            {
                case "channelshared":
                {
                    var hostTeam = extended?.Team; 
                    var sharedWith = extended?.SharedWithTeams ?? new List<TeamInfoEx>();

                    _logger.LogInformation("ChannelShared: hostTeam={HostTeamId}, sharedWithCount={Count}",
                        hostTeam?.Id, sharedWith.Count);

                    foreach (var team in sharedWith)
                    {
                        _logger.LogInformation("SharedWithTeam: id={Id}, name={Name}, aadGroupId={AadGroupId}, tenantId={TenantId}",
                            team.Id, team.Name, team.AadGroupId, team.TenantId);
                    }

                    await turnContext.SendActivityAsync(
                        MessageFactory.Text($" Channel shared with {sharedWith.Count} team(s)."),
                        cancellationToken);
                    break;
                }

                case "channelunshared":
                {
                    var unsharedFrom = extended?.UnsharedFromTeams ?? new List<TeamInfoEx>();

                    _logger.LogInformation("ChannelUnshared: unsharedFromCount={Count}", unsharedFrom.Count);

                    foreach (var team in unsharedFrom)
                    {
                        _logger.LogInformation("UnsharedFromTeam: id={Id}, name={Name}, aadGroupId={AadGroupId}, tenantId={TenantId}",
                            team.Id, team.Name, team.AadGroupId, team.TenantId);
                    }

                    await turnContext.SendActivityAsync(
                        MessageFactory.Text($" Channel unshared from {unsharedFrom.Count} team(s)."),
                        cancellationToken);
                    break;
                }

                default:
                    break;
            }

            await base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
        }

Autenticación de usuarios externos para acceder al contenido de la aplicación en SharePoint

Debe completar este paso cuando la aplicación almacena contenido en el sitio de SharePoint del inquilino que hospeda el canal y solicita un token de SharePoint.

Ahora, envíe el host tenantId guardado dentro tenantId del parámetro de getAuthToken llamada para permitir que los usuarios entre inquilinos accedan al contenido hospedado dentro del sitio de SharePoint conectado al canal compartido.

Identificación de usuarios invitados en canales mediante Graph API

Puede identificar si un miembro de un canal es un usuario invitado, invitado a su inquilino desde una organización externa, mediante roles la propiedad recibida para cada objeto en Lista de miembros de una respuesta de canal .

Para invitados, 'roles' = 'invitado'

Para recuperar con precisión todos los usuarios invitados de un canal, use la siguiente allMembers API:

GET /teams/{team-id}/channels/{channel-id}/allMembers

Esta API funciona en todos los canales estándar y otros canales y se recomienda para identificar de forma confiable a los miembros invitados.

Acceso a datos de SharePoint en canales compartidos y privados

Si va a compilar una aplicación con SharePoint Framework, debe usar el sitio de SharePoint Online (SPO) vinculado al canal compartido, no el vinculado al grupo de equipos host. Tanto los canales compartidos como los privados tienen su propio sitio de SPO que solo es accesible para los miembros de ese canal compartido o privado específico.

Use la API de invitación de Microsoft Graph para acceder a la biblioteca de documentos del sitio SPO vinculado a un canal compartido o privado.

Volver a la parte superior

Acceso al almacenamiento de SharePoint para archivos de canal mediante Graph API

Para acceder a la raíz de archivos de SharePoint de un canal, use la siguiente API:

GET /teams/{teamId}/channels/{channelId}/filesFolder

Esta API devuelve un objeto DriveItem para la raíz de archivos de ese canal. Para obtener más información, consulte archivos de canal.

Use las propiedades siguientes para todas las operaciones de archivo posteriores:

• parentReference.driveId: id. de unidad de SharePoint para el sitio del canal.
• itemId: el folderId de la raíz del canal.

El comportamiento esperado de la unidad de los canales es el siguiente:

• Standard canales usan el driveId del sitio de equipo.
• Otros canales usan un separado driveId para sus sitios individuales.

Administrar el acceso a archivos para usuarios externos o invitados mediante Graph API

POST /drives/{driveId}/items/{itemId}/invite

Autenticación de usuarios externos en pestañas o módulos de tareas

Cuando el módulo de tabulación o tarea necesite acceder a los recursos de SharePoint en el inquilino principal del canal, realice los pasos siguientes:

1. Detectar usuarios externos Use getContext() para recuperar el contexto del canal. Compare user.tenant.id con channel.ownerTenantId or channel.hostTenantId. Si difieren, el usuario es externo.

2. Solicitar token del inquilino principal Llame a getAuthToken() con el identificador de inquilino del usuario externo (user.tenant.id o tid) para asegurarse de que el token se emite desde su inquilino principal.

Volver a la parte superior

Prueba de la aplicación entre canales

Antes de publicar actualizaciones, asegúrese de que la aplicación funciona correctamente en todos los tipos de canal en situaciones reales.

Canal estándar

Confirme que la funcionalidad existente permanece intacta después de los cambios. Asegúrese de que las pestañas, los bots y las extensiones de mensajería sigan funcionando según lo esperado.

Canal compartido

Canal privado

Cree un canal privado en el equipo A con al menos dos miembros (propietario y miembro).

Realice los pasos siguientes para validar:

1. Agregue la aplicación al equipo A y agréguela al canal privado.
2. Compruebe que la pestaña se carga correctamente en el canal privado.
3. Pruebe las respuestas del bot para diferentes tipos de usuario:
   • Miembro en el inquilino
   • Usuario invitado o usuario externo
4. Si la aplicación muestra miembros o asigna tareas, confirme que solo usa miembros del canal y no el equipo completo.
5. Agregue un nuevo miembro al canal privado y compruebe lo siguiente:
   • Si la aplicación recibe un evento de cambio de pertenencia
   • Si la API de pertenencia refleja el nuevo miembro

Las pruebas en estos escenarios le ayudan a detectar cualquier problema con la funcionalidad, los permisos y la experiencia del usuario.

Procedimientos recomendados para admitir todos los canales

Qué hacer

• Recupere siempre la lista de miembros y los roles del canal actual antes de realizar acciones. Por ejemplo, al enviar notificaciones o asignar tareas, se dirige solo a los miembros reales del canal y no a todo el equipo.
• Controle el acceso y el uso compartido de datos en función de la pertenencia y los permisos del canal. Para obtener más información, consulte Administración de la pertenencia a canales.
• Determine si los usuarios son internos, invitados o externos (entre inquilinos) y autentíquelos en su inquilino principal. Valide siempre los permisos para escenarios entre inquilinos, especialmente al acceder a archivos. Para obtener más información, consulte Identificación de usuarios invitados en canales mediante Graph API.
• Actualice el texto de ayuda y las guías de usuario para explicar cómo se comporta la aplicación en diferentes tipos de canal, incluidas las limitaciones para invitados o usuarios externos.
• Revise la documentación y los registros de cambios de Microsoft Teams para mantenerse alineados con las actualizaciones más recientes de las API, los permisos y las configuraciones de canal.

Qué no hacer

• Restrinja las acciones confidenciales a los propietarios o usuarios internos y ofrezca características limitadas a invitados o participantes externos.
• Nunca incluya datos de canal privado en informes más amplios o canales públicos a menos que se autorice explícitamente.

Preguntas frecuentes

Volver a la parte superior

Ejemplos de código

Consulte también

• Administrar la pertenencia al canal
• Descripción de los permisos de aplicación en canales compartidos
• Pestañas de compilación para Teams
• Canales compartidos en Microsoft Teams
• Tipo de recurso de canal
• Directiva de retención para ubicaciones de Teams
• Usar el acceso de invitados y el acceso externo para colaborar con personas fuera de su organización
• Administrar reuniones externas y chatear con personas y organizaciones mediante identidades de Microsoft