Приложения для общих и частных каналов

Общие и частные каналы в Microsoft Teams обеспечивают гибкую совместную работу в командах и организациях. В настоящее время приложения ботов и вкладок поддерживаются в общих и частных каналах. С помощью этого обновления можно воспользоваться несколькими преимуществами:

• Общие каналы. Обеспечивают беспроблемное взаимодействие с внутренними или внешними участниками без изменения контекста пользователя. Эти каналы обеспечивают безопасное детальное управление доступом и синхронизацию членства в режиме реального времени.

• Частные каналы. Предоставление безопасного пространства для отдельных участников команды для совместной работы над конфиденциальным или конфиденциальным содержимым, обеспечивая конфиденциальность и целенаправленные обсуждения в команде.

Общие сведения о каналах для интеграции приложений

Различные каналы определяют видимость приложений, доступ пользователей и поведение хранилища данных:

Возможности в разных каналах

Ниже приведены общие сведения о различных каналах и их возможностях в различных параметрах:

Узнайте, как различные каналы определяют функциональность приложения

Убедитесь, что вы понимаете, как различные каналы определяют функциональность приложения, членство, хранилище или конфиденциальность. В противном случае может возникнуть сломанная функциональность или непреднамеренное раскрытие данных:

• Использование API-интерфейсов членства для конкретного канала

  Не предполагайте, что членство в команде равно членству в канале. Только участники, добавленные в канал, могут участвовать в общих и частных каналах.

• Различие между пользователями и ролями

  Участники канала могут включать пользователей из клиента, гостей или межтенантных пользователей (внешних пользователей из других клиентов). Если приложению необходимо различать различных пользователей для управления доступом, видимостью данных и доступностью компонентов, перед предоставлением разрешений необходимо проверить роли пользователей и идентификаторы клиентов.

• Не предполагайте, что один сайт SharePoint привязан к команде

  В отличие от стандартных каналов, которые совместно используют сайт SharePoint с командой, частные и общие каналы имеют собственные сайты SharePoint. Всегда используйте правильный URL-адрес для каждого канала, чтобы избежать отсутствующих файлов или ошибок несанкционированного доступа.

• Хранение данных в пределах каналов

  Агрегировать или пересылать данные по каналам только при необходимости, чтобы предотвратить случайные утечки. Например, приложения аналитики не должны включать данные частного канала в отчеты на уровне команды, если только разрешения не определены четко.

Вернуться к началу

Включение приложений для общих и частных каналов

Большинство приложений поддерживают общие и частные каналы с простым обновлением манифеста. На основе любого из следующих сценариев определите подход:

• Приложения без зависимости от указанных параметров
• Приложения с зависимостью от указанных параметров

Приложения без зависимости от указанных параметров

Если приложение не выполняется, выполните приведенные ниже действия.

• Использование членства в канале или группе для определения доставки сообщений, назначения задач или разрешений
• Доступ к файлам, хранящимся в Teams или SharePoint, или управление ими
• Объединение и совместное использование данных в нескольких каналах или командах
• Настройка взаимодействия с учетом пользователей (внутренних, гостей или внешних участников)

Затем вам потребуется только:

1. Добавьте supportsChannelFeatures: tier1 в манифест приложения
2. Проверка ожидаемого поведения и тестирование приложения в разных каналах

Нет зависимости от классического доступа и доступа администратора для supportsChannelFeatures: tier1.

Приложения с зависимостью от указанных параметров

Если ваше приложение обрабатывает расширенные сценарии или зависит от указанных параметров, перечисленных в разделе Приложения без зависимости от указанных параметров , ознакомьтесь с этим руководством по целевым обновлениям и рекомендациям. Не переписывайте код.

Получение контекста для общих и частных каналов

При загрузке пользовательского интерфейса в общем или частном канале используйте данные, полученные от getContext вызова для общих или частных каналов. Вызов getContext публикует два новых свойства и hostTeamGroupIDhostTenantID, которые используются для получения членства в канале с помощью API Microsoft Graph. Каждый канал создается в команде узла. Дополнительные сведения см . в разделах Получение контекста в общих каналах и Получение контекста для вкладки для частных каналов.

Управление участием в каналах

allMembers Используйте API для управления членством в каналах и мониторинга их членства в стандартных, общих и частных каналах. Он повышает точность за счет правильного отражения прямых и косвенных элементов. Дополнительные сведения см. в разделе Перечисление всех элементов.

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

Определение участников

• Прямые члены: Пользователи, которые добавляются непосредственно в канал, включая пользователей из других клиентов (межтенантных).
• Непрямые члены: Пользователи, являющиеся членами команды, с которой предоставлен общий доступ к каналу, включая команды в одном клиенте или в нескольких клиентах.

Вы можете определить, является ли участник общего или частного канала прямым или косвенным, проверив заметку @microsoft.graph.originalSourceMembershipUrl . Это свойство определяет источник доступа участника к каналам:

Управление косвенным членством в разных каналах

Вы можете управлять косвенным членством в каналах с помощью следующих API Microsoft Graph:

• allMembers Используйте API, чтобы получить всех пользователей, которые являются участниками определенного канала.

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

• doesUserHaveAccess Используйте API, чтобы проверка, если пользователь удален из канала и может просматривать все доступы пользователей и соответствующие разрешения. Приложения с классическими разрешениями приложений и разрешениями RSC могут использовать этот API.

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

• Используйте API для sharedWithTeams вывода списка всех команд, которым предоставлен общий доступ к каналу.

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

• Используйте API, allowedMembers чтобы получить доступ к общему каналу пользователей из общей команды.

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

  Примечание.

  allowedMembers API возвращает только новых связанных пользователей и не применяется к событиям без общего доступа.

Вернуться к началу

Получение уведомлений приложений об изменениях членства в Microsoft Graph

Приложения, установленные в общих и частных каналах, получают уведомления о добавлении пользователей в команду, которая предоставляет общий доступ к каналу, или удаляет их из нее.

Чтобы получать уведомления от приложения, необходимо:

1. Установите приложение в команде узла и включите его для общего или частного канала. Дополнительные сведения об установке приложения см. в разделе Установка приложения.
2. Создайте действительную подписку на уведомления об изменениях Microsoft Graph для отслеживания связанных изменений членства в команде и общих или общих событий с помощью поддерживаемых API.

Чтобы получать как прямые, так и косвенные уведомления об обновлении элементов, при создании подписки необходимо включить оба параметра строки запроса. Если не указать строки запроса, подписка будет предоставлять только уведомления о прямых обновлениях участников. Дополнительные сведения см. в разделе Доступ к членству в канале.

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

Используя эту подписку, приложения могут отслеживать изменения членства в каналах и связанных с ними командах. Дополнительные сведения о создании подписки на уведомления об изменениях в Microsoft Graph см. в разделе Создание подписки.

Получение уведомлений приложения об изменениях членства бота

Бот получает событие, conversationUpdate когда получает уведомления об обновлениях членства для команд, в которых оно добавлено. Чтобы получать как прямые, так и косвенные уведомления об обновлении участников, настройте бота со следующими предварительными условиями:

1. Обновите манифест приложения до версии 1.25. Добавление supportsChannelFeatures: tier1 для объявления готовности приложения.

2. Запрос разрешения Resource-Specific согласия (RSC)

   Приложение должно запросить следующее разрешение RSC для доступа к сведениям о членстве в каналах:

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

3. Добавление бота в общий канал

   Чтобы получать уведомления о событиях участников, установите бот на уровне Teams и вручную разрешите его в общем канале.

   Этот процесс гарантирует, что бот активен и авторизован для получения уведомлений как для прямых, так и для непрямых участников.

Управление добавленными и удаленными событиями участников

Добавленное событие участника отправляется боту в следующих сценариях:

1. При установке бота и его добавлении в беседу.
2. При добавлении пользователя в беседу, где установлен бот.

Бот получает событие удаления члена в следующих сценариях:

1. При удалении бота и его удаления из беседы.
2. При удалении пользователя из беседы, в которой установлен бот.

Дополнительные сведения см. в разделе События беседы.

При установке бота в команде или канале пакет SDK агентов conversationUpdate получает действие с помощью OnConversationUpdateActivityAsync метода при добавлении общего канала в другую команду.

При добавлении нового участника в общий канал OnMembersAddedAsync вызывается метод . Этот метод предоставляет контекст и сведения о добавленном пользователе, чтобы бот смог ответить соответствующим образом.

Приведенные ниже примеры пакета SDK для агентов применяются к событиям добавления и удаления прямых и косвенных элементов.

Добавленное событие участника

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

Событие удаления элемента

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

Обработка изменений массового членства в графе

При наличии массовых изменений членства Teams обуздает уведомления об обновлении отдельных участников, когда канал предоставляется или не предоставляется команде общего доступа. Чтобы уменьшить перегрузку уведомлений во время обновления членства, например при добавлении общего канала в команду с тысячами участников или удалении из нее, используйте sharedWithTeams ресурс подписки:

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

Подписка sharedWithTeams отправляет одно уведомление, если канал является общим или не предоставляется команде. Это позволяет избежать тысяч уведомлений на пользователя и повысить производительность приложений, которые отслеживают изменения членства. Убедитесь, что вы обновляете список участников общего канала с помощью API allMembers после получения общего с илиотмены общего доступа из команды уведомления.

Проверка доступа пользователей для обновлений членства в Графе

Когда приложение получает уведомление об удалении участника о непрямом обновлении членства, важно проверить, удален ли пользователь из канала, тем более что один и тот же пользователь может иметь как прямое, так и косвенное членство. Например, если пользователь удаляется из команды, которая предоставляет общий доступ к каналу, приложение должно подтвердить, отозван ли доступ пользователя к общему каналу. Используйте API, doesUserHaveAccess чтобы определить, удален ли пользователь из общего канала. Дополнительные сведения о доступе пользователей и соответствующих разрешениях см. в разделе API doesUserHaveAccess .

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

Когда приложение получает уведомление о добавленном участником оповещении о непрямом обновлении членства, ознакомьтесь с API allMembers , чтобы обновить список всех участников.

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

Классифицировать члены как в клиенте или в качестве внетенантного

Члены можно классифицировать как в клиенте или out-tenant, сравнивая TenantId член или команду следующим ownerTenantId образом:

1. TenantId Получите элемент, который требуется сравнить.

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

2. Вызовите microsoftTeams.app.getContext() вкладку из клиентской библиотеки JavaScript Teams. Вызов getContext() возвращает контекст общего канала, который содержит такие сведения, как displayName, membershipType, ownerGroupIdи ownerTenantId.

3. TenantId Сравните элемент со свойством ownerTenantId и определите, является ли элемент в клиенте или out-tenant.

Вернуться к началу

Общие сведения о разрешениях приложений в общих каналах

Вы можете сотрудничать с внешними участниками за пределами организации с помощью общих каналов. Разрешения приложений в общих каналах соответствуют списку приложений команды узла и политике приложений клиента узла.

Проверка установки бота в канале

При добавлении общего канала в другую команду пакет SDK для агентов conversationUpdate получает действие с помощью OnConversationUpdateActivityAsync метода , только если бот установлен в команде. Для проверка, если ваше приложение является частью канала, не существует выделенного API. Боты могут определять, когда приложение добавляется в канал косвенно.

Используйте это channelMemberAdded событие для активации логики для конкретного приложения, например:

• Отправка приветственного сообщения
• Получение списка каналов
• Настройка вкладок
• Запуск запланированных заданий

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

Проверка подлинности внешних пользователей для доступа к содержимому приложения в SharePoint

Выполните этот шаг, когда приложение сохраняет содержимое на сайте SharePoint клиента, в котором размещается канал, и запрашивает маркер SharePoint.

Теперь отправьте сохраненный getAuthToken узел tenantId внутри tenantId параметра вызова, чтобы разрешить межтенантным пользователям доступ к содержимому, размещенному на сайте SharePoint, подключенном к общему каналу.

Определение гостевых пользователей в каналах с помощью API Graph

Можно определить, является ли участник канала гостевым пользователем, приглашенным в клиент из внешней организации, с помощью roles свойства для каждого объекта в списке членов ответа канала .

Для гостей — roles = guest.

Чтобы точно получить всех гостевых пользователей в канале, используйте следующий allMembers API:

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

Этот API работает по стандартным и другим каналам и рекомендуется для надежной идентификации гостевых участников.

Доступ к данным SharePoint в общих и частных каналах

Если вы создаете приложение с помощью SharePoint Framework, необходимо использовать сайт SharePoint в Microsoft 365 (SPO), связанный с общим каналом, а не сайтом, связанным с группой главного разработчика. Как общий, так и частный каналы имеют собственный сайт SharePoint, к которому могут получить доступ только участники этого общего или частного канала.

Используйте API приглашения Microsoft Graph для доступа к библиотеке документов сайта SharePoint в Microsoft 365, связанного с общим или частным каналом.

Вернуться к началу

Доступ к хранилищу SharePoint для файлов канала с помощью API Graph

Чтобы получить доступ к корневому каталогу файлов SharePoint канала, используйте следующий API:

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

Этот API возвращает объект DriveItem для корневого каталога файлов этого канала. Дополнительные сведения см. в разделе Файлы канала.

Используйте следующие свойства для всех последующих операций с файлами:

• parentReference.driveId: идентификатор диска SharePoint для сайта канала.
• itemId: идентификатор папки для корневого каталога канала.

Ожидаемое поведение каналов на диске выглядит следующим образом:

• Standard каналы используют driveId сайта группы.
• Другие каналы используют отдельный driveId для отдельных сайтов.

Управление доступом к файлам для внешних или гостевых пользователей с помощью API Graph

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

Проверка подлинности внешних пользователей во вкладках или модулях задач

Когда вкладке или модулю задач требуется доступ к ресурсам SharePoint в домашнем клиенте канала, выполните следующие действия.

1. Обнаружение внешних пользователей Используйте getContext() для получения контекста канала. Сравните user.tenant.id с channel.ownerTenantId или channel.hostTenantId. Если они отличаются, пользователь является внешним.

2. Запрос маркера из домашнего клиента Вызовите getAuthToken() с идентификатором клиента внешнего пользователя (user.tenant.id или tid), чтобы убедиться, что маркер выдан из его домашнего клиента.

Вернуться к началу

Тестирование приложения в разных каналах

Перед публикацией обновлений убедитесь, что приложение правильно работает во всех типах каналов в реальных ситуациях.

Стандартный канал

Убедитесь, что существующие функции остаются неизменными после внесения изменений. Убедитесь, что вкладки, боты и расширения для обмена сообщениями продолжают работать должным образом.

Общий канал

Частный канал

Создайте частный канал в команде A по крайней мере с двумя участниками (владельцем и участником).

Чтобы проверить поддержку частного канала, выполните следующие действия.

1. Добавьте приложение в команду A, а затем добавьте его в частный канал.
2. Убедитесь, что вкладка загружается правильно в частном канале.
3. Протестируйте ответы бота для разных типов пользователей:
   • Член в клиенте
   • Гостевой или внешний пользователь
4. Если приложение выводит список участников или назначает задачи, убедитесь, что оно использует только участников канала, а не полную команду.
5. Добавьте нового участника в частный канал и проверка:
   • Получение приложением события изменения членства
   • Соответствует ли API членства новому участнику

Тестирование в этих сценариях помогает выявить любые проблемы с функциональностью, разрешениями и взаимодействием с пользователем.

Рекомендации по поддержке всех каналов

Что можно делать

• Прежде чем выполнять действия, всегда получайте список участников и роли текущего канала. Например, при отправке уведомлений или назначении задач нацеливаетесь только на фактических участников канала, а не на всю команду.
• Управление доступом к данным и совместное использование на основе членства в канале и разрешений. Дополнительные сведения см. в разделе Управление членством в каналах.
• Определите , являются ли пользователи внутренними, гостевыми или внешними (межтенантными), и выполните проверку подлинности в домашнем клиенте. Всегда проверяйте разрешения для сценариев с несколькими клиентами, особенно при доступе к файлам. Дополнительные сведения см. в статье Определение гостевых пользователей в каналах с помощью API Graph.
• Обновите текст справки и руководства пользователя , чтобы объяснить, как приложение ведет себя в разных типах каналов, включая любые ограничения для гостей или внешних пользователей.
• Ознакомьтесь с документацией и журналами изменений Teams , чтобы обеспечить соответствие последним обновлениям API, разрешений и конфигураций каналов.

Чего не следует делать

• Ограничьте конфиденциальные действия владельцами или внутренними пользователями и предложите гостям или внешним участникам ограниченные функции.
• Никогда не включайте данные частного канала в более широкие отчеты или общедоступные каналы, если только это не разрешено явным образом.

Вопросы и ответы

Вернуться к началу

Примеры кода

См. также

• Управление участием в каналах
• Общие сведения о разрешениях приложений в общих каналах
• Создание вкладок для Teams
• Общие каналы в Microsoft Teams
• Тип ресурса канала
• Политика хранения для расположений в Teams
• Использование гостевого и внешнего доступа для совместной работы с людьми из-за пределов организации
• Управление внешними собраниями и общение с людьми и организациями с помощью удостоверений Майкрософт