Applications pour les canaux partagés et privés

Les canaux partagés et privés dans Microsoft Teams permettent une collaboration flexible au sein des équipes et entre les organisations. Actuellement, les applications de bot et d’onglet sont prises en charge dans les canaux partagés et privés. Avec cette mise à jour, vous pouvez bénéficier de plusieurs avantages :

• Canaux partagés : autorisez une communication transparente avec les membres internes ou externes, sans modifier le contexte de l’utilisateur. Ces canaux garantissent un contrôle d’accès granulaire sécurisé et une synchronisation d’appartenance en temps réel.

• Canaux privés : fournissent un espace sécurisé pour que les membres de l’équipe sélectionnés collaborent sur du contenu sensible ou confidentiel, garantissant ainsi la confidentialité et les discussions ciblées au sein de l’équipe.

Comprendre les canaux pour l’intégration d’applications

Différents canaux déterminent la visibilité de l’application, l’accès utilisateur et le comportement de stockage des données :

Fonctionnalités sur plusieurs canaux

Voici un aperçu des différents canaux et de leurs fonctionnalités, sur différents paramètres :

Comprendre comment les différents canaux déterminent les fonctionnalités de l’application

Veillez à comprendre que la façon dont les différents canaux déterminent la fonctionnalité, l’appartenance, le stockage ou la confidentialité de l’application peut entraîner des fonctionnalités rompues ou une exposition involontaire des données :

• Utiliser des API d’appartenance spécifiques au canal

  Ne supposez pas que l’appartenance à l’équipe est égale à l’appartenance au canal. Seuls les membres ajoutés au canal peuvent participer à des canaux partagés et privés.

• Faire la distinction entre les utilisateurs et les rôles

  Les membres du canal peuvent inclure des utilisateurs dans le locataire, des invités ou des utilisateurs interlocataires (utilisateurs externes d’autres locataires). Si votre application doit faire la distinction entre différents utilisateurs pour gérer l’accès, la visibilité des données et la disponibilité des fonctionnalités, vous devez valider les rôles d’utilisateur et les ID de locataire avant d’accorder des autorisations.

• Ne supposez pas qu’un seul site SharePoint est lié à une équipe

  Contrairement aux canaux standard, qui partagent un site SharePoint avec l’équipe, les canaux privés et partagés ont leurs propres sites SharePoint. Utilisez toujours l’URL correcte pour chaque canal afin d’éviter les fichiers manquants ou les erreurs d’accès non autorisé.

• Conserver les données délimitées aux canaux

  Agrégez ou publiez des données croisées entre les canaux uniquement si nécessaire, afin d’éviter les fuites accidentelles. Par exemple, les applications analytiques ne doivent pas inclure de données de canal privé dans les rapports à l’échelle de l’équipe, sauf si les autorisations sont clairement définies.

Revenir en haut

Activer les applications pour les canaux partagés et privés

La plupart des applications peuvent prendre en charge les canaux partagés et privés avec une simple mise à jour du manifeste. En fonction de l’un des scénarios suivants, vous pouvez choisir l’approche :

• Applications sans dépendance vis-à-vis des paramètres spécifiés
• Applications dépendantes des paramètres spécifiés

Applications sans dépendance vis-à-vis des paramètres spécifiés

Si votre application ne le fait pas :

• Utiliser l’appartenance à un canal ou à une équipe pour déterminer la remise des messages, l’attribution de tâches ou les autorisations
• Accéder ou gérer des fichiers stockés dans Teams ou SharePoint
• Combiner ou partager des données entre plusieurs canaux ou équipes
• Personnaliser l’expérience, en fonction des utilisateurs (internes, invités ou membres externes)

Ensuite, il vous suffit de :

1. Ajouter supportsChannelFeatures: tier1 au manifeste de votre application
2. Vérifiez le comportement attendu et testez votre application sur plusieurs canaux

Il n’existe aucune dépendance vis-à-vis de l’accès classique et administrateur pour supportsChannelFeatures: tier1.

Applications dépendantes des paramètres spécifiés

Si votre application gère des scénarios avancés ou dépend des paramètres spécifiés répertoriés dans la section Applications sans dépendance par rapport aux paramètres spécifiés , lisez ce guide pour connaître les mises à jour ciblées et les meilleures pratiques. Ne réécris pas votre code.

Obtenir le contexte des canaux partagés et privés

Lors du chargement de l’expérience utilisateur dans un canal partagé ou privé, utilisez les données reçues de l’appel getContext pour les canaux partagés ou privés. L’appel getContext publie deux nouvelles propriétés, hostTeamGroupID et hostTenantID, qui sont utilisées pour récupérer l’appartenance au canal à l’aide des API Microsoft Graph. Chaque canal est créé au sein d’une équipe hôte. Pour plus d’informations, consultez Obtenir le contexte dans les canaux partagés et Obtenir le contexte pour votre onglet pour les canaux privés.

Gérer l’appartenance au canal

Utilisez l’API allMembers qui gère et surveille les appartenances aux canaux standard, partagés et privés. Il améliore la précision en reflétant correctement les membres directs et indirects. Pour plus d’informations, consultez Lister tous les membres.

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

Identifier les membres

• Membres directs : Utilisateurs ajoutés directement au canal, y compris les utilisateurs d’autres locataires (entre locataires).
• Membres indirects : Utilisateurs membres de l’équipe avec laquelle le canal est partagé, y compris les équipes du même locataire ou d’un interlocataire.

Vous pouvez déterminer si un membre d’un canal partagé ou privé est direct ou indirect en vérifiant l’annotation @microsoft.graph.originalSourceMembershipUrl . Cette propriété identifie la source de l’accès d’un membre aux canaux :

Gérer l’appartenance indirecte entre les canaux

Vous pouvez gérer l’appartenance indirecte aux canaux à l’aide des API Microsoft Graph suivantes :

• Utilisez l’API allMembers pour récupérer tous les utilisateurs qui sont membres d’un canal spécifique.

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

• Utilisez l’API doesUserHaveAccess pour déterminer si l’utilisateur est supprimé du canal et peut afficher tous les accès utilisateur et les autorisations appropriées. Les applications disposant d’autorisations d’application classiques et d’autorisations RSC peuvent utiliser cette API.

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

• Utilisez l’APIsharedWithTeams pour répertorier toutes les équipes avec qui un canal est partagé.

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

• Utilisez l’API allowedMembers pour récupérer des utilisateurs d’une équipe partagée qui peuvent accéder à un canal partagé.

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

  Remarque

  L’API allowedMembers retourne uniquement les utilisateurs nouvellement associés et ne s’applique pas aux événements non partagés.

Revenir en haut

Obtenir des notifications d’application pour les modifications d’appartenance au graphique

Les applications installées dans des canaux partagés et privés reçoivent des notifications lorsque des utilisateurs sont ajoutés ou supprimés d’une équipe qui partage le canal.

Pour recevoir des notifications d’application, vous devez :

1. Installez l’application dans une équipe hôte et activez-la pour le canal partagé ou privé. Pour plus d’informations sur l’installation de l’application, consultez Installer l’application.
2. Créez un abonnement aux notifications de modification Microsoft Graph valide pour surveiller les modifications d’appartenance à l’équipe associées et les événements partagés ou non partagés à l’aide d’API prises en charge.

Pour recevoir des notifications de mise à jour de membre directe et indirecte, vous devez inclure les deux paramètres de chaîne de requête lors de la création d’un abonnement. Si les chaînes de requête ne sont pas fournies, l’abonnement remet uniquement des notifications pour les mises à jour directes des membres. Pour plus d’informations, consultez Accès à l’appartenance au canal.

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

Cet abonnement permet aux applications de surveiller les changements d’appartenance dans les canaux et les équipes associées. Pour plus d’informations sur la création d’un abonnement aux notifications de modification Microsoft Graph, consultez Créer un abonnement.

Obtenir des notifications d’application pour les modifications d’appartenance au bot

L’événement conversationUpdate est envoyé à votre bot lorsqu’il reçoit des notifications sur les mises à jour d’appartenance pour les équipes où il est ajouté. Pour recevoir des notifications de mise à jour directe et indirecte des membres, configurez votre bot avec les prérequis suivants :

1. Mettez à jour le manifeste de l’application. Ajoutez supportsChannelFeatures: tier1 pour déclarer la préparation de l’application.

2. Demander l’autorisation de consentement Resource-Specific (RSC)

   Votre application doit demander l’autorisation RSC suivante pour accéder aux informations d’appartenance au canal :

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

3. Vérifier que le bot est ajouté dans le canal partagé

   Pour recevoir des notifications d’événements de membre, installez le bot au niveau de l’équipe et autorisez-le manuellement dans le canal partagé.

   Ce processus garantit que le bot est actif et autorisé à recevoir des notifications pour les membres directs et indirects.

Gérer les événements ajoutés et supprimés des membres

Un événement de membre ajouté est envoyé à votre bot dans les scénarios suivants :

1. Lorsque le bot, lui-même, est installé et ajouté à une conversation
2. Lorsqu’un utilisateur est ajouté à une conversation où le bot est installé

Un événement de membre supprimé est envoyé à votre bot dans les scénarios suivants :

1. Lorsque le bot, lui-même, est désinstallé et supprimé d’une conversation.
2. Lorsqu’un utilisateur est supprimé d’une conversation où le bot est installé.

Pour plus d’informations, consultez Événements de conversation.

Si le bot est installé dans l’équipe ou le canal, le Kit de développement logiciel (SDK) Agents reçoit une conversationUpdate activité via la OnConversationUpdateActivityAsync méthode , lorsqu’un canal partagé est ajouté à une autre équipe.

Lorsqu’un nouveau membre est ajouté à un canal partagé, la OnMembersAddedAsync méthode est appelée. Cette méthode fournit le contexte et les détails de l’utilisateur qui a été ajouté, ce qui permet au bot de répondre en conséquence.

Les exemples suivants du Kit de développement logiciel (SDK) Agents s’appliquent aux événements d’ajout et de suppression de membres directs et indirects.

Événement de membre ajouté

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

Événement de suppression de membre

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

Gérer les modifications d’appartenance en bloc pour le graphique

En cas de modifications d’appartenance en bloc, Teams limite les notifications de mise à jour d’appartenance individuelles lorsqu’un canal est partagé ou non partagé avec une équipe. Pour réduire la surcharge de notification pendant les mises à jour d’appartenance, par exemple lorsqu’un canal partagé est ajouté ou supprimé d’une équipe comprenant des milliers de membres, utilisez lasharedWithTeams ressource d’abonnement :

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

L’abonnement sharedWithTeams envoie une notification unique lorsqu’un canal est partagé ou non partagé avec une équipe. Il évite des milliers de notifications par utilisateur et améliore les performances des applications qui surveillent les changements d’appartenance. Veillez à mettre à jour la liste des membres du canal partagé à l’aide de l’API allMembers après avoir reçu une notification partagée avec ou non partagée à partir d’une notification d’équipe .

Valider l’accès utilisateur pour les mises à jour d’appartenance au graphique

Lorsqu’une application reçoit une notification de membre supprimé pour une mise à jour d’appartenance indirecte, il est important de vérifier si l’utilisateur est supprimé du canal, d’autant plus que le même utilisateur peut avoir à la fois une appartenance directe et indirecte. Par exemple, si un utilisateur est supprimé d’une équipe qui partage un canal, votre application doit confirmer si l’accès de l’utilisateur au canal partagé est révoqué. Utilisez l’API doesUserHaveAccess pour déterminer si l’utilisateur est supprimé du canal partagé. Consultez l’API doesUserHaveAccess pour en savoir plus sur les accès utilisateur et les autorisations pertinentes.

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

Lorsqu’une application reçoit une notification ajoutée à un membre pour une mise à jour d’appartenance indirecte, consultez l’API allMembers pour actualiser la liste de tous les membres.

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

Classifier les membres comme in-tenant ou out-tenant

Vous pouvez classifier les membres comme in-tenant ou out-tenant en comparant le « TenantId » du membre ou de l’équipe comme ownerTenantId suit :

1. Obtenez le « TenantId » du membre que vous souhaitez comparer.

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

2. Appelez microsoftTeams.app.getContext() dans votre onglet à partir de la bibliothèque de client JavaScript Teams. L’appel getContext() retourne le contexte du canal partagé, qui contient les détails tels que displayName, membershipType, ownerGroupIdet ownerTenantId.

3. Comparez le TenantId du membre à la ownerTenantId propriété et déterminez si le membre est in-tenant ou out-tenant.

Revenir en haut

Comprendre les autorisations d’application dans les canaux partagés

Vous pouvez collaborer avec des membres externes en dehors de votre organization à l’aide de canaux partagés. Les autorisations d’application dans les canaux partagés suivent la liste des applications de l’équipe hôte et la stratégie d’application du locataire hôte.

Vérifier l’installation du bot dans un canal

Lorsqu’un canal partagé est ajouté à une autre équipe, le Kit de développement logiciel (SDK) Agents reçoit une conversationUpdate activité via la OnConversationUpdateActivityAsync méthode , uniquement si le bot est installé dans l’équipe. Il n’existe aucune API dédiée à case activée si votre application fait partie d’un canal. Les bots peuvent détecter quand votre application est ajoutée indirectement à un canal.

Utilisez cet channelMemberAdded événement pour déclencher une logique spécifique à l’application, par exemple :

• Envoi d’un message de bienvenue
• Récupération de la liste des canaux
• Configuration des onglets
• Démarrage des travaux planifiés

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

Authentifier les utilisateurs externes pour accéder au contenu de l’application dans SharePoint

Vous devez effectuer cette étape lorsque votre application stocke du contenu dans le site SharePoint du locataire qui héberge le canal et demande un jeton SharePoint.

À présent, envoyez l’hôte tenantId enregistré dans tenantId le paramètre d’appel getAuthToken pour permettre aux utilisateurs interlocataires d’accéder au contenu hébergé à l’intérieur du site SharePoint attaché au canal partagé.

Identifier les utilisateurs invités dans les canaux à l’aide de API Graph

Vous pouvez identifier si un membre d’un canal est un utilisateur invité, invité à votre locataire à partir de organization externes, à l’aide roles de la propriété reçue pour chaque objet dans Lister les membres d’une réponse de canal.

Pour les invités, 'roles' = 'guest'

Pour récupérer avec précision tous les utilisateurs invités dans un canal, utilisez l’API suivante allMembers :

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

Cette API fonctionne sur d’autres canaux standard et est recommandée pour identifier de manière fiable les membres invités.

Accéder aux données SharePoint dans des canaux partagés et privés

Si vous créez une application à l’aide de SharePoint Framework, vous devez utiliser le site SharePoint Online (SPO) lié au canal partagé, et non celui lié au groupe d’équipe hôte. Les canaux partagés et privés ont leur propre site SPO qui n’est accessible qu’aux membres de ce canal partagé ou privé spécifique.

Utilisez l’API d’invitation Microsoft Graph pour accéder à la bibliothèque de documents du site SPO lié à un canal partagé ou privé.

Revenir en haut

Accéder au stockage SharePoint pour les fichiers de canal à l’aide de API Graph

Pour accéder à la racine des fichiers SharePoint d’un canal, utilisez l’API suivante :

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

Cette API renvoie un objet DriveItem pour la racine des fichiers de ce canal. Pour plus d’informations, consultez Fichiers de canal

Utilisez les propriétés suivantes pour toutes les opérations de fichier suivantes :

• parentReference.driveId: DriveId SharePoint pour le site du canal.
• itemId: folderId de la racine du canal.

Le comportement de lecteur attendu des canaux est le suivant :

• Standard canaux utilisent le driveId du site d’équipe.
• D’autres canaux utilisent un autre driveId pour leurs sites individuels.

Gérer l’accès aux fichiers pour les utilisateurs externes ou invités à l’aide de API Graph

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

Authentifier les utilisateurs externes dans des onglets ou des modules de tâche

Lorsque votre onglet ou module de tâche doit accéder aux ressources sharepoint dans le locataire de base du canal, procédez comme suit :

1. Détecter les utilisateurs externes Utilisez getContext() pour récupérer le contexte du canal. Comparez user.tenant.id avec channel.ownerTenantId or channel.hostTenantId. S’ils diffèrent, l’utilisateur est externe.

2. Demandez un jeton à partir du locataire d’origine Appelez getAuthToken() avec l’ID de locataire de l’utilisateur externe (user.tenant.id ou tid) pour vous assurer que le jeton est émis à partir de son locataire d’origine.

Revenir en haut

Tester votre application sur plusieurs canaux

Avant de publier des mises à jour, vérifiez que votre application fonctionne correctement sur tous les types de canaux dans des situations réelles.

Canal standard

Vérifiez que la fonctionnalité existante reste intacte après vos modifications. Assurez-vous que les onglets, les bots et les extensions de messagerie continuent de fonctionner comme prévu.

Canal partagé

Canal privé

Créez un canal privé dans l’équipe A avec au moins deux membres (propriétaire et membre).

Effectuez les étapes suivantes pour valider :

1. Ajoutez l’application à l’équipe A, puis ajoutez-la au canal privé.
2. Vérifiez que votre onglet se charge correctement dans le canal privé.
3. Testez les réponses du bot pour différents types d’utilisateurs :
   • Membre dans le locataire
   • Utilisateur invité ou utilisateur externe
4. Si votre application répertorie des membres ou attribue des tâches, vérifiez qu’elle utilise uniquement les membres du canal et non l’équipe complète.
5. Ajoutez un nouveau membre au canal privé et case activée :
   • Si votre application reçoit un événement de changement d’appartenance
   • Si votre API d’appartenance reflète le nouveau membre

Les tests dans ces scénarios vous aident à repérer les problèmes liés aux fonctionnalités, aux autorisations et à l’expérience utilisateur.

Bonnes pratiques pour la prise en charge de tous les canaux

À faire

• Récupérez toujours la liste des membres et les rôles du canal actuel avant d’effectuer des actions. Par exemple, lors de l’envoi de notifications ou de l’attribution de tâches, ciblez uniquement les membres réels du canal et non l’ensemble de l’équipe.
• Contrôlez l’accès et le partage des données en fonction de l’appartenance au canal et des autorisations. Pour plus d’informations, consultez Gérer l’appartenance aux canaux.
• Déterminez si les utilisateurs sont internes, invités ou externes (interlocataires) et authentifiez-les dans leur locataire d’origine. Validez toujours les autorisations pour les scénarios interlocataires, en particulier lors de l’accès aux fichiers. Pour plus d’informations, consultez Identifier les utilisateurs invités dans les canaux à l’aide de API Graph.
• Mettez à jour le texte d’aide et les guides de l’utilisateur pour expliquer comment votre application se comporte dans différents types de canaux, y compris les limitations pour les invités ou les utilisateurs externes.
• Consultez la documentation de Microsoft Teams et les journaux des modifications pour rester aligné sur les dernières mises à jour des API, des autorisations et des configurations de canal.

À ne pas faire

• Limitez les actions sensibles aux propriétaires ou aux utilisateurs internes et proposez des fonctionnalités limitées aux invités ou aux participants externes.
• N’incluez jamais de données de canal privé dans des rapports plus larges ou des canaux publics, sauf autorisation explicite.

Foire aux questions

Revenir en haut

Exemples de code

Voir aussi

• Gérer l’appartenance au canal
• Comprendre les autorisations d’application dans les canaux partagés
• Créer des onglets pour Teams
• Canaux partagés dans Microsoft Teams
• Type de ressource de canal
• Stratégie de rétention pour les emplacements Teams
• Utiliser l’accès invité et l’accès externe pour collaborer avec des personnes extérieures à votre organisation
• Gérer des réunions externes et discuter avec des personnes et des organisations à l’aide d’identités Microsoft