次の方法で共有


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

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

  • ユーザー、チーム、または会社に関する基本情報。
  • ロケールとテーマの情報。
  • このタブの内容を識別する page.idpage.subPageId (TeamsJS v2.0.0 より前の entityIdsubEntityId と呼ばれます)。

ユーザー コンテキスト

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

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

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

重要

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

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

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

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}: defaultdarkcontrastなどの現在のユーザー インターフェイス (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 引数は、 defaultdark、または contrast の値を持つ文字列です。

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

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

コード サンプル

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

次の手順

関連項目