タブのコンテキストを取得する

  • [アーティクル]

関連するコンテンツを表示するには、タブにコンテキスト情報が必要です。

  • ユーザー、チーム、または会社に関する基本情報。
  • ロケールとテーマの情報。
  • page.idこのタブの内容を識別する と page.subPageId (TeamsJS v.2.0.0 以前とsubEntityId呼ばれますentityId)。

ユーザー コンテキスト

ユーザー、チーム、または会社に関するコンテキストは、次の場合に特に役立ちます。

  • アプリ内のリソースを作成するか、指定したユーザーまたはチームに関連付けます。
  • Microsoft Entra IDまたはその他の ID プロバイダーから認証フローを開始し、ユーザーがユーザー名を再度入力する必要はありません。

詳細については、「 Microsoft Teams でユーザーを認証する」を参照してください。

重要

このユーザー情報はスムーズなユーザー エクスペリエンスを提供するのに役立ちますが、ID 証明として使用しないでください。 たとえば、攻撃者はブラウザーにページを読み込み、有害な情報や要求をレンダリングすることができます。

アクセス コンテキスト情報

コンテキスト情報には 2 つの方法でアクセスできます。

URL プレースホルダー値を挿入してコンテキストを取得する

構成やコンテンツ URL では、プレースホルダーを使用します。 Microsoft Teams では、実際の構成やコンテンツ URL を決定する際に、プレースホルダーを該当する値で置き換えます。 使用可能なプレースホルダーには、 コンテキスト オブジェクトのすべてのフィールドが含まれます。 一般的なプレースホルダーには、次のプロパティがあります。

  • {page.id}: 最初にページを構成するときに定義されたページの開発者が定義した一意 の ID。 (TeamsJS v.2.0.0 より前と呼ばれます {entityId} )。
  • {page.subPageId}: ページ内の特定のアイテムの ディープ リンク を生成するときに定義された、このコンテンツ ポイントのサブページの開発者が定義した一意の ID。 (TeamsJS v.2.0.0 より前と呼ばれます {subEntityId} )。
  • {user.loginHint}: Microsoft Entra IDのサインイン ヒントとして適した値。 これは通常、ホーム テナント内の現在のユーザーのサインイン名です。 (TeamsJS v.2.0.0 より前と呼ばれます {loginHint} )。
  • {user.userPrincipalName}: 現在のテナント内の現在のユーザーのユーザー プリンシパル名。 (TeamsJS v.2.0.0 より前と呼ばれます {userPrincipalName} )。
  • {user.id}: 現在のテナント内の現在のユーザーのMicrosoft Entra オブジェクト ID。 (TeamsJS v.2.0.0 より前と呼ばれます {userObjectId} )。
  • {app.theme}: 、 などのdefaultdarkcontrast現在のユーザー インターフェイス (UI) テーマ。 (TeamsJS v.2.0.0 より前と呼ばれます {theme} )。
  • {team.groupId}: タブが存在する Microsoft 365 グループの ID。 (TeamsJS v.2.0.0 より前と呼ばれます {groupId} )
  • {user.tenant.id}: 現在のユーザーのMicrosoft Entraテナント ID。 (TeamsJS v.2.0.0 より前と呼ばれます {tid} )。
  • {app.locale}: languageId-countryIden-us などの形式のユーザーの現在のロケール。 (TeamsJS v.2.0.0 より前と呼ばれます {locale} )。

注:

以前の {upn} プレースホルダーは、現在では非推奨となっています。 後方互換性のため、現在は {user.loginHint} の同義語となっています。

たとえば、アプリ マニフェストで 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

詳細については、「コンテキスト インターフェイスへのUpdates」と「コンテキスト インターフェイス 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です。 これに対処するために、 プロパティと hostTenantID プロパティが新しく追加され、hostTeamGroupIDメンバーシップを取得するための 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、または contrastのdefaultdark値を持つ文字列です。

次の図は、Teams の既定のテーマ オプションを示しています。

Teams デスクトップ クライアントの既定のテーマを示すスクリーンショット。

コード サンプル

サンプルの名前 説明 JavaScript
タブ チャネル コンテキスト このサンプルでは、プライベートおよび共有チャネルでタブ コンテキスト オブジェクトの内容を使用する方法を示します。 表示

次の手順

アダプティブ カードを使用してタブをビルドする

関連項目