Aplicações para canais partilhados e privados

Os canais partilhados e privados no Microsoft Teams permitem uma colaboração flexível entre equipas e organizações. Atualmente, as aplicações de bot e separador são suportadas em canais partilhados e privados. Com esta atualização, pode experimentar vários benefícios:

• Canais partilhados: permita uma comunicação totalmente integrada com membros internos ou externos, sem alterar o contexto do utilizador. Estes canais garantem o controlo de acesso granular seguro e a sincronização de associações em tempo real.

• Canais privados: forneça espaço seguro para que os membros da equipa selecionados colaborem em conteúdo confidencial ou confidencial, garantindo privacidade e debates focados dentro da equipa.

Compreender os canais para a integração de aplicações

Canais diferentes determinam a visibilidade da aplicação, o acesso do utilizador e o comportamento de armazenamento de dados:

Capacidades entre canais

Eis um destaque dos diferentes canais e das suas capacidades, em vários parâmetros:

Compreender como diferentes canais determinam a funcionalidade da aplicação

Certifique-se de que compreende como diferentes canais determinam a funcionalidade da aplicação, a associação, o armazenamento ou a privacidade. Caso contrário, pode levar a funcionalidades quebradas ou exposição a dados não intencionais:

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

  Não suponha que a associação à equipa é igual à associação ao canal. Apenas os membros adicionados ao canal podem participar em canais partilhados e privados.

• Distinguir entre utilizadores e funções

  Os membros do canal podem incluir utilizadores no inquilino, convidados ou utilizadores entre inquilinos (utilizadores externos de outros inquilinos). Se a sua aplicação precisar de distinguir entre vários utilizadores para gerir o acesso, a visibilidade dos dados e a disponibilidade das funcionalidades, tem de validar as funções de utilizador e os IDs de inquilino antes de conceder permissões.

• Não assuma um único site do SharePoint associado a uma equipa

  Ao contrário dos canais padrão, que partilham o site SharePoint com a equipa, os canais privados e partilhados têm os seus próprios sites do SharePoint. Utilize sempre o URL correto para cada canal para evitar ficheiros em falta ou erros de acesso não autorizado.

• Manter os dados no âmbito dos canais

  Agregar ou publicar dados em vários canais apenas quando necessário, para evitar fugas acidentais. Por exemplo, as aplicações de análise não devem incluir dados de canais privados em relatórios de toda a equipa, a menos que as permissões estejam claramente definidas.

Voltar ao Início

Ativar aplicações para canais partilhados e privados

A maioria das aplicações suporta canais partilhados e privados com uma atualização de manifesto simples. Com base em qualquer um dos seguintes cenários, pode decidir a abordagem:

• Aplicações sem dependência em parâmetros especificados
• Aplicações com dependência em parâmetros especificados

Aplicações sem dependência em parâmetros especificados

Se a sua aplicação não:

• Utilizar a associação de canal ou equipa para determinar a entrega de mensagens, a atribuição de tarefas ou as permissões
• Aceder ou gerir ficheiros armazenados no Teams ou no SharePoint
• Combinar ou partilhar dados em vários canais ou equipas
• Personalizar a experiência, com base em utilizadores (internos, convidados ou membros externos)

Em seguida, só precisa de:

1. Adicionar supportsChannelFeatures: tier1 ao manifesto da aplicação
2. Verificar o comportamento esperado e testar a sua aplicação em vários canais

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

Aplicações com dependência em parâmetros especificados

Se a sua aplicação processar cenários avançados ou depender dos parâmetros especificados listados na secção Aplicações sem dependência dos parâmetros especificados , leia este guia para obter as atualizações direcionadas e as melhores práticas. Não reescreva o código.

Obter contexto para canais partilhados e privados

Ao carregar a experiência de utilizador num canal partilhado ou privado, utilize os dados recebidos da getContext chamada para canais partilhados ou privados. A getContext chamada publica duas novas propriedades, hostTeamGroupID e hostTenantID, que são utilizadas para obter a associação a canais com as APIs do Microsoft Graph. Todos os canais são criados dentro de uma equipa de anfitriões. Para obter mais informações, consulte Obter contexto em canais partilhados e Obter contexto para o seu separador para canais privados.

Gerenciar associação de canal

Utilize a allMembers API que gere e monitoriza as associações de canais em canais padrão, partilhados e privados. Melhora a precisão ao refletir corretamente os membros diretos e indiretos. Para obter mais informações, consulte Listar todosMembers.

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

Identificar membros

• Membros diretos: Utilizadores que são adicionados diretamente ao canal, incluindo utilizadores de outros inquilinos (entre inquilinos).
• Membros indiretos: Utilizadores que são membros da equipa, com os quais o canal é partilhado, incluindo equipas no mesmo inquilino ou entre inquilinos.

Pode identificar se um membro de um canal partilhado ou privado é direto ou indireto ao verificar a @microsoft.graph.originalSourceMembershipUrl anotação. Esta propriedade identifica a origem do acesso de um membro aos canais:

Gerir a associação indireta entre canais

Pode gerir a associação indireta em canais com as seguintes APIs do Microsoft Graph:

• Utilize a allMembers API para obter todos os utilizadores que são membros de um canal específico.

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

• Utilize a doesUserHaveAccess API para determinar se o utilizador é removido do canal e pode ver todos os acessos de utilizador e permissões relevantes. As aplicações com permissões de aplicações clássicas e permissões RSC podem utilizar esta API.

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

• Utilize asharedWithTeams API para listar todas as equipas com as quais um canal é partilhado.

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

• Utilize a allowedMembers API para obter utilizadores de uma equipa partilhada que pode aceder a um canal partilhado.

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

  Observação

  A allowedMembers API devolve apenas os utilizadores associados recentemente e não se aplica a eventos não partilhados.

Voltar ao Início

Obter notificações de aplicações para alterações de associação a gráficos

As aplicações instaladas em canais partilhados e privados recebem notificações quando os utilizadores são adicionados ou removidos de uma equipa que partilha o canal.

Para receber notificações de aplicações, tem de:

1. Instale a aplicação numa equipa de anfitrião e ative-a para o canal partilhado ou privado. Para obter mais informações sobre como instalar a aplicação, consulte Instalar a aplicação.
2. Crie uma subscrição de notificação de alteração válida do Microsoft Graph para monitorizar as alterações à associação à equipa associada e eventos partilhados ou não partilhados com as APIs suportadas.

Para receber notificações de atualização de membros diretos e indiretos, tem de incluir os parâmetros da cadeia de consulta ao criar uma subscrição. Se as cadeias de consulta não forem fornecidas, a subscrição apenas entrega notificações para atualizações diretas de membros. Para obter mais informações, veja Acesso à associação a canais.

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

Esta subscrição permite que as aplicações monitorizem as alterações de associação nos canais e nas respetivas equipas associadas. Para obter mais informações sobre como criar uma subscrição de notificação de alteração do Microsoft Graph, consulte Criar uma subscrição.

Obter notificações de aplicações para alterações de associação a bots

O conversationUpdate evento é enviado para o bot quando recebe notificações sobre as atualizações de associação para as equipas onde é adicionado. Para receber notificações de atualização de membros diretos e indiretos, configure o bot com os seguintes pré-requisitos:

1. Atualize o manifesto da aplicação. Adicione supportsChannelFeatures: tier1 para declarar a preparação da aplicação.

2. Pedir permissão de Consentimento Resource-Specific (RSC)

   A sua aplicação tem de pedir a seguinte permissão RSC para aceder às informações de associação de canais:

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

3. Certifique-se de que o bot é adicionado no canal partilhado

   Para receber notificações de eventos de membros, instale o bot ao nível da equipa e permita-o manualmente no canal partilhado.

   Este processo garante que o bot está ativo e autorizado a receber notificações para membros diretos e indiretos.

Gerir eventos adicionados e removidos do membro

Um evento adicionado a um membro é enviado para o bot nos seguintes cenários:

1. Quando o bot, por si só, é instalado e adicionado a uma conversação
2. Quando um utilizador é adicionado a uma conversação onde o bot está instalado

Um evento removido de membro é enviado para o bot nos seguintes cenários:

1. Quando o bot, por si só, é desinstalado e removido de uma conversação.
2. Quando um utilizador é removido de uma conversação onde o bot está instalado.

Para obter mais informações, veja Eventos de conversação.

Se o bot estiver instalado na equipa ou no canal, o SDK de Agentes recebe uma conversationUpdate atividade através do OnConversationUpdateActivityAsync método quando um canal partilhado é adicionado a outra equipa.

Quando um novo membro é adicionado a um canal partilhado, o OnMembersAddedAsync método é chamado. Este método fornece o contexto e os detalhes do utilizador que foi adicionado, permitindo que o bot responda em conformidade.

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

Evento de membro adicionado

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

Processar alterações de associação em massa para gráfico

Se existirem alterações de associação em massa, o Teams restringe as notificações de atualização de associação individuais quando um canal é partilhado ou não partilhado com uma equipa. Para reduzir a sobrecarga de notificação durante as atualizações de associação, como quando um canal partilhado é adicionado ou removido de uma equipa com milhares de membros, utilize osharedWithTeams recurso de subscrição:

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

A sharedWithTeams subscrição envia uma única notificação quando um canal é partilhado ou não partilhado com uma equipa. Evita milhares de notificações por utilizador e melhora o desempenho das aplicações que monitorizam as alterações de associação. Certifique-se de que atualiza a lista de membros do canal partilhado com a API allMembers depois de receber uma notificação de equipa partilhada ounão partilhada.

Validar o acesso do utilizador para atualizações de associação de grafos

Quando uma aplicação recebe uma notificação de membro removido para uma atualização de associação indireta, é importante verificar se o utilizador foi removido do canal, especialmente porque o mesmo utilizador pode ter associação direta e indireta. Por exemplo, se um utilizador for removido de uma equipa que partilha um canal, a sua aplicação tem de confirmar se o acesso do utilizador ao canal partilhado é revogado. Utilize a doesUserHaveAccess API para determinar se o utilizador foi removido do canal partilhado. Veja a API doesUserHaveAccess para saber mais sobre os acessos dos utilizadores e as permissões relevantes.

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

Quando uma aplicação recebe uma notificação de membro adicionada para uma atualização de associação indireta, veja a API allMembers para atualizar a lista de todos os membros.

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

Classificar membros como in-tenant ou out-tenant

Pode classificar os membros como no inquilino ou fora do inquilino ao comparar o "TenantId" do membro ou da equipa com ownerTenantId o seguinte:

1. Obtenha o "TenantId" do membro que pretende comparar.

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

2. Chame microsoftTeams.app.getContext() o seu separador a partir da biblioteca de cliente JavaScript do Teams. A chamada getContext() devolve o contexto do canal partilhado, que contém os detalhes, tais como displayName, membershipType, ownerGroupIde ownerTenantId.

3. Compare o TenantId do membro com a ownerTenantId propriedade e determine se o membro é um inquilino ou um inquilino.

Voltar ao Início

Compreender as permissões de aplicações em canais partilhados

Pode colaborar com membros externos fora da sua organização através de canais partilhados. As permissões de aplicações em canais partilhados seguem a lista de aplicações da equipa anfitriã e a política de aplicações do inquilino anfitrião.

Verificar a instalação do bot num canal

Quando um canal partilhado é adicionado a outra equipa, o SDK de Agentes recebe uma conversationUpdate atividade através do OnConversationUpdateActivityAsync método , apenas se o bot estiver instalado na equipa. Não existe uma API dedicada para marcar se a sua aplicação fizer parte de um canal. Os bots podem detetar quando a sua aplicação é adicionada indiretamente a um canal.

Utilize este channelMemberAdded evento para acionar lógica específica da aplicação, como:

• Enviar uma mensagem de boas-vindas
• A obter a lista de canais
• Configurar separadores
• Iniciar tarefas agendadas

        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 utilizadores externos para aceder ao conteúdo da aplicação no SharePoint

Tem de concluir este passo quando a sua aplicação armazena conteúdos no site do SharePoint do inquilino que aloja o canal e pede um token do SharePoint.

Agora, envie o anfitrião tenantId guardado dentro tenantId do parâmetro de getAuthToken chamada para permitir que os utilizadores entre inquilinos acedam ao conteúdo alojado no site do SharePoint anexado ao canal partilhado.

Identificar utilizadores convidados em canais com API do Graph

Pode identificar se um membro de um canal é um utilizador convidado, convidado para o seu inquilino a partir de uma organização externa, através roles da propriedade recebida para cada objeto em Listar membros de uma resposta de canal .

Para convidados, "roles" = "guest"

Para obter com precisão todos os utilizadores convidados num canal, utilize a seguinte allMembers API:

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

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

Aceder a dados do SharePoint em canais partilhados e privados

Se estiver a criar uma aplicação com o SharePoint Framework, terá de utilizar o site do SharePoint Online (SPO) ligado ao canal partilhado e não o associado ao grupo de equipa de anfitriões. Os canais partilhados e privados têm o seu próprio site SPO que só é acessível aos membros desse canal partilhado ou privado específico.

Utilize a API de convite do Microsoft Graph para aceder à biblioteca de documentos do site do SPO ligado a um canal partilhado ou privado.

Voltar ao Início

Aceder ao armazenamento do SharePoint para ficheiros de canal com API do Graph

Para aceder à raiz de ficheiros do SharePoint de um canal, utilize a seguinte API:

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

Esta API devolve um objeto DriveItem para a raiz de ficheiros desse canal. Para obter mais informações, veja ficheiros de canal

Utilize as seguintes propriedades para todas as operações de ficheiro subsequentes:

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

O comportamento esperado da unidade dos canais é o seguinte:

• Standard canais utilizam o driveId do site de equipa.
• Outros canais utilizam um separador driveId para os respetivos sites individuais.

Gerir o acesso a ficheiros para utilizadores externos ou convidados com API do Graph

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

Autenticar utilizadores externos em separadores ou módulos de tarefas

Quando o separador ou módulo de tarefas precisar de aceder aos recursos do SharePoint no inquilino principal do canal, execute os seguintes passos:

1. Detetar utilizadores externos Utilize getContext() para obter o contexto do canal. Compare user.tenant.id com channel.ownerTenantId or channel.hostTenantId. Se forem diferentes, o utilizador é externo.

2. Peça o token do inquilino raiz Chamada getAuthToken() com o ID de inquilino do utilizador externo (user.tenant.id ou tid) para garantir que o token é emitido a partir do inquilino principal.

Voltar ao Início

Testar a sua aplicação em vários canais

Antes de publicar atualizações, certifique-se de que a sua aplicação funciona corretamente em todos os tipos de canais em situações reais.

Canal padrão

Confirme que a funcionalidade existente permanece intacta após as alterações. Certifique-se de que os separadores, bots e extensões de mensagens continuam a funcionar conforme esperado.

Canal compartilhado

Canal privado

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

Execute os seguintes passos para validar:

1. Adicione a aplicação à Equipa A e, em seguida, adicione-a ao canal privado.
2. Verifique se o separador é carregado corretamente no canal privado.
3. Testar respostas de bot para diferentes tipos de utilizador:
   • Membro no inquilino
   • Utilizador convidado ou utilizador externo
4. Se a sua aplicação listar membros ou atribuir tarefas, confirme que utiliza apenas membros do canal e não a equipa completa.
5. Adicione um novo membro ao canal privado e marcar:
   • Se a sua aplicação recebe um evento de alteração de associação
   • Se a API de associação reflete o novo membro

Os testes nestes cenários ajudam-no a detetar quaisquer problemas com a funcionalidade, as permissões e a experiência do utilizador.

Melhores práticas para suportar todos os canais

O que fazer

• Obtenha sempre as funções e a lista de membros do canal atual antes de efetuar ações. Por exemplo, ao enviar notificações ou atribuir tarefas, direcione apenas os membros reais do canal e não toda a equipa.
• Controlar o acesso e a partilha de dados com base na associação e permissões de canais. Para obter mais informações, veja Gerir a associação a canais.
• Determine se os utilizadores são internos, convidados ou externos (entre inquilinos) e autentique-os no respetivo inquilino doméstico. Valide sempre as permissões para cenários entre inquilinos, especialmente quando acede a ficheiros. Para obter mais informações, veja Identificar utilizadores convidados em canais com API do Graph.
• Atualize o texto da ajuda e os guias do utilizador para explicar o comportamento da sua aplicação em diferentes tipos de canais, incluindo quaisquer limitações para convidados ou utilizadores externos.
• Reveja a documentação e os registos de alterações do Microsoft Teams para se manter alinhado com as atualizações mais recentes às APIs, permissões e configurações de canais.

O que não fazer

• Restrinja ações confidenciais a proprietários ou utilizadores internos e ofereça funcionalidades limitadas a convidados ou participantes externos.
• Nunca inclua dados de canais privados em relatórios mais amplos ou canais públicos, a menos que sejam explicitamente autorizados.

Perguntas frequentes

Voltar ao Início

Exemplos de código

Confira também

• Gerenciar associação de canal
• Compreender as permissões de aplicações em canais partilhados
• 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
• Gerir reuniões externas e conversar por chat com pessoas e organizações com identidades da Microsoft