Kontext für Ihre Registerkarte erhalten

  • Artikel

Ihre Registerkarte erfordert Kontextinformationen, um relevante Inhalte anzuzeigen:

  • Grundlegende Informationen zum Benutzer, Team oder Unternehmen.
  • Gebietsschema- und Designinformationen.
  • Und page.idpage.subPageId , die identifizieren, was sich auf dieser Registerkarte befindet (bekannt als entityId und subEntityId vor TeamsJS v2.0.0).

Benutzerkontext

Kontext zum Benutzer, Team oder Unternehmen kann besonders nützlich sein, wenn:

  • Sie erstellen oder ordnen Ressourcen in Ihrer App dem angegebenen Benutzer oder Team zu.
  • Sie initiieren einen Authentifizierungsfluss von Microsoft Entra ID oder einem anderen Identitätsanbieter, und Sie verlangen nicht, dass der Benutzer seinen Benutzernamen erneut eingibt.

Weitere Informationen finden Sie unter Authentifizieren eines Benutzers in Microsoft Teams.

Wichtig

Obwohl diese Benutzerinformationen zu einer reibungslosen Benutzererfahrung beitragen können, dürfen Sie sie nicht als Identitätsnachweis verwenden. Beispielsweise kann ein Angreifer Ihre Seite in einem Browser laden und schädliche Informationen oder Anforderungen rendern.

Zugreifen auf Kontextinformationen

Sie können auf zwei Arten auf Kontextinformationen zugreifen:

Abrufen des Kontexts durch Einfügen von URL-Platzhalterwerten

Verwenden Sie Platzhalter in Ihren Konfigurations-oder Inhalts-URLs. Microsoft Teams ersetzt die Platzhalter durch die relevanten Werte, wenn die tatsächliche Konfigurations- oder Inhalts-URL ermittelt wird. Die verfügbaren Platzhalter enthalten alle Felder im Kontextobjekt . Allgemeine Platzhalter umfassen die folgenden Eigenschaften:

  • {page.id}: Die vom Entwickler definierte eindeutige ID für die Seite, die beim ersten Konfigurieren der Seite definiert wurde. (Bekannt als {entityId} vor TeamsJS v2.0.0).
  • {page.subPageId}: Die vom Entwickler definierte eindeutige ID für die Unterseite, auf die dieser Inhalt verweist, der beim Generieren eines Deep-Links für ein bestimmtes Element innerhalb der Seite definiert wurde. (Bekannt als {subEntityId} vor TeamsJS v2.0.0).
  • {user.loginHint}: Ein Wert, der als Anmeldehinweis für Microsoft Entra ID geeignet ist. Dies ist in der Regel der Anmeldename des aktuellen Benutzers in ihrem Basismandanten. (Bekannt als {loginHint} vor TeamsJS v2.0.0).
  • {user.userPrincipalName}: Der Benutzerprinzipalname des aktuellen Benutzers im aktuellen Mandanten. (Bekannt als {userPrincipalName} vor TeamsJS v2.0.0).
  • {user.id}: Die Microsoft Entra Objekt-ID des aktuellen Benutzers im aktuellen Mandanten. (Bekannt als {userObjectId} vor TeamsJS v2.0.0).
  • {app.theme}: Das aktuelle Design der Benutzeroberfläche ,, defaultdarkoder contrast. (Bekannt als {theme} vor TeamsJS v2.0.0).
  • {team.groupId}: Die ID der Microsoft 365-Gruppe, in der sich die Registerkarte befindet. (Bekannt als {groupId} vor TeamsJS v2.0.0)
  • {user.tenant.id}: Die Microsoft Entra Mandanten-ID des aktuellen Benutzers. (Bekannt als {tid} vor TeamsJS v2.0.0).
  • {app.locale}: Das aktuelle Gebietsschema des Benutzers, das als languageId-countryId formatiert ist, z. B en-us. . (Bekannt als {locale} vor TeamsJS v2.0.0).

Hinweis

  • Der bisherige Platzhalter {upn} ist nun veraltet. Aus Gründen der Abwärtskompatibilität ist es derzeit ein Synonym für {user.loginHint}.
  • Mobile Versionen (Android und iOS) von Microsoft Teams unterstützen derzeit nur TeamsJS v1.x.x-Platzhalter.

Wenn Sie beispielsweise in Ihrem App-Manifest ihr tab configurationUrl-Attribut auf "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}" festlegen und der angemeldete Benutzer über die folgenden Attribute verfügt:

  • Ihr Benutzername lautet user@example.com.
  • Ihre Unternehmensmandanten-ID lautet e2653c-etc.
  • Sie sind Mitglied der Microsoft 365-Gruppe mit der ID 00209384-etc.
  • Der Benutzer hat sein Teams-Design auf dunkel festgelegt.

Teams ruft beim Konfigurieren der Registerkarte die folgende URL auf:

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

Abrufen von Kontext mithilfe der JavaScript-Bibliothek von Microsoft Teams

Sie können die Kontextinformationen auch mithilfe der Microsoft Teams JavaScript-Clientbibliothek abrufen.

Die Informationen können durch Aufrufen microsoftTeams.app.getContext().then((context) => {/*...*/});von abgerufen werden.

Der folgende Code enthält ein Beispiel für eine Kontextvariable:

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

Entsprechendes async/await Muster:

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

Entsprechendes async/await Muster:

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

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

In der folgenden Tabelle sind häufig verwendete Kontexteigenschaften des Kontextobjekts aufgeführt:

TeamsJS v2-Name TeamsJS v1-Name
team.internalId teamId
team.displayName teamName
channel.id channelId
channel.displayName Channelname
chat.id chatId
app.locale Gebietsschema
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

Weitere Informationen finden Sie unter Updates zur Kontextschnittstelle und in der Referenz zur Kontextschnittstellen-API.

Abrufen des Kontexts in privaten Kanälen

Hinweis

Private Kanäle befinden sich derzeit nur in der privaten Entwicklervorschau.

Wenn Ihre Inhaltsseite in einem privaten Kanal geladen wird, werden die Daten, die getContext Sie vom Anruf erhalten, verschleiert, um die Privatsphäre des Kanals zu schützen.

Die folgenden Felder werden geändert, wenn sich Ihre Inhaltsseite in einem privaten Kanal befindet:

  • team.groupId: Für private Kanäle nicht definiert
  • team.internalId: Auf die ThreadId des privaten Kanals festgelegt
  • team.displayName: Auf den Namen des privaten Kanals festgelegt
  • sharepointSite.url: Auf die URL einer eindeutigen, eindeutigen SharePoint-Website für den privaten Kanal festgelegt
  • sharepointSite.path: Auf den Pfad einer eindeutigen, eindeutigen SharePoint-Website für den privaten Kanal festgelegt
  • sharepointSite.domain: Auf die Domäne einer eindeutigen, eindeutigen SharePoint-Websitedomäne für den privaten Kanal festgelegt
  • channel.ownerGroupId: Wird auf die Gruppen-ID des Hostteams des privaten Kanals festgelegt.

Wenn Ihre Seite einen dieser Werte verwendet, muss der Wert des channel.membershipType Felds lauten Private , um zu bestimmen, ob Ihre Seite in einem privaten Kanal geladen ist und entsprechend reagieren kann.

Hinweis

teamSiteUrl eignet sich auch gut für Standardkanäle. Wenn Ihre Seite einen dieser Werte verwendet, muss der Wert des channelType Felds lauten Shared , um zu bestimmen, ob Ihre Seite in einem freigegebenen Kanal geladen ist und entsprechend reagieren kann.

Abrufen von Kontext in freigegebenen Kanälen

Wenn die Inhalts-UX in einem freigegebenen Kanal geladen wird, verwenden Sie die vom Aufruf empfangenen Daten für Änderungen am getContext freigegebenen Kanal. Wenn tab einen der folgenden Werte verwendet, müssen Sie das channelType Feld auffüllen, um zu bestimmen, ob die Registerkarte in einem freigegebenen Kanal geladen ist, und entsprechend reagieren. Für freigegebene Kanäle ist nullder groupId Wert , da die groupId des Hostteams nicht genau die tatsächliche Mitgliedschaft des freigegebenen Kanals widerspiegelt. Um dies zu beheben, werden die hostTeamGroupID Eigenschaften und hostTenantID neu hinzugefügt und sind nützlich, um Microsoft Graph-API Aufrufe zum Abrufen der Mitgliedschaft auszuführen. hostTeam verweist auf das Team, das den freigegebenen Kanal erstellt hat. currentTeam verweist auf das Team, von dem der aktuelle Benutzer auf den freigegebenen Kanal zugreift.

Weitere Informationen zu diesen Konzepten und freigegebenen Kanälen finden Sie unter Freigegebene Kanäle.

Verwenden Sie die folgenden getContext Eigenschaften in freigegebenen Kanälen:

Eigenschaft Beschreibung
channelId Die -Eigenschaft ist auf die Thread-ID für freigegebene Kanäle festgelegt.
channelType Die -Eigenschaft ist für freigegebene Kanäle auf sharedChannel festgelegt.
groupId Die -Eigenschaft gilt null für freigegebene Kanäle.
hostTenantId Die -Eigenschaft wird neu hinzugefügt und beschreibt die Mandanten-ID des Hosts, die für den Vergleich mit der Mandanten-ID-Eigenschaft des tid aktuellen Benutzers nützlich ist.
hostTeamGroupId Die -Eigenschaft wurde neu hinzugefügt und beschreibt die Microsoft Entra Gruppen-ID des Hostteams, die nützlich ist, um Microsoft Graph-API Aufrufe zum Abrufen der Mitgliedschaft im freigegebenen Kanal auszuführen.
teamId Die -Eigenschaft wird neu hinzugefügt und auf die Thread-ID des aktuellen freigegebenen Teams festgelegt.
teamName Die -Eigenschaft ist auf die des aktuellen freigegebenen teamNameTeams festgelegt.
teamType Die -Eigenschaft ist auf die des aktuellen freigegebenen teamTypeTeams festgelegt.
teamSiteUrl Die -Eigenschaft beschreibt die des freigegebenen Kanals channelSiteUrl.
teamSitePath Die -Eigenschaft beschreibt die des freigegebenen Kanals channelSitePath.
teamSiteDomain Die -Eigenschaft beschreibt die des freigegebenen Kanals channelSiteDomain.
tenantSKU Die -Eigenschaft beschreibt die des Hostteams tenantSKU.
tid Die -Eigenschaft beschreibt die Mandanten-ID des aktuellen Benutzers.
userObjectId Die -Eigenschaft beschreibt die ID des aktuellen Benutzers.
userPrincipalName Die -Eigenschaft beschreibt den UPN des aktuellen Benutzers.

Weitere Informationen zu freigegebenen Kanälen finden Sie unter Freigegebene Kanäle.

Behandeln von Designänderungen

Wichtig

  • Standardmäßig unterstützt der neue Teams-Client das helle Design für Apps in Teams-Besprechungen. Wenn die Eigenschaft in der app.theme getContext-API den Wert zurückgibt, weist der default Teams-Client ein helles Design auf.
  • Frühere Versionen von Teams-Clients unterstützen nur das Design Dark und Contrast für Apps in Teams-Besprechungen.

Sie können Ihre App registrieren, um informiert zu werden, wenn sich das Design ändert, indem Sie aufrufen microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ }).

Das theme Argument in der Funktion ist eine Zeichenfolge mit dem Wert default, darkoder contrast.

Die folgende Abbildung zeigt die Standarddesignoption in Teams:

Screenshot: Standarddesign im Teams-Desktopclient

Codebeispiel

Beispielname Beschreibung JavaScript
Tabstoppkanalkontext In diesem Beispiel wird gezeigt, wie Sie den Inhalt des Tabstoppkontextobjekts in einem privaten und freigegebenen Kanal verwenden. View

Nächster Schritt

Erstellen von Registerkarten mit adaptiven Karten

Siehe auch