Teams JavaScript クライアント ライブラリ
Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) は、Teams、Microsoft 365 アプリ、Outlook でホストされているエクスペリエンスを作成するのに役立ちます。このエクスペリエンスでは、アプリ コンテンツが iFrame でホストされます。 ライブラリは、次の Teams 機能を使用してアプリを開発するのに役立ちます。
バージョン 2.0.0
以降、既存の TeamsJS ライブラリ (@microsoft/teams-js
、または単に TeamsJS
) がリファクタリングされ、 Teams アプリを Outlook と Microsoft 365 アプリで実行できるように、Microsoft Teamsに加えて有効になります。 機能的な観点から見ると、最新バージョンの TeamsJS では、既存のすべての (v.1.x.x) Teams アプリ機能がサポートされ、Outlook と Microsoft 365 アプリで Teams アプリをホストするオプションの機能が追加されています。
さまざまなアプリ シナリオのバージョン管理ガイダンスを次に示します。
アプリの種類 | TeamsJS のバージョン | アプリ マニフェストのバージョン | 次の手順 |
---|---|---|---|
Outlook と Microsoft 365 全体で拡張された Teams アプリ | TeamsJS v.2.19.0 以降 | v.1.13 以降 | Teams アプリを拡張して Microsoft 365 全体で実行する、または新しい Microsoft 365 アプリを作成する |
既存の Teams 専用アプリ | 可能な場合は TeamsJS v.2.19.0 に更新します (v.1.12 はまだサポートされています*) | 1.12 | TeamsJS の下位互換性について理解し、TeamsJS v.2.0 に更新する |
新しい Teams 専用アプリ | TeamsJS v.2.19.0 以降 | 1.12 | Teams Toolkit を使用して新しい Teams アプリを作成する |
* Teams 専用アプリを含む最新の機能強化と新機能のサポートを利用するには、可能な限り最新の TeamsJS (v.2.19.0 以降) を使用します。TeamsJS v.1.12 は引き続きサポートされますが、新機能や機能強化は追加されません。1.12 スキーマと 1.13 スキーマは同じです。詳細については、「 TeamsJS ライブラリ」を参照してください。
この記事の残りの部分では、TeamsJS ライブラリの構造と最新の更新プログラムについて説明します。
Microsoft 365 のサポート (Microsoft 365 と Outlook での Teams アプリの実行)
TeamsJS v.2.0 では、特定の種類の Teams アプリをMicrosoft 365 エコシステム全体で実行する機能が導入されています。 Teams アプリ用の他の Microsoft 365 アプリケーション ホスト (Microsoft 365 アプリと Outlook を含む) では、Teams プラットフォーム用に構築できるアプリケーションの種類と機能のサブセットがサポートされています。 このサポートは時間の経過と同時に拡張されます。 Teams アプリのホスト サポートの概要については、「 Microsoft 365 全体での TeamsJS 機能のサポート」を参照してください。
TeamsJS バージョン 2.x.x の新機能
TeamsJS バージョン 1.x.x と v.2.0.0 以降には、2 つの大きな変更があります。
コールバック関数が Promise オブジェクトを返すようになりました。 TeamsJS v.1.12 のコールバック パラメーターを持つほとんどの関数は、非同期操作の処理とコードの読みやすさを向上させるために JavaScript Promise オブジェクトを返すように最新化されています。
API が 機能に整理されました。 機能は、
authentication
、dialog
、chat
、calendar
など、同様の機能を提供する API の論理グループと考えることができます。 各名前空間は、個別の機能を表します。
ヒント
Microsoft Visual Studio Code の Teams Toolkit 拡張機能を使用すると、既存の Teams アプリの TeamsJS v.2.0 更新プロセスを簡略化できます。
下位互換性
既存の Teams アプリから @microsoft/teams-js@2.0.0
(以降) の参照を開始すると、変更された API を呼び出すコードに対して非推奨の警告が表示されます。
API 翻訳レイヤー (v.1 から v.2 TeamsJS API 呼び出しへのマッピング) は、TeamsJS v.2 API パターンを使用するようにアプリケーション コードを更新できるようになるまで、既存の Teams アプリが Teams での作業を継続できるようにするために用意されています。
認証
バージョン 2.11.0 以降TeamsJS
では、認証が完了した後にユーザーを正しいクライアントにリダイレクトするには、認証 API で 3 つ目の url パラメーター (hostRedirectUrl
) をアプリで指定する必要があります。 クライアントを Microsoft 365 ホスト アプリケーション全体でサポートできるようにするには、 hostRedirectUrl
認証パラメーターが必要です。 古いバージョンの TeamsJS
に実装されたアプリでは、 oauthRedirectmethod
と authId
クエリ パラメーターがサード パーティのアプリ サーバーに渡されるため、この更新プログラムに続く Teams のみがサポートされます。
認証パラメーターの詳細については、「 外部 OAuth プロバイダーの使用」を参照してください。
Microsoft 365 全体で実行されている Teams アプリ
既存の Teams アプリを Outlook と Microsoft 365 で実行できるようにするための要件を次に示します。
TeamsJS バージョン 2.x.x (
@microsoft/teams-js@2.0.0
) 以降への依存関係。この記事で説明する必要な変更に従って、既存のアプリケーション コードを変更します。
アプリ マニフェスト (以前は Teams アプリ マニフェストと呼ばれる) をバージョン 1.13 以降に更新します。
詳細については、「 Microsoft 365 全体で Teams アプリを拡張する」を参照してください。
コールバックの Promise への変換
注:
getTabInstances
API は Teams モバイルには実装されていません。
以前にコールバック パラメーターを受け取った Teams API は、JavaScript Promise オブジェクトを返すように更新されます。 これには、以下の API が含まれます。
app.getContext, app.initialize, appInstallDialog.openAppInstallDialog, app.openLink, authentication.authenticate, authentication.getAuthToken, authentication.getUser, authentication.registerAuthenticationHandlers was removed to support using Promises, calendar.openCalendarItem, calendar.composeMeeting, call.startCall, chat.getChatMembers, conversations.openConversation, location.getLocation, location.showLocation, mail.openMailItem, mail.composeMail, pages.backStack.navigateBack, pages.navigateToTab, pages.tabs.getMruTabInstances, pages.tabs.getTabInstances, pages.getConfig, pages.config.setConfig, pages.backStack.navigateBack, people.selectPeople, teams.fullTrust.getConfigSetting, teams.fullTrust.joinedTeams.getUserJoinedTeams
Promises を使用するには、コードがこれらの API のいずれかを呼び出す方法を更新する必要があります。 たとえば、コードが次のような Teams API を呼び出しているとします。
コード:
import microsoftTeams from "@microsoft/teams-js";
microsoftTeams.getContext((context) => { /* ... */ });
これを次のように更新する必要があります:
import { app } from "@microsoft/teams-js";
app.getContext().then((context) => {
/*...*/
});
...または同等の async/await
パターン:
import { app } from "@microsoft/teams-js";
async function example() {
const context = await app.getContext();
/*...*/
}
ヒント
Teams Toolkit を使用して TeamsJS v.2.0 に更新すると、更新プログラムにフラグが付けられ、クライアント コードに TODO
コメントが含まれます。
SDK を介したクラウド間通信は、セキュリティ上の理由から制限されています。そのため、21Vianet ドメインによって運営される Teams は validOrigins
に含まれません。 アプリが 21Vianet によって運用される Teams で機能できるようにするには、アプリのデプロイで SDK の初期化中に、 validMessageOrigins パラメーターを使用して、21Vianet ドメインによって運用される Teams を指定します。
import { app } from '@microsoft/teams-js';
app.initialize(["https://teams.microsoftonline.cn"]);
API の機能への編成
機能は、同様の機能を提供する API の (名前空間を介した) 論理グループです。 Microsoft Teams、Outlook、Microsoft 365 アプリは、タブ アプリのホストと考えることができます。 ホストは、特定の機能内で定義されているすべての API をサポートしている場合、その機能をサポートします。 ホストが機能を部分的に実装することはできません。 機能は、認証やダイアログのように、機能ベースまたはコンテンツ ベースです。 ページなどのアプリケーションの種類や他のグループの機能もあります。
TeamsJS v.2.0 以降では、API は JavaScript 名前空間の関数として定義されます。この名前は、必要な機能と一致します。 たとえば、アプリがダイアログ機能をサポートするホストで実行されている場合、アプリは (名前空間で定義されている他のダイアログ関連の API に加えて) dialog.open
などの API を安全に呼び出すことができます。 アプリがそのホストでサポートされていない API を呼び出そうとすると、API によって例外が生成されます。
ヒント
その機能 (名前空間) で isSupported()
関数を呼び出して、特定の機能の実行時にホスト サポートを確認します。
アプリ エクスペリエンスを差別化する
その機能 (名前空間) で isSupported()
関数を呼び出して、特定の機能の実行時にホスト サポートを確認できます。 サポートされている場合は true
を返し、サポートされていない場合は false
し、必要に応じてアプリの動作を調整できます。 これにより、アプリは、サポートするホストの UI と機能を明らかにしながら、サポートしないホストで引き続き実行できます。
アプリが動作するホスト名は、Context
インターフェイス (app.Context.app.host.name
) の HostName 列挙値として表示されます。 これを実行時にクエリするには、 getContext
を呼び出します。 クラシック Teams クライアントの場合、この値は 不明 または 未定義として返される場合があります。 この場合、これらの値をクラシック Teams にマップします。
{hostName}
URL プレースホルダー値も使用できます。 ただし、 hostName メカニズムは慎重に使用することをお勧めします。
-
hostName プロパティ値に基づいて、特定の機能がホストで使用できる、またはできないとは考えないでください。 代わりに、機能サポート (
isSupported
) を確認します。 -
hostName を使用して API 呼び出しをゲートしないでください。 代わりに、機能サポート (
isSupported
) を確認します。 - hostName は、実行中のホストに基づいてアプリケーションのテーマを区別するために使用します。 たとえば、Teamsで実行する場合は Microsoft Teams の紫色を主なアクセント カラーとして使用し、Outlook で実行する場合は Outlook の青を使用できます。
- hostName は、実行中のホストに基づいてユーザーに表示されるメッセージを区別するために使用します。 たとえば、Web 上の Microsoft 365 で実行する場合は Microsoft 365 でタスクを管理 し、Teams で実行する場合 は Teams でタスクを管理 するを示します。
名前空間
TeamsJS v.2.0 以降、API は名前空間として機能に編成されます。 特に重要な新しい名前空間には、app、pages、dialog、teamsCore があります。
app 名前空間
app
名前空間には、Teams、Microsoft 365 アプリ、Outlook 全体で、アプリ全体の使用に必要なトップレベル API が含まれています。 他のさまざまな TeamsJS 名前空間のすべての API は、TeamsJS v.2.0 の時点で app
名前空間に移動されます。
元の名前空間 global (window) |
新しい名前空間 app |
---|---|
executeDeepLink |
app.openLink (名前の変更) |
initialize |
app.initialize |
getContext |
app.getContext |
registerOnThemeChangeHandler |
app.registerOnThemeChangeHandler |
元の名前空間 appInitialization |
新しい名前空間 app |
---|---|
appInitialization.notifyAppLoaded |
app.notifyAppLoaded |
appInitialization.notifySuccess |
app.notifySuccess |
appInitialization.notifyFailure |
app.notifyFailure |
appInitialization.notifyExpectedFailure |
app.notifyExpectedFailure |
appInitialization.FailedReason 列挙 |
app.FailedReason |
appInitialization.ExpectedFailureReason 列挙 |
app.ExpectedFailureReason |
appInitialization.IFailedRequest 列挙 |
app.IFailedRequest |
appInitialization.IExpectedFailureRequest 列挙 |
app.IExpectedFailureRequest |
pages 名前空間
pages
名前空間には、Teams、Microsoft 365 アプリ、Outlook など、さまざまな Microsoft 365 ホスト内で Web ページを実行および移動するための機能が含まれています。 また、サブ名前空間として実装されるいくつかのサブ機能も含まれています。
元の名前空間 global (window) |
新しい名前空間 pages |
---|---|
setFrameContext |
pages.setCurrentFrame (名前の変更) |
initializeWithFrameContext |
pages.initializeWithFrameContext |
registerFocusEnterHandler |
pages.registerFocusEnterHandler |
registerFullScreenHandler |
pages.registerFullScreenHandler |
returnFocus |
pages.returnFocus |
shareDeepLink |
pages.shareDeepLink |
元の名前空間 settings |
新しい名前空間 pages |
---|---|
settings.getSettings |
pages.getConfig (名前の変更) |
pages.tabs
元の名前空間 global (window) |
新しい名前空間 pages.tabs |
---|---|
getTabInstances |
pages.tabs.getTabInstances |
getMruTabInstances |
pages.tabs.getMruTabInstances |
元の名前空間 navigation |
新しい名前空間 pages.tabs |
---|---|
navigation.navigateToTab |
pages.tabs.navigateToTab |
pages.config
元の名前空間 settings |
新しい名前空間 pages.config |
---|---|
settings.setSettings |
pages.config.setConfig (名前の変更) |
settings.setValidityState |
pages.config.setValidityState |
settings.initialize |
pages.config.initialize |
settings.registerOnSaveHandler |
pages.config.registerOnSaveHandler |
settings.registerOnRemoveHandler |
pages.config.registerOnRemoveHandler |
settings.Settings インターフェイス |
pages.config.Config (名前の変更) |
settings.SaveEvent インターフェイス |
pages.config.SaveEvent (名前の変更) |
settings.RemoveEvent インターフェイス |
pages.config.RemoveEvent (名前の変更) |
settings.SaveParameters インターフェイス |
pages.config.SaveParameters (名前の変更) |
settings.SaveEventImpl インターフェイス |
pages.config.SaveEventImpl (名前の変更) |
元の名前空間 global (window) |
新しい名前空間 pages.config |
---|---|
registerChangeConfigHandler |
pages.config.registerChangeConfigHandler (名前の変更) |
pages.backStack
元の名前空間 navigation |
新しい名前空間 pages.backStack |
---|---|
navigation.navigateBack |
pages.backStack.navigateBack |
元の名前空間 global (window) |
新しい名前空間 pages.backStack |
---|---|
registerBackButtonHandler |
pages.backStack.registerBackButtonHandler |
pages.appButton
元の名前空間 global (window) |
新しい名前空間 pages.appButton |
---|---|
registerAppButtonClickHandler |
pages.appButton.onClick (名前の変更) |
registerAppButtonHoverEnterHandler |
pages.appButton.onHoverEnter (名前の変更) |
registerAppButtonHoverLeaveEnter |
pages.appButton.onHoverLeave (名前の変更) |
FrameContext インターフェイス |
pages.appButton.FrameInfo (名前の変更) |
dialog 名前空間
注:
ダイアログの表示に使用する window.alert
、 window.confirm
、 window.prompt
API は、新しい Teams クライアントではサポートされていません。
Fluent V9 ダイアログを使用する場合や、Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) を使用してアダプティブ カードや入れ子になった<iframe>
を使用して Teams ダイアログを表示するなど、独自のフレーム内にダイアログをレンダリングすることをお勧めします。
TeamsJS タスク 名前空間の名前が ダイアログに変更され、次の API の名前が変更されます。
元の名前空間 tasks |
新しい名前空間 dialog |
---|---|
tasks.startTask |
dialog.url.open , dialog.url.bot.open , dialog.adaptiveCard.open , dialog.adaptiveCard.bot.open |
tasks.submitTask |
dialog.url.submit (名前の変更) |
tasks.updateTask |
dialog.update (名前の変更) |
tasks.TaskModuleDimension 列挙 |
dialog.DialogDimension (名前の変更) |
tasks.TaskInfo インターフェイス |
dialog.DialogInfo (名前の変更) |
さらに、この機能は 2 つのメインサブキャパビリティに分割されます。HTML ベースのダイアログの場合はdialog.url
、アダプティブ カード ベースのダイアログの場合はdialog.adaptiveCard
、ボットベースのダイアログにはさらにサブネームスペースがあります。
teamsCore 名前空間
Microsoft 365 アプリや Outlook などの他の Microsoft 365 ホストを実行するように TeamsJS ライブラリを一般化するために、Teams 固有の機能 (もともと はグローバル 名前空間) が teamsCore 名前空間に移動されます。
元の名前空間 global (window) |
新しい名前空間 teamsCore |
---|---|
enablePrintCapability |
teamsCore.enablePrintCapability |
print |
teamsCore.print |
registerOnLoadHandler |
teamsCore.registerOnLoadHandler |
registerBeforeUnloadHandler |
teamsCore.registerBeforeUnloadHandler |
Context インターフェイスの更新
Context
インターフェイスは、app
名前空間に移動され、Teams に加えて Outlook と Microsoft 365 アプリで実行されるスケーラビリティを向上させるために同様のプロパティをグループ化するように更新されます。
ホスト アプリケーションに応じてユーザー エクスペリエンスを区別するためのタブを有効にするために、新しいプロパティ app.Context.app.host.name
が追加されます。
TeamsJS バージョン 2.x.x ソース (app.ts ファイル) のtransformLegacyContextToAppContext
関数を確認して、変更を視覚化することもできます。
Context インターフェイスでの元の名前 |
app.Context の新しい場所 |
---|---|
appIconPosition |
app.Context.app.iconPositionVertical |
appLaunchId |
NOT IN TeamsJS v.2.0 |
appSessionId |
app.Context.app.sessionId |
channelId |
app.Context.channel.id |
channelName |
app.Context.channel.displayName |
channelRelativeUrl |
app.Context.channel.relativeUrl |
channelType |
app.Context.channel.membershipType |
chatId |
app.Context.chat.id |
defaultOneNoteSectionId |
app.Context.channel.defaultOneNoteSectionId |
entityId |
app.Context.page.id |
frameContext |
app.Context.page.frameContext |
groupId |
app.Context.team.groupId |
hostClientType |
app.Context.app.host.clientType |
hostTeamGroupId |
app.Context.channel.ownerGroupId |
hostTeamTenantId |
app.Context.channel.ownerTenantId |
isCallingAllowed |
app.Context.user.isCallingAllowed |
isFullScreen |
app.Context.page.isFullScreen |
isMultiWindow |
app.Context.page.isMultiWindow |
isPSTNCallingAllowed |
app.Context.user.isPSTNCallingAllowed |
isTeamArchived |
app.Context.team.isArchived |
locale |
app.Context.app.locale |
loginHint |
app.Context.user.loginHint |
meetingId |
app.Context.meeting.id |
osLocaleInfo |
app.Context.app.osLocaleInfo |
parentMessageId |
app.Context.app.parentMessageId |
ringId |
app.Context.app.host.ringId |
sessionId |
app.Context.app.host.sessionId |
sourceOrigin |
app.Context.page.sourceOrigin |
subEntityId |
app.Context.page.subPageId |
teamId |
app.Context.team.internalId |
teamSiteDomain |
app.Context.sharepointSite.domain |
teamSitePath |
app.Context.sharepointSite.path |
teamSiteUrl |
app.Context.sharepointSite.url |
teamTemplateId |
app.Context.team.templateId |
teamType |
app.Context.team.type |
tenantSKU |
app.Context.user.tenant.teamsSku |
tid |
app.Context.user.tenant.id |
upn |
app.Context.user.userPrincipalName |
userClickTime |
app.Context.app.userClickTime |
userFileOpenPreference |
app.Context.app.userFileOpenPreference |
userLicenseType |
app.Context.user.licenseType |
userObjectId |
app.Context.user.id |
userTeamRole |
app.Context.team.userRole |
該当なし | app.Context.app.host.name |
TeamsJS バージョン 2.0 への更新
TeamsJS バージョン 2.0.x で Teams アプリを更新する最も簡単な方法は、Visual Studio Code 用 の Teams Toolkit 拡張機能 を使用することです。 このセクションでは、その手順について説明します。 コードを手動で更新する場合は、必要な API の変更の詳細については、「Promise と APIに変換されたコールバック」セクションを参照してください。
1. 最新の Teams Toolkit Visual Studio Code 拡張機能をインストールする
Visual Studio Code Extensions Marketplace で、Teams Toolkit を検索し、最新バージョンをインストールします。
2. TeamsJS 参照を更新する
Outlook と Microsoft 365 アプリで実行するには、アプリが npm パッケージ@microsoft/teams-js@2.0.0
(以降) に依存している必要があります。 これらの手順を手動で実行する方法と、API の変更の詳細については、「コールバックの Promise への変換」と「API の機能への編成」に関する以下のセクションを参照してください。
- 最新の Teams Toolkit (バージョン 2.10.0 以降) があることを確認します
-
コマンド パレットを開きます:
Ctrl+Shift+P
- コマンド
Teams: Upgrade Teams JS SDK references to support Outlook and Microsoft 365 apps
を実行します。
完了すると、ユーティリティは TeamsJS バージョン 2.x.x (@microsoft/teams-js@2.0.0
以降) の依存関係を使用してpackage.json
ファイルを更新し、*.js/.ts
と*.jsx/.tsx
は次のように更新されます。
-
package.json
TeamsJS バージョン 2.x.x への参照 - TeamsJS バージョン 2.x.x の Import ステートメント
- TeamsJS バージョン 2.x.x への関数、列挙型、インターフェイス呼び出し
-
TODO
コメント リマインダーを使用して、 コンテキスト インターフェイスの変更の影響を受ける可能性がある領域を確認する -
コールバック関数を Promise に変換するための
TODO
コメント リマインダー
重要
html ファイル内のコードはアップグレード ツールではサポートされていないため、手動で変更する必要があります。
3. アプリ マニフェストを更新する (省略可能)
Microsoft 365 アプリと Outlook で実行するように Teams アプリを更新する場合は、アプリ マニフェストをバージョン 1.13 以降に更新する必要もあります。 これは、Teams Toolkit で簡単に行うか、手動で行うことができます。
-
コマンド パレットを開きます:
Ctrl+Shift+P
- Teams を実行する: Outlook と Microsoft 365 apps コマンドをサポートするように Teams マニフェストをアップグレードし、アプリ マニフェスト ファイルを選択します。 変更が行われます。
Teams Toolkit を使用して個人用アプリを作成した場合は、それを使用してアプリ マニフェスト ファイルの変更を検証し、エラーを特定することもできます。 コマンド パレットを開いてTeams をCtrl+Shift+P
見つけます。マニフェスト ファイルを検証するか、Teams ツールキットの [配置] メニューからオプションを選択します (Visual Studio Code の左側にある Teams アイコンを探します)。
次の手順
- TeamsJS ライブラリのリファレンスを使用して、TeamsJS ライブラリの使用を開始します。
- TeamsJS の最新の更新プログラムの 変更ログ を確認します。
Platform Docs