Obtenha contexto para sua guia

  • Artigo

Sua guia requer informações contextuais para exibir conteúdo relevante:

  • Informações básicas sobre o usuário, a equipe ou a empresa.
  • Informações de localidade e tema.
  • O page.id e page.subPageId que identificam o que está nesta guia (conhecido como entityId e subEntityId antes do TeamsJS v.2.0.0).

Contexto do usuário

O contexto sobre o usuário, a equipe ou a empresa pode ser especialmente útil quando:

  • Crie ou associe recursos em seu aplicativo com o usuário ou a equipe especificados.
  • Você inicia um fluxo de autenticação do Microsoft Entra ID ou de outro provedor de identidade e não exige que o usuário insira seu nome de usuário novamente.

Para obter mais informações, consulte autenticar um usuário no Microsoft Teams.

Importante

Embora essas informações de usuário possam ajudar a fornecer uma experiência suave do usuário, você não deve usá-la como prova de identidade. Por exemplo, um invasor pode carregar sua página em um navegador e renderizar informações ou solicitações prejudiciais.

Informações de contexto de acesso

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

Obter contexto inserindo valores de espaço reservado 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 espaços reservados disponíveis incluem todos os campos no objeto de contexto . Os espaços reservados comuns incluem as seguintes propriedades:

  • {page.id}: A ID exclusiva definida pelo desenvolvedor para a página definida ao configurar a página pela primeira vez. (Conhecido como {entityId} antes do TeamsJS v.2.0.0).
  • {page.subPageId}: A ID exclusiva definida pelo desenvolvedor para a subpage que esse conteúdo aponta definida ao gerar um link profundo para um item específico na página. (Conhecido como {subEntityId} antes do TeamsJS v.2.0.0).
  • {user.loginHint}: um valor adequado como uma dica de entrada para Microsoft Entra ID. Geralmente, esse é o nome de entrada do usuário atual em seu locatário doméstico. (Conhecido como {loginHint} antes do TeamsJS v.2.0.0).
  • {user.userPrincipalName}: o nome da entidade de usuário do usuário atual no locatário atual. (Conhecido como {userPrincipalName} antes do TeamsJS v.2.0.0).
  • {user.id}: A ID do objeto Microsoft Entra do usuário atual no locatário atual. (Conhecido como {userObjectId} antes do TeamsJS v.2.0.0).
  • {app.theme}: o tema da interface do usuário (interface do usuário) atual, como default, darkou contrast. (Conhecido como {theme} antes do TeamsJS v.2.0.0).
  • {team.groupId}: A ID do grupo Microsoft 365 no qual a guia reside. (Conhecido como {groupId} antes do TeamsJS v.2.0.0)
  • {user.tenant.id}: A ID do locatário Microsoft Entra do usuário atual. (Conhecido como {tid} antes do TeamsJS v.2.0.0).
  • {app.locale}: a localidade atual do usuário formatada como languageId-countryId, por exemplo en-us. (Conhecido como {locale} antes do TeamsJS v.2.0.0).

Observação

O espaço reservado {upn} anterior agora está preterido. Para compatibilidade com versões anteriores, é atualmente um sinônimo para {user.loginHint}.

Por exemplo, no manifesto do aplicativo, se você definir o atributo configurationUrl da "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}" guia como e o usuário conectado tiver os seguintes atributos:

  • Seu nome de usuário é user@example.com.
  • A ID do locatário da empresa é e2653c-etc.
  • Eles são membros do grupo microsoft 365 com ID 00209384-etc.
  • O usuário definiu seu tema do Teams como escuro.

O Teams chama a seguinte URL ao configurar a guia:

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

Obter contexto usando a biblioteca JavaScript do Microsoft Teams

Você também pode recuperar as informações de contexto usando a biblioteca de clientes JavaScript do Microsoft Teams.

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

O código a seguir 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 a seguir lista as propriedades de contexto comumente usadas 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, consulte Atualizações para a interface context e a referência da API de interface de contexto.

Recuperar contexto em canais privados

Observação

No momento, os canais privados estão apenas na versão prévia do desenvolvedor privado.

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

Os seguintes campos são alterados quando sua página de conteúdo está em um canal privado:

  • team.groupId: indefinido para canais privados
  • team.internalId: Defina como o threadId do canal privado
  • team.displayName: Definir como o nome do canal privado
  • sharepointSite.url: Defina como a URL de um site do SharePoint distinto e exclusivo para o canal privado
  • sharepointSite.path: Defina como o caminho de um site do SharePoint distinto e exclusivo para o canal privado
  • sharepointSite.domain: Defina como o domínio de um domínio de site do SharePoint distinto e exclusivo para o canal privado
  • channel.ownerGroupId: definido como o groupId da equipe de host do canal privado

Se sua página usa qualquer um desses valores, o valor do channel.membershipType campo deve ser Private para determinar se sua página está carregada em um canal privado e pode responder adequadamente.

Observação

teamSiteUrl também funciona bem para canais padrão. Se sua página usa qualquer um desses valores, o valor do channelType campo deve ser Shared para determinar se sua página está carregada em um canal compartilhado e pode responder adequadamente.

Obter contexto em canais compartilhados

Quando a UX de conteúdo for carregada em um canal compartilhado, use os dados recebidos da chamada para alterações de getContext canal compartilhado. Se a guia fizer uso de qualquer um dos valores a seguir, você deverá preencher o channelType campo para determinar se a guia está carregada em um canal compartilhado e responder adequadamente. Para canais compartilhados, o groupId valor é null, uma vez que o groupId da equipe do host não reflete com precisão a verdadeira associação do canal compartilhado. Para resolver isso, as hostTeamGroupID propriedades e hostTenantID são adicionadas recentemente e úteis para fazer chamadas do Microsoft API do Graph para recuperar a associação. hostTeam refere-se à Equipe que criou o canal compartilhado. currentTeam refere-se à Equipe da qual o usuário atual está acessando o canal compartilhado.

Para obter mais informações sobre esses conceitos e canais compartilhados, consulte canais compartilhados.

Use as seguintes getContext propriedades em canais compartilhados:

Propriedade Descrição
channelId A propriedade é definida como a ID do thread de canais compartilhados.
channelType A propriedade está definida como para sharedChannel canais compartilhados.
groupId A propriedade é null para canais compartilhados.
hostTenantId A propriedade foi adicionada recentemente e descreve a ID do locatário do host, útil para comparar com a propriedade de locatário do tid usuário atual.
hostTeamGroupId A propriedade foi adicionada recentemente e descreve a ID do grupo Microsoft Entra da equipe de host, útil para fazer chamadas do Microsoft API do Graph para recuperar a associação de canal compartilhado.
teamId A propriedade foi adicionada recentemente e definida como a ID do thread da equipe compartilhada atual.
teamName A propriedade está definida como teamName.
teamType A propriedade está definida como teamType.
teamSiteUrl A propriedade descreve o canal channelSiteUrlcompartilhado .
teamSitePath A propriedade descreve o canal channelSitePathcompartilhado .
teamSiteDomain A propriedade descreve o canal channelSiteDomaincompartilhado .
tenantSKU A propriedade descreve o tenantSKU.
tid A propriedade descreve a ID do locatário do usuário atual.
userObjectId A propriedade descreve a ID do usuário atual.
userPrincipalName A propriedade descreve o UPN do usuário atual.

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

Manipular alteração de tema

Importante

  • Por padrão, o novo cliente do Teams dá suporte a um tema leve para aplicativos em reuniões do Teams. Quando a app.theme propriedade na API getContext retorna o valor, o default cliente do Teams está no tema leve.
  • A versão anterior dos clientes do Teams só dá suporte ao tema Escuro e Contraste para aplicativos em reuniões do Teams.

Você pode registrar seu aplicativo para ser informado se o tema for alterado chamando microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ }).

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

A imagem a seguir mostra a opção de tema padrão no Teams:

A captura de tela mostra o tema padrão no cliente da área de trabalho do Teams.

Exemplo de código

Nome do exemplo Descrição JavaScript
Contexto do canal tab Este exemplo mostra como usar o conteúdo do objeto de contexto de guia em um canal privado e compartilhado. View

Próxima etapa

Criar guias com Cartões Adaptáveis

Confira também