タブのコンテキストを取得する
関連するコンテンツを表示するには、タブにコンテキスト情報が必要です。
- ユーザー、チーム、または会社に関する基本情報。
- ロケールとテーマの情報。
- このタブの内容を識別する
page.id
とpage.subPageId
(TeamsJS v2.0.0 より前のentityId
とsubEntityId
と呼ばれます)。
ユーザー コンテキスト
ユーザー、チーム、または会社に関するコンテキストは、次の場合に特に役立ちます。
- アプリ内のリソースを作成するか、指定したユーザーまたはチームに関連付けます。
- Microsoft Entra ID またはその他の ID プロバイダーから認証フローを開始し、ユーザーがユーザー名を再度入力する必要はありません。
詳細については、「 Microsoft Teamsでユーザーを認証する」を参照してください。
重要
このユーザー情報はスムーズなユーザー エクスペリエンスを提供するのに役立ちますが、ID 証明として使用しないでください。 たとえば、攻撃者はブラウザーにページを読み込み、有害な情報や要求をレンダリングすることができます。
アクセス コンテキスト情報
コンテキスト情報には 2 つの方法でアクセスできます。
- URL プレースホルダー値の使用。
- Microsoft Teams JavaScript クライアント ライブラリ コンテキスト オブジェクトから。
URL プレースホルダー値を挿入してコンテキストを取得する
構成やコンテンツ URL では、プレースホルダーを使用します。 Microsoft Teams では、実際の構成やコンテンツ URL を決定する際に、プレースホルダーを該当する値で置き換えます。 使用可能なプレースホルダーには、 コンテキスト オブジェクトのすべてのフィールドが含まれます。 一般的なプレースホルダーには、次のプロパティがあります。
-
{page.id}: 最初にページを構成するときに定義されたページの開発者が定義した一意 の ID。 (TeamsJS v2.0.0 より前の
{entityId}
と呼ばれます)。 -
{page.subPageId}: ページ内の特定のアイテムの ディープ リンク を生成するときに定義された、このコンテンツ ポイントのサブページの開発者が定義した一意の ID。 (TeamsJS v2.0.0 より前の
{subEntityId}
と呼ばれます)。 -
{user.loginHint}: Microsoft Entra ID のサインイン ヒントとして適した値。 これは通常、ホーム テナント内の現在のユーザーのサインイン名です。 (TeamsJS v2.0.0 より前の
{loginHint}
と呼ばれます)。 -
{user.userPrincipalName}: 現在のテナント内の現在のユーザーのユーザー プリンシパル名。 (TeamsJS v2.0.0 より前の
{userPrincipalName}
と呼ばれます)。 -
{user.id}: 現在のテナント内の現在のユーザーの Microsoft Entra オブジェクト ID。 (TeamsJS v2.0.0 より前の
{userObjectId}
と呼ばれます)。 -
{app.theme}:
default
、dark
、contrast
などの現在のユーザー インターフェイス (UI) テーマ。 (TeamsJS v2.0.0 より前の{theme}
と呼ばれます)。 -
{team.groupId}: タブが存在する Microsoft 365 グループの ID。 (TeamsJS v2.0.0 より前の
{groupId}
と呼ばれます) -
{user.tenant.id}: 現在のユーザーの Microsoft Entra テナント ID。 (TeamsJS v2.0.0 より前の
{tid}
と呼ばれます)。 -
{app.locale}:
en-us
など、languageId-countryId として書式設定されたユーザーの現在のロケール。 (TeamsJS v2.0.0 より前の{locale}
と呼ばれます)。
注:
- 以前の
{upn}
プレースホルダーは、現在では非推奨となっています。 下位互換性のために、{user.loginHint}
のシノニムです。 - Microsoft Teamsのモバイル (Android および iOS) バージョンでは、TeamsJS v1.x.x プレースホルダーのみがサポートされます。
たとえば、アプリ マニフェストで、tab configurationUrl 属性を "https://www.contoso.com/config?name={user.loginHint}&tenant={user.tenant.id}&group={team.groupId}&theme={app.theme}"
に設定し、サインインしているユーザーに次の属性がある場合です。
- ユーザー名は user@example.com。
- 会社のテナント ID は e2653c-etc です。
- これらは、ID 00209384-etc を持つ Microsoft 365 グループのメンバーです。
- ユーザーが Teams テーマを ダークに設定しました。
Teams は、タブを構成するときに次の URL を呼び出します。
https://www.contoso.com/config?name=user@example.com&tenant=e2653c-etc&group=00209384-etc&theme=dark
Microsoft Teams JavaScript ライブラリを使用してコンテキストを取得する
Microsoft Teams JavaScript クライアント ライブラリを使用してコンテキスト情報を取得することもできます。
情報は、 microsoftTeams.app.getContext().then((context) => {/*...*/});
を呼び出すことによって取得できます。
次のコードでは、コンテキスト変数の例を示します。
{
"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) => {
/*...*/
});
同等の 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) => {
/*...*/
});
同等の async/await
パターン:
import { app, Context } from "@microsoft/teams-js";
async function example() {
const context = await app.getContext();
/*...*/
}
次の表は、コンテキスト オブジェクトの一般的に使用される コンテキスト プロパティの一覧です。
TeamsJS v2 名 | TeamsJS v1 名 |
---|---|
team.internalId | teamId |
team.displayName | teamName |
channel.id | channelId |
channel.displayName | channelName |
chat.id | chatId |
app.locale | ロケール |
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 |
詳細については、「コンテキスト インターフェイスの更新」と「コンテキスト インターフェイス API リファレンス」を参照してください。
プライベート チャネルでコンテキストを取得する
注:
プライベート チャネルは、プライベート開発者プレビューのみです。
コンテンツ ページがプライベート チャネルに読み込まれると、 getContext
呼び出しから受信したデータは難読化され、チャネルのプライバシーが保護されます。
コンテンツ ページがプライベート チャネルにある場合、次のフィールドが変更されます。
-
team.groupId
: プライベート チャネルの場合は未定義 -
team.internalId
: プライベート チャネルの threadId に設定します -
team.displayName
: プライベート チャネルの名前に設定します -
sharepointSite.url
: プライベート チャネルの個別の一意の SharePoint サイトの URL に設定します -
sharepointSite.path
: プライベート チャネルの個別の一意の SharePoint サイトのパスに設定します -
sharepointSite.domain
: プライベート チャネルの個別の一意の SharePoint サイト ドメインのドメインに設定します -
channel.ownerGroupId
: プライベート チャネルのホスト チーム groupId に設定します
ページでこれらの値のいずれかを使用する場合は、 channel.membershipType
フィールドの値を Private
して、ページがプライベート チャネルに読み込まれ、適切に応答できるかどうかを判断する必要があります。
注:
teamSiteUrl
標準チャネルにも適しています。 ページでこれらの値のいずれかを使用する場合は、 channelType
フィールドの値を Shared
して、ページが共有チャネルに読み込まれ、適切に応答できるかどうかを判断する必要があります。
共有チャネルでコンテキストを取得する
コンテンツ UX が共有チャネルに読み込まれる場合は、共有チャネルの変更 getContext
呼び出しから受信したデータを使用します。 タブで次のいずれかの値を使用する場合は、 channelType
フィールドに値を設定して、タブが共有チャネルに読み込まれているかどうかを判断し、適切に応答する必要があります。
共有チャネルの場合、ホスト チームの groupId は共有チャネルの真のメンバーシップを正確に反映していないため、 groupId
値は null
されます。 これに対処するために、 hostTeamGroupID
プロパティと hostTenantID
プロパティが新しく追加され、メンバーシップを取得するための Microsoft Graph API 呼び出しを行う場合に便利です。
hostTeam
は、共有チャネルを作成したチームを指します。
currentTeam
は、現在のユーザーが共有チャネルにアクセスしている Team を指します。
これらの概念と共有チャネルの詳細については、「 共有チャネル」を参照してください。
共有チャネルでは、次の getContext
プロパティを使用します。
プロパティ | 説明 |
---|---|
channelId |
プロパティは、共有チャネル スレッド ID に設定されます。 |
channelType |
プロパティは、共有チャネルの sharedChannel に設定されます。 |
groupId |
プロパティは、共有チャネルに対して null されます。 |
hostTenantId |
プロパティが新しく追加され、ホストのテナント ID が記述され、現在のユーザーの tid テナント ID プロパティと比較するのに役立ちます。 |
hostTeamGroupId |
プロパティが新しく追加され、ホスト チームの Microsoft Entra グループ ID が記述されています。共有チャネル メンバーシップを取得するために Microsoft Graph API 呼び出しを行う場合に便利です。 |
teamId |
プロパティが新しく追加され、現在の共有チームのスレッド ID に設定されます。 |
teamName |
プロパティは、現在の共有チームの teamName に設定されます。 |
teamType |
プロパティは、現在の共有チームの teamType に設定されます。 |
teamSiteUrl |
プロパティは、共有チャネルの channelSiteUrl について説明します。 |
teamSitePath |
プロパティは、共有チャネルの channelSitePath について説明します。 |
teamSiteDomain |
プロパティは、共有チャネルの channelSiteDomain について説明します。 |
tenantSKU |
プロパティは、ホスト チームの tenantSKU について説明します。 |
tid |
プロパティは、現在のユーザーのテナント ID を記述します。 |
userObjectId |
プロパティは、現在のユーザーの ID を記述します。 |
userPrincipalName |
プロパティは、現在のユーザーの UPN について説明します。 |
共有チャネルの詳細については、「共有 チャネル」を参照してください。
テーマの変更を処理する
重要
- 既定では、 新しい Teams クライアントは Teams 会議のアプリのライト テーマをサポートします。 getContext API の
app.theme
プロパティがdefault
値を返すと、Teams クライアントは淡色テーマになります。 - 以前のバージョンの Teams クライアントでは、Teams 会議でアプリのダーク テーマとコントラスト テーマのみがサポートされています。
テーマが変更された場合に通知されるようにアプリを登録するには、 microsoftTeams.app.registerOnThemeChangeHandler(function(theme) { /* ... */ })
を呼び出します。
関数の theme
引数は、 default
、 dark
、または contrast
の値を持つ文字列です。
コード サンプル
サンプルの名前 | 説明 | JavaScript |
---|---|---|
タブ チャネル コンテキスト | このサンプルでは、プライベートおよび共有チャネルでタブ コンテキスト オブジェクトの内容を使用する方法を示します。 | 表示 |
次の手順
関連項目
Platform Docs