Получение контекста для вкладки Microsoft TeamsGet context for your Microsoft Teams tab

Для отображения соответствующего контента на вкладке может потребоваться Контекстная информация.Your tab might require contextual information to display relevant content.

  • Для вкладки могут потребоваться основные сведения о пользователе, команде или компании.Your tab might need basic information about the user, team, or company.
  • Для вкладки может потребоваться информация о языковых стандартах и теме.Your tab might need locale and theme information.
  • На вкладке может потребоваться прочитать entityId или subEntityId определить, что находится на этой вкладке.Your tab might need to read the entityId or subEntityId that identifies what is in this tab.

Контекст пользователяUser context

Контекст пользователя, группы или компании особенно полезен приContext about the user, team or company can be especially useful when

  • Необходимо создать или связать ресурсы в приложении с указанным пользователем или группой.You need to create or associate resources in your app with the specified user or team.
  • Вы хотите инициировать процесс проверки подлинности для Azure Active Directory или другого поставщика удостоверений и не требовать от пользователя повторного ввода имени пользователя.You want to initiate an authentication flow against Azure Active Directory or other identity provider, and you don't want to require the user to enter their username again. (Дополнительные сведения о проверке подлинности на вкладке Microsoft Teams можно найти в разделе Проверка подлинности пользователя на вкладке Microsoft Teams.)(For more information on authenticating within your Microsoft Teams tab, see Authenticate a user in your Microsoft Teams tab.)

Важно!

Несмотря на то что эти сведения о пользователях помогают обеспечить гладкую работу пользователей, не следует использовать его для подтверждения подлинности.Although this user information can help provide a smooth user experience, you should not use it as proof of identity. Например, злоумышленник может загрузить страницу в «плохой браузер» и предоставить ей любую нужную информацию.For example, an attacker could you load your page in a "bad browser" and provide it with any information they want.

Доступ к контекстуAccessing context

Доступ к сведениям о контексте можно получить двумя способами:You can access context information in two ways:

Извлечение контекста путем вставки значений заполнители URL-адресовGetting context by inserting URL placeholder values

Используйте заполнители в URL-адресах конфигурации или контента.Use placeholders in your configuration or content URLs. Microsoft Teams заменяет заполнители соответствующими значениями при определении фактической конфигурации или URL-адреса контента, к которому выполняется переход.Microsoft Teams replaces the placeholders with the relevant values when determining the actual configuration or content URL to navigate to. Доступные заполнители включают все поля в объекте context .The available placeholders include all fields on the Context object. Общие заполнители включают в себя следующее:Common placeholders include the following:

  • {Ентитид}: идентификатор, указанный для элемента на этой вкладке при первой настройке вкладки.{entityId}: The ID you supplied for the item in this tab when first configuring the tab.
  • {Субентитид}: идентификатор, указанный при создании детальной ссылки для определенного элемента на этой вкладке. Используется для восстановления в определенном состоянии в пределах объекта; Например, прокрутите или активируйте определенный фрагмент содержимого.{subEntityId}: The ID you supplied when generating a deep link for a specific item within this tab. This should be used to restore to a specific state within an entity; for example, scrolling to or activating a specific piece of content.
  • {Логинхинт}: значение, которое подходит как подсказка для входа для Azure AD. Как правило, это имя входа текущего пользователя в его домашнем клиенте.{loginHint}: A value suitable as a login hint for Azure AD.This is usually the login name of the current user, in their home tenant.
  • {userPrincipalName}: имя участника пользователя текущего пользователя в текущем клиенте.{userPrincipalName}: The User Principal Name of the current user, in the current tenant.
  • {Усеробжектид}: идентификатор объекта Azure AD текущего пользователя в текущем клиенте.{userObjectId}: The Azure AD object ID of the current user, in the current tenant.
  • {Theme}: текущие темы пользовательского интерфейса, такие как default , dark или contrast .{theme}: The current UI theme such as default, dark, or contrast.
  • {groupId}: идентификатор группы Office 365, в которой находится вкладка.{groupId}: The ID of the Office 365 Group in which the tab resides.
  • {TID}: идентификатор клиента Azure AD для текущего пользователя.{tid}: The Azure AD tenant ID of the current user.
  • {locale}: текущий языковой стандарт пользователя, отформатированный как languageId-Каунтрид (например, EN-US).{locale}: The current locale of the user formatted as languageId-countryId (for example, en-us).
  • {Ослокалеинфо}: более подробные сведения о языковом стандарте из ОС пользователя, если они доступны.{osLocaleInfo}: More detailed locale info from the user's OS if available. Можно использовать вместе с:Can be used together with:
    • пакет @microsoft/ГЛОБЕ NPM, чтобы обеспечить соответствие приложения дате ОС пользователя иthe @microsoft/globe NPM package to ensure your app respects the user's OS date and
    • Конфигурация формата времени.time format configuration.
  • {sessionId}: уникальный идентификатор для текущего сеанса Teams, который будет использоваться для согласования данных телеметрии.{sessionId}: Unique ID for the current Teams session for use in correlating telemetry data.
  • {Чаннелид}: идентификатор Microsoft Teams для канала, с которым связан контент.{channelId}: The Microsoft Teams ID for the channel with which the content is associated.
  • {Чаннелнаме}: имя канала, с которым связан контент.{channelName}: The name for the channel with which the content is associated.
  • {Чатид}: идентификатор Microsoft Teams для чата, с которой связан контент.{chatId}: The Microsoft Teams ID for the chat with which the content is associated.
  • {URL}: URL-адрес контента этой вкладки.{url}: Content URL of this tab.
  • {Вебситеурл}: URL-адрес веб-сайта этой вкладки.{websiteUrl}: Website URL of this tab.
  • {Фаворитечаннелсонли}: флаг, позволяющий выбирать только избранные каналы.{favoriteChannelsOnly}: Flag allowing to select favorite channels only.
  • {Фаворитетеамсонли}: флаг, позволяющий выбрать только избранные команды.{favoriteTeamsOnly}: Flag allowing to select favorite teams only.
  • {Усертеамроле}: роль текущего пользователя в команде.{userTeamRole}: Role of current user in the team.
  • {Теамтипе}: тип команды.{teamType}: The type of the team.
  • {Истеамлоккед}: состояние блокировки команды.{isTeamLocked}: The locked status of the team.
  • {Истеамарчивед}: архивированный статус команды.{isTeamArchived}: The archived status of the team.
  • {Полнотекстовая}: указывает, находится ли вкладка в полноэкранном режиме.{isFullScreen}: Indication whether the tab is in full-screen mode.
  • {Теамситеурл}: корневой сайт SharePoint, связанный с командой.{teamSiteUrl}: The root SharePoint site associated with the team.
  • {Теамситедомаин}: домен корневого сайта SharePoint, связанного с командой.{teamSiteDomain}: The domain of the root SharePoint site associated with the team.
  • {Теамситепас}: относительный путь к сайту SharePoint, связанному с командой.{teamSitePath}: The relative path to the SharePoint site associated with the team.
  • {Чаннелрелативеурл}: относительный путь к папке SharePoint, связанной с каналом.{channelRelativeUrl}: The relative path to the SharePoint folder associated with the channel.
  • {Тенантску}: тип лицензии для текущего клиента пользователей.{tenantSKU}: The type of license for the current users tenant.
  • {Рингид}: текущий идентификатор звонка.{ringId}: Current ring ID.
  • {Аппсессионид}: уникальный идентификатор для текущего сеанса, который используется для согласования данных телеметрии.{appSessionId}: Unique ID for the current session for use in correlating telemetry data.
  • {Комплетионботид}: указывает идентификатор Bot для отправки результата взаимодействия пользователя с модулем задачи.{completionBotId}: Specifies a bot ID to send the result of the user's interaction with the task module.
  • {conversationId}: идентификатор беседы.{conversationId}: The Id of the conversation.
  • {Хостклиенттипе}: тип клиента узла. (Возможные значения: Android, iOS, Web, Desktop и рижел.){hostClientType}: Type of the host client.(Possible values are: android, ios, web, desktop, and rigel.)
  • {Фрамеконтекст}: контекст, в котором загружается URL-адрес вкладки (Content, Task, Setting, Remove, Сидепанел).{frameContext}: The context where the tab url is loaded (content, task, setting, remove, sidePanel).
  • {SharePoint}: этот компонент доступен только при размещении в SharePoint.{sharepoint}: This is only available when hosted in SharePoint.
  • {meetingId}: он используется вкладкой при запуске в контексте собрания.{meetingId}: It is used by tab when running in meeting context.
  • {Усерлиценсетипе} Тип лицензии для текущего пользователя.{userLicenseType} The license type for the current user.

Примечание

Предыдущий {upn} заполнитель теперь не является устаревшим.The previous {upn} placeholder is now deprecated. Для обратной совместимости он в настоящее время является синонимом {loginHint} .For backward compatibility, it is currently a synonym for {loginHint}.

Например, предположим, что в манифесте вкладки атрибуту присвоено значение configURLFor example, suppose in your tab manifest you set the configURL attribute to

"https://www.contoso.com/config?name={loginHint}&tenant={tid}&group={groupId}&theme={theme}"

И пользователь, вошедшего в систему, имеет следующие атрибуты:And the signed-in user has the following attributes:

  • Имя пользователя — "user@example.com"Their username is 'user@example.com'
  • Идентификатор клиента компании — "e2653c-and-etc"Their company tenant ID is 'e2653c-etc'
  • Они являются членами группы Office 365 с идентификатором ' 00209384 ' и т. д.They are a member of the Office 365 group with id '00209384-etc'
  • Тема Teams пользователя задается "темная"The user has set their Teams theme to 'dark'

При настройке вкладки Teams вызывает этот URL-адрес:When they configure your tab, Teams calls this URL:

https://www.contoso.com/config?name=user@example.com&tenant=e2653c-etc&group=00209384-etc&theme=dark

Извлечение контекста с помощью библиотеки JavaScript для Microsoft TeamsGetting context by using the Microsoft Teams JavaScript library

Вы также можете получить приведенные выше сведения с помощью пакета SDK для JavaScript для Microsoft Teams , вызвав microsoftTeams.getContext(function(context) { /* ... */ }) .You can also retrieve the information listed above using the Microsoft Teams JavaScript client SDK by calling microsoftTeams.getContext(function(context) { /* ... */ }).

Переменная контекста будет выглядеть так, как показано в следующем примере.The context variable will look like the following example.

{
    "teamId": "The Microsoft Teams ID in the format 19:[id]@thread.skype",
    "teamName": "The name of the current team",
    "channelId": "The channel ID in the format 19:[id]@thread.skype",
    "channelName": "The name of the current channel",
    "chatId": "The chat ID in the in the format 19:[id]@thread.skype",
    "locale": "The current locale of the user formatted as languageId-countryId (for example, en-us)",
    "entityId": "The developer-defined unique ID for the entity this content points to",
    "subEntityId": "The developer-defined unique ID for the sub-entity this content points to",
    "loginHint": "A value suitable as a login hint for Azure AD. This is usually the login name of the current user, in their home tenant",
    "userPrincipalName": "The User Principal Name of the current user, in the current tenant",
    "userObjectId": "The Azure AD object id of the current user, in the current tenant",
    "tid": "The Azure AD tenant ID of the current user",
    "groupId": "Guid identifying the current O365 Group ID",
    "theme": "The current UI theme: default | dark | contrast",
    "isFullScreen": "Indicates whether the tab is in full-screen mode",
    "userLicenseType": "Indicates the user licence type in the given SKU (for example, student or teacher)",
    "tenantSKU": "Indicates the SKU category of the tenant (for example, EDU)",
    "channelType": "microsoftTeams.ChannelType.Private | microsoftTeams.ChannelType.Regular"
}

Получение контекста в частных каналахRetrieving context in private channels

Примечание

В настоящее время частные каналы находятся в предварительной версии для разработчиков личных версий.Private channels are currently in private developer preview.

Когда страница контента загружается в частном канале, данные, получаемые из getContext вызова, будут замаскированы для защиты конфиденциальности канала.When your content page is loaded in a private channel, the data you receive from the getContext call will be obfuscated to protect the privacy of the channel. Следующие поля изменяются, когда страница контента находится в частном канале.The following fields are changed when your content page is in a private channel. Если страница использует любое из указанных ниже значений, необходимо проверить channelType поле, чтобы определить, загружена ли страница в частном канале, и ответить соответствующим образом.If your page makes use of any of the values below, you'll need to check the channelType field to determine if your page is loaded in a private channel, and respond appropriately.

  • groupId — Не определено для частных каналовgroupId - Undefined for private channels
  • teamId — Задает threadId для частного каналаteamId - Set to the threadId of the private channel
  • teamName — Укажите имя закрытого канала.teamName - Set to the name of the private channel
  • teamSiteUrl -Задать URL-адрес уникального уникального сайта SharePoint для частного каналаteamSiteUrl - Set to the URL of a distinct, unique SharePoint site for the private channel
  • teamSitePath -Задать путь к отдельному, уникальному сайту SharePoint для частного каналаteamSitePath - Set to the path of a distinct, unique SharePoint site for the private channel
  • teamSiteDomain — Укажите домен для частного канала в отдельном домене сайта SharePoint.teamSiteDomain - Set to the domain of a distinct, unique SharePoint site domain for the private channel

Обработка изменений темыTheme change handling

Вы можете зарегистрировать свое приложение, чтобы сообщить, изменяется ли тема с помощью вызова microsoftTeams.registerOnThemeChangeHandler(function(theme) { /* ... */ }) .You can register your app to be told if the theme changes by calling microsoftTeams.registerOnThemeChangeHandler(function(theme) { /* ... */ }).

themeАргумент в функции будет строкой со значением default , dark или contrast .The theme argument in the function will be a string with a value of default, dark, or contrast.