Obtención del contexto de Teams para la pestaña
La pestaña requiere información contextual para mostrar el contenido pertinente:
- Información básica sobre el usuario, el equipo o la empresa.
- Configuración regional e información del tema.
-
page.id
ypage.subPageId
que identifican lo que hay en esta pestaña (conocido comoentityId
ysubEntityId
antes de TeamsJS v2.0.0).
Contexto del usuario
El contexto sobre el usuario, el equipo o la empresa puede ser especialmente útil cuando:
- Crea o asocia recursos en la aplicación con el usuario o equipo especificados.
- Se inicia un flujo de autenticación desde microsoft Entra ID u otro proveedor de identidades y no es necesario que el usuario vuelva a escribir su nombre de usuario.
Para obtener más información, consulte Autenticación de un usuario en Microsoft Teams.
Importante
Aunque esta información de usuario puede ayudar a proporcionar una experiencia de usuario fluida, no debe usarla como prueba de identidad. Por ejemplo, un atacante puede cargar la página en un explorador y representar información o solicitudes dañinas.
Acceso a la información de contexto
Puede acceder a la información contextual de dos formas:
- Usar valores de marcador de posición de dirección URL.
- Desde el objeto de contexto de la biblioteca cliente JavaScript de Microsoft Teams.
Obtener contexto insertando valores de marcador de posición de dirección URL
Use marcadores de posición en la configuración o en las direcciones URL de contenido. Microsoft Teams reemplaza los marcadores de posición por valores pertinentes al determinar la configuración o la dirección URL real del contenido. Los marcadores de posición disponibles incluyen todos los campos del objeto de contexto . Los marcadores de posición comunes incluyen las siguientes propiedades:
-
{page.id}: identificador único definido por el desarrollador para la página definida al configurar la página por primera vez. (Conocido como
{entityId}
antes de TeamsJS v2.0.0). -
{page.subPageId}: el identificador único definido por el desarrollador para la subpágina que estos puntos de contenido definen al generar un vínculo profundo para un elemento específico dentro de la página. (Conocido como
{subEntityId}
antes de TeamsJS v2.0.0). -
{user.loginHint}: valor adecuado como sugerencia de inicio de sesión para microsoft entra id. Este suele ser el nombre de inicio de sesión del usuario actual en su inquilino principal. (Conocido como
{loginHint}
antes de TeamsJS v2.0.0). -
{user.userPrincipalName}: el nombre principal de usuario del usuario actual en el inquilino actual. (Conocido como
{userPrincipalName}
antes de TeamsJS v2.0.0). -
{user.id}: el identificador de objeto De Microsoft Entra del usuario actual en el inquilino actual. (Conocido como
{userObjectId}
antes de TeamsJS v2.0.0). -
{app.theme}: tema de la interfaz de usuario (UI) actual, como
default
,dark
ocontrast
. (Conocido como{theme}
antes de TeamsJS v2.0.0). -
{team.groupId}: el identificador del grupo de Microsoft 365 en el que reside la pestaña. (Conocido como
{groupId}
antes de TeamsJS v2.0.0) -
{user.tenant.id}: el identificador de inquilino de Microsoft Entra del usuario actual. (Conocido como
{tid}
antes de TeamsJS v2.0.0). -
{app.locale}: la configuración regional actual del usuario con formato languageId-countryId, por ejemplo
en-us
. (Conocido como{locale}
antes de TeamsJS v2.0.0).
Nota:
- El marcador de posición
{upn}
anterior está en desuso. Para la compatibilidad con versiones anteriores, es un sinónimo de{user.loginHint}
. - Las versiones móviles (Android e iOS) de Microsoft Teams solo admiten marcadores de posición TeamsJS v1.x.x.
Por ejemplo, en el manifiesto de la aplicación si establece el atributo "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}"
tab configurationUrl en y el usuario que ha iniciado sesión tiene los siguientes atributos:
- Su nombre de usuario es user@example.com.
- Su identificador de inquilino de empresa es e2653c-etcetera.
- Son miembros del grupo de Microsoft 365 con el identificador 00209384-etcetera.
- El usuario ha establecido su tema de Teams en oscuro.
Teams llama a la siguiente dirección URL al configurar la pestaña:
https://www.contoso.com/config?name=user@example.com&tenant=e2653c-etc&group=00209384-etc&theme=dark
Obtener contexto mediante la biblioteca JavaScript de Microsoft Teams
También puede recuperar la información de contexto mediante la biblioteca cliente javascript de Microsoft Teams.
La información se puede recuperar llamando a microsoftTeams.app.getContext().then((context) => {/*...*/});
.
El código siguiente proporciona un ejemplo de variable de contexto:
{
"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) => {
/*...*/
});
Patrón equivalente 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) => {
/*...*/
});
Patrón equivalente async/await
:
import { app, Context } from "@microsoft/teams-js";
async function example() {
const context = await app.getContext();
/*...*/
}
En la tabla siguiente se enumeran las propiedades de contexto usadas habitualmente del objeto de contexto :
Nombre de TeamsJS v2 | Nombre de TeamsJS v1 |
---|---|
team.internalId | teamId |
team.displayName | teamName |
channel.id | channelId |
channel.displayName | channelName |
chat.id | chatId |
app.locale | configuración regional |
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 | Id. de la reunión |
channel.defaultOneNoteSectionId | defaultOneNoteSectionId |
page.isMultiWindow | isMultiWindow |
Para obtener más información, vea Actualizaciones de la interfaz Context y la referencia de la API de interfaz de contexto.
Recuperar contexto en canales privados
Nota:
Los canales privados solo están en versión preliminar para desarrolladores privados.
Cuando la página de contenido se carga en un canal privado, los datos que recibe de la getContext
llamada se ofuscan para proteger la privacidad del canal.
Los campos siguientes se cambian cuando la página de contenido está en un canal privado:
-
team.groupId
: no definido para canales privados -
team.internalId
: se establece en el threadId del canal privado. -
team.displayName
: se establece en el nombre del canal privado. -
sharepointSite.url
: se establece en la dirección URL de un sitio de SharePoint único y distinto para el canal privado. -
sharepointSite.path
: se establece en la ruta de acceso de un sitio de SharePoint único y distinto para el canal privado. -
sharepointSite.domain
: se establece en el dominio de un dominio de sitio de SharePoint único y distinto para el canal privado. -
channel.ownerGroupId
: se establece en el groupId del equipo host del canal privado.
Si la página usa cualquiera de estos valores, el valor del channel.membershipType
campo debe ser Private
determinar si la página se carga en un canal privado y puede responder correctamente.
Nota:
teamSiteUrl
también funciona bien para los canales estándar. Si la página usa cualquiera de estos valores, el valor del channelType
campo debe ser Shared
determinar si la página se carga en un canal compartido y puede responder correctamente.
Obtener contexto en canales compartidos
Cuando la experiencia de usuario de contenido se cargue en un canal compartido, use los datos recibidos de getContext
la llamada para los cambios de canal compartido. Si tab usa cualquiera de los valores siguientes, debe rellenar el channelType
campo para determinar si la pestaña se carga en un canal compartido y responder correctamente.
En el caso de los canales compartidos, el groupId
valor es null
, ya que el groupId del equipo host no refleja con precisión la pertenencia verdadera del canal compartido. Para solucionar este problema, las hostTeamGroupID
propiedades y hostTenantID
se agregan recientemente y son útiles para realizar llamadas a La API de Microsoft Graph para recuperar la pertenencia.
hostTeam
hace referencia al equipo que creó el canal compartido.
currentTeam
hace referencia al equipo desde el que el usuario actual tiene acceso al canal compartido.
Para obtener más información sobre estos conceptos y canales compartidos, consulte Canales compartidos.
Use las siguientes getContext
propiedades en canales compartidos:
Propiedad | Descripción |
---|---|
channelId |
La propiedad se establece en el identificador de subproceso de canales compartidos. |
channelType |
La propiedad se establece en sharedChannel para canales compartidos. |
groupId |
La propiedad es null para canales compartidos. |
hostTenantId |
La propiedad se ha agregado recientemente y describe el identificador de inquilino del host, útil para compararla con la propiedad de identificador de inquilino del tid usuario actual. |
hostTeamGroupId |
La propiedad se ha agregado recientemente y describe el identificador de grupo microsoft entra del equipo host, útil para realizar llamadas a Microsoft Graph API para recuperar la pertenencia a canales compartidos. |
teamId |
La propiedad se agrega recientemente y se establece en el identificador de subproceso del equipo compartido actual. |
teamName |
La propiedad se establece en el equipo teamName compartido actual. |
teamType |
La propiedad se establece en el equipo teamType compartido actual. |
teamSiteUrl |
La propiedad describe la propiedad del channelSiteUrl canal compartido. |
teamSitePath |
La propiedad describe la propiedad del channelSitePath canal compartido. |
teamSiteDomain |
La propiedad describe la propiedad del channelSiteDomain canal compartido. |
tenantSKU |
La propiedad describe la propiedad del tenantSKU equipo host. |
tid |
La propiedad describe el identificador de inquilino del usuario actual. |
userObjectId |
La propiedad describe el identificador del usuario actual. |
userPrincipalName |
La propiedad describe el UPN del usuario actual. |
Para obtener más información sobre los canales compartidos, consulte canales compartidos.
Controlar el cambio de tema
Importante
- De forma predeterminada, el nuevo cliente de Teams admite el tema claro para las aplicaciones en reuniones de Teams. Cuando la propiedad de getContext
app.theme
API devuelve el valor, eldefault
cliente de Teams está en un tema claro. - La versión anterior de los clientes de Teams solo admite el tema Oscuro y Contraste para las aplicaciones de las reuniones de Teams.
Puede registrar la aplicación para que se le informe si el tema cambia llamando a microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ })
.
El theme
argumento de la función es una cadena con un valor de default
, dark
o contrast
.
Ejemplo de código
Ejemplo de nombre | Descripción | JavaScript |
---|---|---|
Contexto de canal de tabulación | En este ejemplo se muestra cómo usar el contenido del objeto de contexto de tabulación en un canal privado y compartido. | View |
Paso siguiente
Vea también
- Pestañas de compilación para Teams
- Diseñar la pestaña para Microsoft Teams
- Habilitación del inicio de sesión único para la aplicación de pestañas
- Canales compartidos de Microsoft Teams Connect
- Esquema del manifiesto de la aplicación de Teams
- Usar cuadros de diálogo en pestañas
- Presentación del nuevo cliente de Teams