Obter contexto para a guia do Microsoft TeamsGet context for your Microsoft Teams tab

Sua guia pode exigir informações contextuais para exibir conteúdo relevante.Your tab might require contextual information to display relevant content.

  • Sua guia pode precisar de informações básicas sobre o usuário, a equipe ou a empresa.Your tab might need basic information about the user, team, or company.
  • Sua guia pode precisar de informações de localidade e tema.Your tab might need locale and theme information.
  • Sua guia pode precisar ler o entityId ou subEntityId que identifica o que está nesta guia.Your tab might need to read the entityId or subEntityId that identifies what is in this tab.

Contexto de usuárioUser context

O contexto sobre o usuário, a equipe ou a empresa pode ser especialmente útil quandoContext about the user, team or company can be especially useful when

  • Você precisa criar ou associar recursos em seu aplicativo com o usuário ou equipe especificado.You need to create or associate resources in your app with the specified user or team.
  • Você deseja iniciar um fluxo de autenticação no Azure Active Directory ou outro provedor de identidade e não quer exigir que o usuário insira o nome de usuário novamente.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. (Para obter mais informações sobre como autenticar na guia Microsoft Teams, confira autenticar um usuário em sua guia do Microsoft Teams.)(For more information on authenticating within your Microsoft Teams tab, see Authenticate a user in your Microsoft Teams tab.)

Importante

Embora essas informações do usuário possam ajudar a fornecer uma experiência de usuário tranqüila, você não deve usá-la como prova de identidade.Although this user information can help provide a smooth user experience, you should not use it as proof of identity. Por exemplo, um invasor pode carregar sua página em um "navegador inválido" e fornecer qualquer informação que desejar.For example, an attacker could you load your page in a "bad browser" and provide it with any information they want.

Contexto de acessoAccessing context

Você pode acessar informações de contexto de duas maneiras:You can access context information in two ways:

Obtendo contexto inserindo valores de espaço reservado de URLGetting context by inserting URL placeholder values

Use espaços reservados em suas configurações ou URLs de conteúdo.Use placeholders in your configuration or content URLs. O Microsoft Teams substitui os espaços reservados pelos valores relevantes ao determinar a configuração real ou a URL de conteúdo para navegar.Microsoft Teams replaces the placeholders with the relevant values when determining the actual configuration or content URL to navigate to. Os espaços reservados disponíveis incluem todos os campos no objeto Context .The available placeholders include all fields on the Context object. Os espaços reservados comuns incluem o seguinte:Common placeholders include the following:

  • {EntityId}: a ID que você forneceu para o item nesta guia quando configura a guiapela primeira vez.{entityId}: The ID you supplied for the item in this tab when first configuring the tab.
  • {subentityid}: a ID que você forneceu ao gerar um link profundo para um item específico dentro dessa guia. Isso deve ser usado para restaurar um estado específico dentro de uma entidade; por exemplo, rolar ou ativar uma parte específica do conteúdo.{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.
  • {loginHint}: um valor adequado como uma dica de logon para o Azure AD. Em geral, esse é o nome de logon do usuário atual em seu locatário inicial.{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}: o nome principal de usuário do usuário atual, no locatário atual.{userPrincipalName}: The User Principal Name of the current user, in the current tenant.
  • {userobjectid}: a ID de objeto do Azure AD do usuário atual, no locatário atual.{userObjectId}: The Azure AD object ID of the current user, in the current tenant.
  • {Theme}: o tema atual da interface do usuário, como default , dark ou contrast .{theme}: The current UI theme such as default, dark, or contrast.
  • {GroupId}: a ID do grupo do Office 365 em que a guia reside.{groupId}: The ID of the Office 365 Group in which the tab resides.
  • {tid}: a ID do locatário do Azure AD do usuário atual.{tid}: The Azure AD tenant ID of the current user.
  • {locale}: a localidade atual do usuário formatada como LanguageID-countryId (por exemplo, en-US).{locale}: The current locale of the user formatted as languageId-countryId (for example, en-us).

Observação

O {upn} espaço reservado anterior agora é preterido.The previous {upn} placeholder is now deprecated. Para compatibilidade com versões anteriores, no momento é sinônimo de {loginHint} .For backward compatibility, it is currently a synonym for {loginHint}.

Por exemplo, suponha que, em seu manifesto de guia, você defina o configURL atributo comoFor 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}"

E o usuário conectado tem os seguintes atributos:And the signed-in user has the following attributes:

  • O nome de usuário é ' user@example.com 'Their username is 'user@example.com'
  • A ID de locatário da empresa é ' e2653c-etc 'Their company tenant ID is 'e2653c-etc'
  • Eles são membros do grupo do Office 365 com a ID ' 00209384-etc 'They are a member of the Office 365 group with id '00209384-etc'
  • O usuário definiu o tema da equipe como ' escuro 'The user has set their Teams theme to 'dark'

Ao configurar sua guia, o Teams chama esta 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

Obtendo contexto usando a biblioteca JavaScript do Microsoft TeamsGetting context by using the Microsoft Teams JavaScript library

Você também pode recuperar as informações listadas acima usando o SDK do cliente JavaScript do Microsoft Teams chamando 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) { /* ... */ }).

A variável de contexto se parecerá com o exemplo a seguir.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"
}

Recuperando contexto em canais privadosRetrieving context in private channels

Observação

Os canais privados estão atualmente na visualização do desenvolvedor privado.Private channels are currently in private developer preview.

Quando a página de conteúdo é carregada em um canal privado, os dados recebidos da getContext chamada serão ofuscados para proteger a privacidade do canal.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. Os campos a seguir são alterados quando a página de conteúdo está em um canal privado.The following fields are changed when your content page is in a private channel. Se a página utiliza qualquer um dos valores abaixo, você precisará verificar o channelType campo para determinar se a página está carregada em um canal privado e responder de forma adequada.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-Undefined para canais privadosgroupId - Undefined for private channels
  • teamId-Definir o threadId do canal privadoteamId - Set to the threadId of the private channel
  • teamName-Definir o nome do canal privadoteamName - Set to the name of the private channel
  • teamSiteUrl-Definir como a URL de um site distinto exclusivo do SharePoint para o canal privadoteamSiteUrl - Set to the URL of a distinct, unique SharePoint site for the private channel
  • teamSitePath-Definir como o caminho de um site exclusivo do SharePoint distinto para o canal privadoteamSitePath - Set to the path of a distinct, unique SharePoint site for the private channel
  • teamSiteDomain-Definir para o domínio de um domínio de site do SharePoint distinto e exclusivo para o canal privadoteamSiteDomain - Set to the domain of a distinct, unique SharePoint site domain for the private channel

Tratamento de alterações de temasTheme change handling

Você pode registrar seu aplicativo para ser informado se o tema for alterado por chamada microsoftTeams.registerOnThemeChangeHandler(function(theme) { /* ... */ }) .You can register your app to be told if the theme changes by calling microsoftTeams.registerOnThemeChangeHandler(function(theme) { /* ... */ }).

O theme argumento na função será uma cadeia de caracteres com um valor de default , dark ou contrast .The theme argument in the function will be a string with a value of default, dark, or contrast.