Agentes e aplicativos de guia para canais compartilhados e privados

Os canais compartilhados e privados no Microsoft Teams permitem uma colaboração flexível entre equipes e organizações. Atualmente, os aplicativos de agente e guia têm suporte em canais compartilhados e privados. Usando essa atualização, você pode obter vários benefícios:

• Canais compartilhados: permitem a comunicação perfeita com membros internos ou externos, sem alterar o contexto do usuário. Esses canais garantem controle de acesso granular seguro e sincronização de associação em tempo real.

• Canais privados: fornecem espaço seguro para membros selecionados da equipe colaborarem em conteúdo sensível ou confidencial, garantindo privacidade e discussões focadas dentro da equipe.

Entender os canais para integração de aplicativos

Canais diferentes determinam a visibilidade do aplicativo, o acesso do usuário e o comportamento do armazenamento de dados:

Recursos em todos os canais

Aqui está um esboço dos diferentes canais e seus recursos em vários parâmetros:

Entenda como diferentes canais determinam a funcionalidade do aplicativo

Certifique-se de entender como diferentes canais determinam a funcionalidade, a associação, o armazenamento ou a privacidade do aplicativo. Caso contrário, você poderá encontrar funcionalidade interrompida ou exposição de dados não intencional:

• Usar APIs de associação específicas do canal

  Não presuma que a associação à equipe é igual à associação ao canal. Somente os membros que você adicionar ao canal podem participar de canais compartilhados e privados.

• Distinguir entre usuários e funções

  Os membros do canal podem incluir usuários no locatário, convidados ou usuários entre locatários (usuários externos de outros locatários). Se o aplicativo precisar distinguir entre vários usuários para gerenciar o acesso, a visibilidade dos dados e a disponibilidade de recursos, valide as funções de usuário e as IDs de locatário antes de conceder permissões.

• Não presuma que um único site do SharePoint esteja vinculado a uma equipe

  Ao contrário dos canais padrão, que compartilham um site do SharePoint com a equipe, os canais privados e compartilhados têm seus próprios sites do SharePoint. Sempre use a URL correta para cada canal, para evitar arquivos ausentes ou erros de acesso não autorizado.

• Manter os dados no escopo dos canais

  Agregue ou publique dados entre canais somente quando necessário, para evitar vazamentos acidentais. Por exemplo, os aplicativos de análise não devem incluir dados de canal privado em relatórios de toda a equipe, a menos que as permissões estejam claramente definidas.

Habilitar aplicativos para canais compartilhados e privados

A maioria dos aplicativos pode dar suporte a canais compartilhados e privados com uma simples atualização de manifesto. Com base em qualquer um dos seguintes cenários, decida a abordagem:

• Aplicativos sem dependência de parâmetros especificados
• Aplicativos com dependência de parâmetros especificados

Aplicativos sem dependência de parâmetros especificados

Se o seu aplicativo não tiver:

• Use a associação de canal ou equipe para determinar a entrega de mensagens, atribuição de tarefas ou permissões
• Acessar ou gerenciar arquivos armazenados no Teams ou no SharePoint
• Combinar ou compartilhar dados em vários canais ou equipes
• Personalizar a experiência com base nos usuários (internos, convidados ou membros externos)

Então, você só precisa:

1. Adicionar supportsChannelFeatures: tier1 ao manifesto do aplicativo
2. Verifique o comportamento esperado e teste seu aplicativo em todos os canais

Não há dependência do acesso clássico e de administrador para supportsChannelFeatures: tier1.

Aplicativos com dependência de parâmetros especificados

Se o aplicativo lida com cenários avançados ou depende dos parâmetros especificados listados na seção Aplicativos sem dependência de parâmetros especificados , leia este guia para atualizações direcionadas e as práticas recomendadas. Não reescreva seu código.

Obter contexto para canais compartilhados e privados

Ao carregar a experiência do usuário em um canal compartilhado ou privado, use os dados recebidos da getContext chamada para canais compartilhados ou privados. A getContext chamada publica duas novas propriedades hostTeamGroupID e hostTenantID, que são usadas para recuperar a associação ao canal usando APIs do Microsoft Graph. Cada canal é criado em uma equipe de host. Para obter mais informações, consulte Obter contexto em canais compartilhados e Obter contexto para sua guia para canais privados.

Gerenciar associação de canal

Use a allMembers API para gerenciar e monitorar associações de canal em canais padrão, compartilhados e privados. Ele aumenta a precisão refletindo corretamente os membros diretos e indiretos. Para obter mais informações, consulte Listar allMembers.

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

Identificar membros

• Membros diretos: Usuários adicionados diretamente ao canal, incluindo usuários de outros locatários (entre locatários).
• Membros indiretos: Usuários que são membros da equipe, com os quais o canal é compartilhado, incluindo equipes no mesmo locatário ou em um locatário cruzado.

Você pode identificar se um membro de um canal compartilhado ou privado é direto ou indireto verificando a @microsoft.graph.originalSourceMembershipUrl anotação. Esta propriedade identifica a origem do acesso de um membro aos canais:

Gerenciar a associação indireta em todos os canais

Você pode gerenciar a associação indireta em canais usando as seguintes APIs do Microsoft Graph:

• Use a allMembers API para obter todos os usuários que são membros de um canal específico.

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

• Use a doesUserHaveAccess API para marcar se o usuário foi removido do canal e pode exibir todos os acessos de usuário e permissões relevantes. Aplicativos com permissões de aplicativo clássico e permissões RSC podem usar essa API.

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

• Use a sharedWithTeams API para listar todas as equipes com as quais um canal é compartilhado.

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

• Use a allowedMembers API para obter usuários de uma equipe compartilhada que podem acessar um canal compartilhado.

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

  Observação

  A allowedMembers API retorna apenas usuários recém-associados e não se aplica a eventos não compartilhados.

Obter notificações de aplicativos para alterações na assinatura do Microsoft Graph

Os aplicativos instalados em canais compartilhados e privados recebem notificações quando os usuários são adicionados ou removidos de uma equipe que compartilha o canal.

Para receber notificações de aplicativos, você deve:

1. Instale o aplicativo em uma equipe anfitriã e habilite-o para o canal compartilhado ou privado. Para obter mais informações sobre como instalar o aplicativo, consulte Instalar o aplicativo.
2. Crie uma assinatura válida de notificação de alteração do Microsoft Graph para monitorar alterações de associação à equipe associadas e eventos compartilhados ou não compartilhados usando APIs com suporte.

Para receber notificações de atualização de membros diretos e indiretos, você deve incluir os dois parâmetros de cadeia de caracteres de consulta ao criar uma assinatura. Se você não fornecer as cadeias de caracteres de consulta, a assinatura fornecerá apenas notificações para atualizações diretas dos membros. Para obter mais informações, consulte Acesso à associação ao canal.

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

Ao usar essa assinatura, os aplicativos podem monitorar as alterações de associação nos canais e suas equipes associadas. Para obter mais informações sobre como criar uma assinatura de notificação de alteração do Microsoft Graph, consulte Criar uma assinatura.

Receber notificações de aplicativos sobre alterações na associação do agente

Seu agente recebe o conversationUpdate evento quando recebe notificações sobre atualizações de associação para equipes onde ele é adicionado. Para receber notificações diretas e indiretas de atualização de membros, configure ao seu agente os seguintes pré-requisitos:

1. Atualize o manifesto do aplicativo para a v1.25. Adicionar supportsChannelFeatures: tier1 para declarar a preparação do aplicativo.

2. Permissão RSC (solicitação de consentimento Resource-Specific)

   Seu aplicativo deve solicitar a seguinte permissão RSC para acessar as informações de associação ao canal:

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

3. Adicionar o agente no canal compartilhado

   Para receber notificações de eventos de membros, instale o agente no nível do Teams e permita-o manualmente no canal compartilhado.

   Esse processo garante que o agente esteja ativo e autorizado a receber notificações para membros diretos e indiretos.

Gerenciar eventos adicionados e removidos de membros

Um evento adicionado ao membro é enviado ao seu agente nos seguintes cenários:

1. Quando você instala o agente e o adiciona a uma conversa.
2. Quando você adiciona um usuário a uma conversa em que o agente está instalado.

Seu agente recebe um evento de remoção de membro nos seguintes cenários:

1. Quando você desinstala o agente e o remove de uma conversa.
2. Quando você remove um usuário de uma conversa em que o agente está instalado.

Para obter mais informações, consulte Eventos de conversa.

Se você instalar o agente na equipe ou no canal, o SDK do Agents receberá uma conversationUpdate atividade por meio do OnConversationUpdateActivityAsync método quando você adicionar um canal compartilhado a outra equipe.

Quando você adiciona um novo membro a um canal compartilhado, o OnMembersAddedAsync método é chamado. Esse método fornece o contexto e os detalhes do usuário que foi adicionado, para que o agente possa responder adequadamente.

Os exemplos de SDK de Agentes a seguir se aplicam a eventos de adição e remoção de membros diretos e indiretos.

Evento adicionado ao membro

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 removido do membro

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);
}

Lidar com alterações de associação em massa para o Graph

Se houver alterações de associação em massa, o Teams restringirá as notificações de atualização de associação individuais quando um canal for compartilhado ou não compartilhado com uma equipe. Para reduzir a sobrecarga de notificações durante atualizações de associação, como quando um canal compartilhado é adicionado ou removido de uma equipe com milhares de membros, use o sharedWithTeams recurso de assinatura:

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

A sharedWithTeams assinatura envia uma única notificação quando um canal é compartilhado ou não compartilhado com uma equipe. Ele evita milhares de notificações por usuário e melhora o desempenho de aplicativos que monitoram alterações de associação. Certifique-se de atualizar a lista de membros do canal compartilhado usando a API allMembers depois de receber uma notificação compartilhada com ou não compartilhada da equipe.

Validar o acesso do usuário para atualizações de associação do graph

Quando um aplicativo recebe uma notificação de membro removido para uma atualização de associação indireta, é importante verificar se o usuário foi removido do canal, especialmente porque o mesmo usuário pode ter associação direta e indireta. Por exemplo, se um usuário for removido de uma equipe que compartilha um canal, seu aplicativo deverá confirmar se o acesso do usuário ao canal compartilhado foi revogado. Use a doesUserHaveAccess API para determinar se o usuário foi removido do canal compartilhado. Consulte a API doesUserHaveAccess para saber mais sobre acessos de usuário e permissões relevantes.

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

Quando um aplicativo recebe uma notificação de adição de membro para uma atualização indireta de associação, consulte a API allMembers para atualizar a lista de todos os membros.

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

Classificar membros como inquilinos ou fora do locatário

Você pode classificar os membros como locatários ou locatários comparando os TenantId membros ou equipe da ownerTenantId seguinte forma:

1. Obtenha o TenantId do membro que você deseja comparar.

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

2. Chame microsoftTeams.app.getContext() sua guia da biblioteca de cliente JavaScript do Teams. A chamada getContext() retorna o contexto do canal compartilhado, que contém detalhes como displayName, membershipType, ownerGroupId, e ownerTenantId.

3. Compare o TenantId membro com a ownerTenantId propriedade e determine se o membro é um inquilino ou locatário externo.

Entender as permissões de aplicativos nos canais compartilhados

Você pode colaborar com membros externos fora da sua organização usando canais compartilhados. As permissões de aplicativo em canais compartilhados seguem a lista de aplicativos da equipe anfitriã e a política de aplicativo do locatário do host.

Verificar a instalação do agente em um canal

Quando um canal compartilhado é adicionado a outra equipe, o SDK do Agents recebe uma conversationUpdate atividade por meio do OnConversationUpdateActivityAsync método, somente se o agente estiver instalado na equipe. Não há nenhuma API dedicada para marcar se seu aplicativo faz parte de um canal. Os agentes podem detectar quando seu aplicativo é adicionado a um canal indiretamente.

Use esse channelMemberAdded evento para disparar a lógica específica do aplicativo, como:

• Enviando uma mensagem de boas-vindas
• Buscando a lista de participantes do canal
• Configurando guias
• Iniciando trabalhos agendados

        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);
        }

Autenticar usuários externos para acessar o conteúdo do aplicativo no SharePoint

Conclua esta etapa quando seu aplicativo armazenar conteúdo no site do SharePoint do locatário que hospeda o canal e solicitar um token do SharePoint.

Agora, envie o host tenantId salvo dentro tenantId do parâmetro de getAuthToken chamada para permitir que os usuários entre locatários acessem o conteúdo hospedado no site do SharePoint anexado ao canal compartilhado.

Identificar usuários convidados em canais usando a API do Graph

Você pode identificar se um membro de um canal é um usuário convidado, convidado para o locatário da organização externa, usando a roles propriedade para cada objeto na Lista de membros de uma resposta do canal .

Para convidados, roles = guest.

Para recuperar com precisão todos os usuários convidados em um canal, use a seguinte allMembers API:

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

Essa API funciona em todos os canais padrão e outros e é recomendada para identificar de forma confiável os membros convidados.

Acessar dados do SharePoint em canais compartilhados e privados

Se você estiver criando um aplicativo usando a Estrutura do SharePoint , precisará usar o site do SharePoint no Microsoft 365 (SPO) vinculado ao canal compartilhado, não aquele vinculado ao grupo da equipe host. Os canais compartilhado e privado têm seu próprio site do SharePoint que somente os membros desse canal compartilhado ou privado específico podem acessar.

Use a API de convite do Microsoft Graph para acessar a biblioteca de documentos do site do SharePoint no Microsoft 365 vinculado a um canal compartilhado ou privado.

Acessar o armazenamento do SharePoint para arquivos de canal usando a API do Graph

Para acessar a raiz de arquivos do SharePoint de um canal, use a seguinte API:

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

Essa API retorna um objeto DriveItem para a raiz de arquivos desse canal. Para obter mais informações, consulte arquivos de canal.

Use as seguintes propriedades para todas as operações de arquivo subsequentes:

• parentReference.driveId: A DriveId do SharePoint para o site do canal.
• itemId: A folderId da raiz do canal.

O comportamento de acionamento esperado dos canais é o seguinte:

• Os canais Standard usam a driveId do site de equipe.
• Outros canais usam um separado driveId para seus sites individuais.

Gerenciar o acesso a arquivos para usuários externos ou convidados usando a API do Graph

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

Autenticar usuários externos em guias ou módulos de tarefas

Quando sua guia ou módulo de tarefa precisar acessar recursos do SharePoint no locatário inicial do canal, execute as seguintes etapas:

1. Detectar usuários externos Use getContext() para recuperar o contexto do canal. Compare user.tenant.id com channel.ownerTenantId ou channel.hostTenantId. Se forem diferentes, o usuário é externo.

2. Solicitar token do locatário inicial Chame getAuthToken() com a ID do locatário do usuário externo (user.tenant.id ou tid) para garantir que o token seja emitido de seu locatário inicial.

Teste seu aplicativo em vários canais

Antes de publicar atualizações, certifique-se de que seu aplicativo funcione corretamente em todos os tipos de canal em situações reais.

Canal padrão

Confirme se a funcionalidade existente permanece intacta após as alterações. Certifique-se de que guias, bots e extensões de mensagens continuem funcionando conforme o esperado.

Canal compartilhado

Canal privado

Crie um canal privado na Equipe A com pelo menos dois membros (proprietário e membro).

Execute as seguintes etapas para validar o suporte de canal privado:

1. Adicione o aplicativo à Equipe A e, em seguida, adicione-o ao canal privado.
2. Verifique se a guia foi carregada corretamente no canal privado.
3. Se o aplicativo listar membros ou atribuir tarefas, confirme se ele usa apenas membros do canal e não a equipe completa.
4. Adicione um novo membro ao canal privado e marcar:
   • Se seu aplicativo recebe um evento de alteração de associação
   • Se sua API de associação reflete o novo membro

Testar esses cenários ajuda você a detectar quaisquer problemas com funcionalidade, permissões e experiência do usuário.

Práticas recomendadas para oferecer suporte a todos os canais

O que fazer

• Sempre obtenha a lista de membros e as funções do canal atual antes de executar ações. Por exemplo, ao enviar notificações ou atribuir tarefas, direcione apenas os membros reais do canal e não a equipe inteira.
• Controle o acesso e o compartilhamento de dados com base na associação e nas permissões do canal. Para obter mais informações, consulte Gerenciar a associação do canal.
• Determine se os usuários são internos, convidados ou externos (entre locatários) e autentique-os em seu locatário inicial. Sempre valide as permissões para cenários entre locatários, especialmente ao acessar arquivos. Para obter mais informações, consulte Identificar usuários convidados em canais usando a API do Graph.
• Atualize o texto de ajuda e os guias do usuário para explicar como seu aplicativo se comporta em diferentes tipos de canal, incluindo quaisquer limitações para convidados ou usuários externos.
• Examine a documentação e os changelogs do Teams para se manter alinhado com as atualizações mais recentes para APIs, permissões e configurações de canal.

O que não fazer

• Restrinja ações confidenciais a proprietários ou usuários internos e ofereça recursos limitados a convidados ou participantes externos.
• Nunca inclua dados de canal privado em relatórios mais amplos ou canais públicos, a menos que explicitamente autorizado.

Perguntas frequentes

Exemplos de código

Confira também

• Gerenciar associação de canal
• Entender as permissões de aplicativos nos canais compartilhados
• Compilar guias para o Teams
• Canais compartilhados no Microsoft Teams
• Tipo de recurso de canal
• Política de retenção para locais do Teams
• Usar o acesso para convidado e o acesso externo para colaborar com pessoas de fora da sua organização
• Gerenciar reuniões externas e conversar com pessoas e organizações usando identidades da Microsoft