Compartilhar via

Obtenha contexto para sua guia

  • Artigo

O separador requer informações contextuais para apresentar conteúdo relevante:

  • Informações básicas sobre o utilizador, a equipa ou a empresa.
  • Informações de região e tema.
  • page.subPageId E page.id que identificam o que está neste separador (conhecido como entityId e subEntityId antes do TeamsJS v2.0.0).

Contexto do usuário

O contexto sobre o utilizador, a equipa ou a empresa pode ser especialmente útil quando:

  • Pode criar ou associar recursos na sua aplicação ao utilizador ou equipa especificado.
  • Inicia um fluxo de autenticação a partir do Microsoft Entra ID ou de outro fornecedor de identidade e não exige que o utilizador introduza novamente o respetivo nome de utilizador.

Para obter mais informações, consulte Autenticar um utilizador no seu Microsoft Teams.

Importante

Embora estas informações de utilizador possam ajudar a proporcionar uma experiência de utilizador suave, não pode utilizá-la como prova de identidade. Por exemplo, um atacante pode carregar a sua página num browser e compor informações ou pedidos prejudiciais.

Informações de contexto do Access

Você pode acessar informações de contexto de duas maneiras:

Obter contexto ao inserir valores de marcador de posição de URL

Usar espaços reservados em sua configuração ou URLs de conteúdo. O Microsoft Teams substitui os espaços reservados pelos valores relevantes ao determinar a configuração real ou o URL do conteúdo. Os marcadores de posição disponíveis incluem todos os campos no objeto de contexto . Os marcadores de posição comuns incluem as seguintes propriedades:

  • {page.id}: O ID exclusivo definido pelo programador para a página definida ao configurar a página pela primeira vez. (Conhecido como {entityId} antes do TeamsJS v2.0.0).
  • {page.subPageId}: O ID exclusivo definido pelo programador para a subpágina que estes pontos de conteúdo definiram ao gerar uma ligação avançada para um item específico na página. (Conhecido como {subEntityId} antes do TeamsJS v2.0.0).
  • {user.loginHint}: um valor adequado como uma sugestão de início de sessão para o ID do Microsoft Entra. Normalmente, este é o nome de início de sessão do utilizador atual no respetivo inquilino. (Conhecido como {loginHint} antes do TeamsJS v2.0.0).
  • {user.userPrincipalName}: o Nome Principal de Utilizador do utilizador atual no inquilino atual. (Conhecido como {userPrincipalName} antes do TeamsJS v2.0.0).
  • {user.id}: O ID de objeto do Microsoft Entra do utilizador atual no inquilino atual. (Conhecido como {userObjectId} antes do TeamsJS v2.0.0).
  • {app.theme}: o tema atual da interface de utilizador (IU), como default, darkou contrast. (Conhecido como {theme} antes do TeamsJS v2.0.0).
  • {team.groupId}: O ID do grupo do Microsoft 365 no qual o separador reside. (Conhecido como {groupId} antes do TeamsJS v2.0.0)
  • {user.tenant.id}: O ID de inquilino do Microsoft Entra do utilizador atual. (Conhecido como {tid} antes do TeamsJS v2.0.0).
  • {app.locale}: a região atual do utilizador formatada como languageId-countryId, por exemplo en-us. (Conhecido como {locale} antes do TeamsJS v2.0.0).

Observação

  • O espaço reservado {upn} anterior agora está preterido. Para retrocompatibilidade, é um sinónimo para {user.loginHint}.
  • As versões móveis (Android e iOS) do Microsoft Teams suportam apenas marcadores de posição do TeamsJS v1.x.x.

Por exemplo, no manifesto da aplicação, se definir o atributo "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}"configurationUrl do separador como e o utilizador com sessão iniciada tiver os seguintes atributos:

  • O nome de utilizador é user@example.com.
  • O ID de inquilino da empresa é e2653c-etc.
  • São membros do grupo do Microsoft 365 com o ID 00209384-etc.
  • O utilizador definiu o tema do Teams como escuro.

O Teams chama o seguinte URL ao configurar o separador:

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

Obter contexto com a biblioteca JavaScript do Microsoft Teams

Também pode obter as informações de contexto com a biblioteca de cliente JavaScript do Microsoft Teams.

As informações podem ser obtidas ao chamar microsoftTeams.app.getContext().then((context) => {/*...*/});.

O código seguinte fornece um exemplo de variável 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) => {
    /*...*/
});

Padrão 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) => {
    /*...*/
});

Padrão equivalente async/await :

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

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

A tabela seguinte lista as propriedades de contexto utilizadas frequentemente do objeto de contexto :

Nome do TeamsJS v2 Nome do TeamsJS v1
team.internalId teamId
team.displayName teamName
channel.id channelId
channel.displayName channelName
chat.id chatId
app.locale localidade
page.id entityId
page.subPageId subEntityId
user.loginHint loginHint
user.userPrincipalName upn
user.id userObjectId
user.tenant.id tid
team.groupId groupId
app.theme tema
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

Para obter mais informações, veja Updates to the Context interface and the Context interface API reference (Atualizações à interface de contexto e à Referência da API da interface de contexto).

Obter contexto em canais privados

Observação

Os canais privados estão apenas em pré-visualização privada para programadores.

Quando a sua página de conteúdo é carregada num canal privado, os dados que recebe da getContext chamada são ocultados para proteger a privacidade do canal.

Os seguintes campos são alterados quando a página de conteúdo está num canal privado:

  • team.groupId: Indefinido para canais privados
  • team.internalId: definido como o threadId do canal privado
  • team.displayName: defina como o nome do canal privado
  • sharepointSite.url: defina para o URL de um site sharePoint exclusivo e distinto para o canal privado
  • sharepointSite.path: defina para o caminho de um site sharePoint exclusivo e distinto para o canal privado
  • sharepointSite.domain: definido como o domínio de um domínio de site do SharePoint exclusivo e distinto para o canal privado
  • channel.ownerGroupId: Definido para o groupId da equipa de anfitriões do canal privado

Se a sua página utilizar qualquer um destes valores, o valor do campo tem de channel.membershipType ser Private para determinar se a sua página é carregada num canal privado e pode responder adequadamente.

Observação

teamSiteUrl também funciona bem para canais padrão. Se a sua página utilizar qualquer um destes valores, o valor do campo tem de channelType ser Shared para determinar se a sua página é carregada num canal partilhado e pode responder adequadamente.

Obter contexto em canais partilhados

Quando a EXPERIÊNCIA de conteúdo é carregada num canal partilhado, utilize os dados recebidos da getContext chamada para alterações de canais partilhados. Se o separador utilizar qualquer um dos seguintes valores, tem de preencher o channelType campo para determinar se o separador é carregado num canal partilhado e responder adequadamente. Para canais partilhados, o groupId valor é null, uma vez que o groupId da equipa anfitriã não reflete com precisão a verdadeira associação do canal partilhado. Para resolver este problema, as hostTeamGroupID propriedades e hostTenantID são adicionadas recentemente e são úteis para fazer chamadas à Microsoft Graph API para obter a associação. hostTeam refere-se à Equipa que criou o canal partilhado. currentTeam refere-se à Equipa a partir da qual o utilizador atual está a aceder ao canal partilhado.

Para obter mais informações sobre estes conceitos e canais partilhados, consulte canais partilhados.

Utilize as seguintes getContext propriedades em canais partilhados:

Propriedade Descrição
channelId A propriedade está definida para o ID de thread de canais partilhados.
channelType A propriedade está definida como sharedChannel para canais partilhados.
groupId A propriedade destina-se null a canais partilhados.
hostTenantId A propriedade foi adicionada recentemente e descreve o ID de inquilino do anfitrião, útil para comparar com a propriedade ID de inquilino do tid utilizador atual.
hostTeamGroupId A propriedade foi adicionada recentemente e descreve o ID de grupo do Microsoft Entra da equipa anfitriã, útil para fazer chamadas à Microsoft Graph API para obter a associação a canais partilhados.
teamId A propriedade é adicionada recentemente e definida para o ID de thread da equipa partilhada atual.
teamName A propriedade está definida para a equipa teamNamepartilhada atual.
teamType A propriedade está definida para a equipa teamTypepartilhada atual.
teamSiteUrl A propriedade descreve o canal channelSiteUrlpartilhado .
teamSitePath A propriedade descreve o canal channelSitePathpartilhado .
teamSiteDomain A propriedade descreve o canal channelSiteDomainpartilhado .
tenantSKU A propriedade descreve o tenantSKU.
tid A propriedade descreve o ID de inquilino do utilizador atual.
userObjectId A propriedade descreve o ID do utilizador atual.
userPrincipalName A propriedade descreve o UPN do utilizador atual.

Para obter mais informações sobre canais partilhados, consulte canais partilhados.

Processar a alteração do tema

Importante

  • Por predefinição, o novo cliente do Teams suporta um tema claro para aplicações em reuniões do Teams. Quando a app.theme propriedade na API getContext devolve o valor, o default cliente do Teams está no tema claro.
  • A versão anterior dos clientes do Teams só suporta o tema Escuro e Contraste para aplicações em reuniões do Teams.

Pode registar a sua aplicação para ser informado se o tema for alterado ao chamar microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ }).

O theme argumento na função é uma cadeia com um valor de default, darkou contrast.

A imagem seguinte mostra a opção de tema predefinida no Teams:

Captura de ecrã a mostrar o tema predefinido no cliente de ambiente de trabalho do Teams.

Exemplo de código

Nome do exemplo Descrição JavaScript
Contexto do canal de tabulação Este exemplo mostra como utilizar os conteúdos do objeto de contexto de separador num canal privado e partilhado. View

Próxima etapa

Criar guias com Cartões Adaptáveis

Confira também