Получение контекста для вкладки

  • Статья

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

  • Основные сведения о пользователе, команде или компании.
  • Сведения о языковом стандарте и теме.
  • page.subPageId И page.id , которые определяют, что находится на этой вкладке (известный как entityId и subEntityId до TeamsJS версии 2.0.0).

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

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

  • Вы создаете или связываете ресурсы в приложении с указанным пользователем или командой.
  • Вы инициируете поток проверки подлинности от Microsoft Entra ID или другого поставщика удостоверений и не требуете от пользователя повторно вводить свое имя пользователя.

Дополнительные сведения см. в статье Проверка подлинности пользователя в Microsoft Teams.

Важно!

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

Доступ к сведениям о контексте

Доступ к контекстной информации можно получить двумя способами:

Получение контекста путем вставки значений заполнителей URL-адреса

Используйте заполнители в конфигурации или в URL-адресах контента. Microsoft Teams заменяет заполнители соответствующими значениями, когда определяет фактическую конфигурацию или URL-адрес контента. Доступные заполнители включают все поля в объекте контекста . К общим заполнителям относятся следующие свойства:

  • {page.id}: определяемый разработчиком уникальный идентификатор страницы, определенной при первой настройке страницы. (Известен как {entityId} и раньше TeamsJS версии 2.0.0).
  • {page.subPageId}: определяемый разработчиком уникальный идентификатор для подстраничной страницы, определенной этим содержимым при создании глубокой ссылки на определенный элемент на странице. (Известен как {subEntityId} и раньше TeamsJS версии 2.0.0).
  • {user.loginHint}: значение, подходящее в качестве подсказки для входа для Microsoft Entra ID. Обычно это имя для входа текущего пользователя в домашнем клиенте. (Известен как {loginHint} и раньше TeamsJS версии 2.0.0).
  • {user.userPrincipalName}: имя участника-пользователя текущего пользователя в текущем клиенте. (Известен как {userPrincipalName} и раньше TeamsJS версии 2.0.0).
  • {user.id}: идентификатор объекта Microsoft Entra текущего пользователя в текущем клиенте. (Известен как {userObjectId} и раньше TeamsJS версии 2.0.0).
  • {app.theme}: тема текущего пользовательского интерфейса, например default, darkили contrast. (Известен как {theme} и раньше TeamsJS версии 2.0.0).
  • {team.groupId}: идентификатор группы Microsoft 365, в которой находится вкладка. (Известен как {groupId} и раньше TeamsJS версии 2.0.0)
  • {user.tenant.id}: идентификатор клиента Microsoft Entra текущего пользователя. (Известен как {tid} и раньше TeamsJS версии 2.0.0).
  • {app.locale}: текущий языковой стандарт пользователя, отформатированный как languageId-countryId, например en-us. (Известен как {locale} и раньше TeamsJS версии 2.0.0).

Примечание.

Предыдущий заполнитель {upn} теперь не поддерживается. Для обратной совместимости в настоящее время он является синонимом для {user.loginHint}.

Например, если для атрибута "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}" tab configurationUrl задано значение манифеста приложения, а у вошедшего пользователя есть следующие атрибуты:

  • Имя пользователя — user@example.com.
  • Идентификатор клиента компании — e2653c-etc.
  • Они члены группы Microsoft 365 с идентификатором 00209384 и т. д.
  • Пользователь задал темную тему Teams.

При настройке вкладки Teams вызывает следующий URL-адрес:

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

Получение контекста с помощью библиотеки JavaScript в Microsoft Teams

Вы также можете получить сведения о контексте с помощью клиентской библиотеки JavaScript в Microsoft Teams.

Сведения можно получить, вызвав .microsoftTeams.app.getContext().then((context) => {/*...*/});

В следующем коде приведен пример переменной контекста:

{
 "app": {
   "host": {
     "clientType": "The type of host client. Possible values are android, ios, web, desktop, surfaceHub, teamsRoomsAndroid, teamsPhones, teamsDisplays rigel (deprecated, use teamsRoomsWindows instead)",
     "name": "",
     "ringId": "The current ring ID",
     "sessionId": "The unique ID for the current Teams session for use in correlating telemetry data"    },
   "iconPositionVertical": "",
   "locale": "The current locale of the user formatted as languageId-countryId (for example, en-us)",
   "osLocaleInfo": "",
   "parentMessageId": "The parent message ID from which this dialog is launched",
   "sessionId": "The unique ID for the current session used for correlating telemetry data",
   "theme": "The current UI theme: default | dark | contrast",
   "userClickTime": "",
   "userFileOpenPreference": ""  },
 "channel": {
   "defaultOneNoteSectionId": "The OneNote section ID that is linked to the channel",
   "displayName": "The name of the current channel",
   "id": "The channel ID in the format 19:[id]@thread.skype",
   "membershipType": "",
   "ownerGroupId": "",
   "ownerTenantId": "",
   "relativeUrl": "The relative path to the SharePoint folder associated with the channel"  },
 "chat": { "id": "The chat ID in the format 19:[id]@thread.skype" },
 "meeting": {
   "id": "The meeting ID used by tab when running in meeting context"  },
 "page": {
   "frameContext": "The context where tab URL is loaded (for example, content, task, setting, remove, sidePanel)",
   "id": "The developer-defined unique ID for the entity this content points to",
   "isFullScreen": "Indicates if the tab is in full-screen",
   "isMultiWindow": "The indication whether the tab is in a pop out window",
   "sourceOrigin": "",
   "subPageId": "The developer-defined unique ID for the sub-entity this content points to"  },
 "sharepoint": "The SharePoint context is available only when hosted in SharePoint",
 "sharepointSite": {
   "domain": "The domain of the root SharePoint site associated with the team",
   "path": "The relative path to the SharePoint site associated with the team",
   "url": "The root SharePoint site associated with the team"  },
 "team": {
   "displayName": "The name of the current team",
   "groupId": "Guid identifying the current Office 365 Group ID",
   "internalId": "The Microsoft Teams ID in the format 19:[id]@thread.skype",
   "isArchived": "Indicates if team is archived",
   "templateId": "",
   "type": "The type of team",
   "userRole": "The user's role in the team"  },
 "user": {
   "displayName": "",
   "id": "The Azure AD object id of the current user, in the current tenant",
   "isCallingAllowed": "Indicates if calling is allowed for the current logged in user",
   "isPSTNCallingAllowed": "Indicates if PSTN calling is allowed for the current logged in user",
   "licenseType": "The license type for the current user. Possible values are E1, E3, and E5 enterprise plans",
   "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",
   "tenant": {
     "id": "The Azure AD tenant ID of the current user",
     "teamsSku": "The license type for the current user tenant. Possible values are enterprise, free, edu, unknown"    },
   "userPrincipalName": "The principal name of the current user, in the current tenant"  }
}

TypeScript

import { app, Context } from "@microsoft/teams-js";

app.getContext().then((context: Context) => {
    /*...*/
});

Эквивалентный async/await шаблон:

import { app, Context } from "@microsoft/teams-js";

async function example() {
  const context: Context = await app.getContext();
  /*...*/
}

JavaScript

import { app, Context } from "@microsoft/teams-js";

app.getContext().then((context) => {
    /*...*/
});

Эквивалентный async/await шаблон:

import { app, Context } from "@microsoft/teams-js";

async function example() {
  const context = await app.getContext();
  /*...*/
}

В следующей таблице перечислены часто используемые свойства контекста объекта контекста :

Имя TeamsJS версии 2 Имя TeamsJS версии 1
team.internalId teamId
team.displayName teamName
channel.id channelId
channel.displayName channelName
chat.id chatId
app.locale языковые стандарты
page.id entityId
page.subPageId subEntityId
user.loginHint loginHint
user.userPrincipalName Upn
user.id userObjectId
user.tenant.id Tid
team.groupId groupId
app.theme theme
page.isFullScreen isFullScreen
team.type teamType
sharepointSite.teamSiteUrl teamSiteUrl
sharepointSite.teamSiteDomain teamSiteDomain
sharepointSite.teamSitePath teamSitePath
channel.relativeUrl channelRelativeUrl
app.host.sessionId Sessionid
team.userRole userTeamRole
team.isArchived isTeamArchived
app.host.clientType hostClientType
page.frameContext frameContext
sharepoint sharepoint
user.tenant.teamsSku tenantSKU
user.licenseType userLicenseType
app.parentMessageId parentMessageId
app.host.ringId ringId
app.sessionId appSessionId
user.isCallingAllowed isCallingAllowed
user.isPSTNCallingAllowed isPSTNCallingAllowed
meeting.id meetingId
channel.defaultOneNoteSectionId defaultOneNoteSectionId
page.isMultiWindow isMultiWindow

Дополнительные сведения см. в разделе Обновления интерфейса контекста и справочник по API интерфейса контекста.

Получение контекста в частных каналах

Примечание.

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

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

Следующие поля изменяются, когда страница содержимого находится в частном канале:

  • team.groupId: не определено для частных каналов.
  • team.internalId: задайте значение threadId частного канала.
  • team.displayName: задайте имя частного канала.
  • sharepointSite.url: задайте URL-адрес уникального сайта SharePoint для частного канала.
  • sharepointSite.path: задайте путь к отдельному уникальному сайту SharePoint для частного канала.
  • sharepointSite.domain: задайте домен отдельного, уникального домена сайта SharePoint для частного канала.
  • channel.ownerGroupId: задайте для команды узла groupId частного канала.

Если страница использует любое из этих значений, значение channel.membershipType поля должно быть Private таким, чтобы определить, загружена ли ваша страница в частном канале и может ли она реагировать соответствующим образом.

Примечание.

teamSiteUrl также хорошо подходит для стандартных каналов. Если страница использует любое из этих значений, значение channelType поля должно быть Shared таким, чтобы определить, загружена ли ваша страница в общем канале и может ли она соответствующим образом реагировать.

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

При загрузке пользовательского интерфейса содержимого в общий канал используйте данные, полученные из getContext вызова, для изменения общего канала. Если вкладка использует любое из следующих значений, необходимо заполнить channelType поле, чтобы определить, загружена ли вкладка в общем канале, и ответить соответствующим образом. Для общих каналов groupId значение равно null, так как идентификатор groupId принимающей команды не точно отражает истинное членство в общем канале. Чтобы устранить эту проблему, hostTeamGroupID свойства и hostTenantID добавлены и полезны для выполнения вызовов Microsoft API Graph для получения членства. hostTeam ссылается на команду, создающую общий канал. currentTeam ссылается на команду, из которой текущий пользователь обращается к общему каналу.

Дополнительные сведения об этих понятиях и общих каналах см. в разделе Общие каналы.

Используйте следующие getContext свойства в общих каналах:

Свойство Описание
channelId Для свойства задается идентификатор потока общих каналов.
channelType Свойство имеет значение sharedChannel для общих каналов.
groupId Свойство предназначено null для общих каналов.
hostTenantId Свойство добавлено и описывает идентификатор клиента узла, полезное для сравнения со свойством идентификатора tid клиента текущего пользователя.
hostTeamGroupId Свойство добавлено и описывает идентификатор группы Microsoft Entra команды узла, который полезен для выполнения вызовов Microsoft API Graph для получения членства в общем канале.
teamId Свойство добавляется и задает идентификатор потока текущей общей команды.
teamName Для свойства задано значение текущей общей команды teamName.
teamType Для свойства задано значение текущей общей команды teamType.
teamSiteUrl Свойство описывает общий канал channelSiteUrl.
teamSitePath Свойство описывает общий канал channelSitePath.
teamSiteDomain Свойство описывает общий канал channelSiteDomain.
tenantSKU Свойство описывает tenantSKU.
tid Свойство описывает идентификатор клиента текущего пользователя.
userObjectId Свойство описывает идентификатор текущего пользователя.
userPrincipalName Свойство описывает имя участника-пользователя текущего пользователя.

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

Обработка изменения темы

Важно!

  • По умолчанию новый клиент Teams поддерживает светлую тему для приложений на собраниях Teams. app.theme Когда свойство в API getContext возвращает default значение, клиент Teams находится в светлой теме.
  • Более ранняя версия клиентов Teams поддерживала только темные и контрастные темы для приложений в собраниях Teams.

Вы можете зарегистрировать приложение, чтобы получить информацию о том, изменится ли тема, вызвав .microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ })

Аргумент theme в функции представляет собой строку со значением default, darkили contrast.

На следующем рисунке показан параметр темы по умолчанию в Teams:

Снимок экрана: тема по умолчанию в классическом клиенте Teams.

Пример кода

Название примера Описание JavaScript
Контекст канала tab В этом примере показано, как использовать содержимое объекта контекста вкладки в частном и общем канале. Просмотр

Следующий этап

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

См. также