Teams JavaScript クライアント ライブラリ

  • [アーティクル]

Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) は、アプリ コンテンツが iFrame でホストされている Teams、Microsoft 365 アプリ、Outlook でホストされているエクスペリエンスを作成するのに役立ちます。 ライブラリは、次の Teams 機能を使用してアプリを開発するのに役立ちます。

バージョン 2.0.0以降では、既存の TeamsJS ライブラリ (@microsoft/teams-jsまたは単に TeamsJS) がリファクタリングされ、 Teams アプリを Microsoft Teams に加えて Outlook と Microsoft 365 アプリで実行できるようになります。 機能的な観点から見ると、最新バージョンの TeamsJS では、既存のすべての (v.1.x.x) Teams アプリ機能がサポートされ、Outlook と Microsoft 365 アプリで Teams アプリをホストするオプションの機能が追加されています。

さまざまなアプリ シナリオについて、現在のバージョン管理ガイダンスを次に示します。

TeamsJS のバージョン アプリ マニフェストのバージョン 次のステップ
Microsoft 365 / Outlook に拡張された Teams アプリ TeamsJS v.2.0 以降 1.13 以降 Teams アプリを拡張して Microsoft 365 全体で実行する、または新しい Microsoft 365 アプリを作成する
既存の Teams 専用アプリ 可能な場合、TeamsJS v.2.0 に更新する (v.1.12 はまだサポートされています*) 1.12 TeamsJS の下位互換性について理解し、TeamsJS v.2.0 に更新する
新しい Teams 専用アプリ TeamsJS v.2.0 以降 1.12 Teams Toolkit を使用して新しい Teams アプリを作成する

*Teams 専用アプリを含む最新の機能強化と新機能のサポートを利用するには、可能な限り最新の TeamsJS (v.2.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 つの大きな変更があります。

ヒント

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 での作業を継続できるようにするために用意されています。

Teams 専用アプリ

アプリを Teams でのみ実行する (Microsoft 365 アプリと Outlook ではなく) 場合でも、ベスト プラクティスは、最新の機能強化、新機能、サポート (Teams 専用アプリの場合でも) の恩恵を受けるために、できるだけ早く最新の TeamsJS (v.2.0 以降) の参照を開始することです。 TeamsJS v.1.13.1 はサポートされているため使用することをお勧めしますが、新機能や機能強化は追加されません。

これができるようになったら、次の手順は、この記事で説明されている変更を使用して既存のアプリケーション コードを更新することです。 それまでの間、v.1 から v.2 の API への変換レイヤーが下位互換性を提供し、既存の Teams アプリが TeamsJS バージョン 2.0 で引き続き機能するようにします。

Teams でアプリを実行するロジックを実装するには、次のコード スニペットを使用します。


// Ensure that you initialize the TeamsJS once, regardless of how often this is called.
let teamsInitPromise;
export function ensureTeamsJSInitialized(){
    if (!teamsInitPromise) {
        teamsInitPromise = microsoftTeams.app.initialize();
    }
    return teamsInitPromise;
}

// Function returns a promise which resolves to true if we're running in Teams
export async function inTeams(){
  try {
    await ensureTeamsJSInitialized();
    const context = await microsoftTeams.app.getContext();
    return (context.app.host.name === microsoftTeams.HostName.teams);
  }
  catch (e) {
    console.log(`${e} from Teams SDK, may be running outside of Teams`);
    return false;
  }
}

アプリが正しく機能するためには、関数呼び出しを続行する前に、アプリの 初期化 が完了するまで待つ必要があります。 Teams 専用に設計されたプログラム ロジックは、他の Microsoft 365 アプリケーションで正しく機能しない可能性があります。 Microsoft 365 全体でアプリを円滑に操作するには、他の Microsoft 365 アプリケーションのロジック処理のプロビジョニングを行います。

認証

バージョン 2.11.0 以降では TeamsJS 、認証の完了後にユーザーを正しいクライアントにリダイレクトするには、 hostRedirectUrl認証 API で 3 番目の url パラメーター () をアプリで指定する必要があります。 hostRedirectUrl認証パラメーターは、クライアントが Microsoft 365 ホスト アプリケーション全体でサポートされるようにするために必要です。 以前のバージョンのアプリで実装されているアプリでは、および クエリ パラメーターがサード パーティのTeamsJSアプリ サーバーに渡されるためoauthRedirectmethodauthId、この更新プログラムに続く Teams のみがサポートされます。

認証パラメーターの詳細については、「 外部 OAuth プロバイダーの使用」を参照してください。

Microsoft 365 全体で実行されている Teams アプリ

既存の Teams アプリを Outlook と Microsoft 365 で実行できるようにするには、次のものが必要です。

  1. TeamsJS バージョン 2.x.x ( @microsoft/teams-js@2.0.0) 以降への依存関係、

  2. この記事で説明されている必要な変更に従って既存のアプリケーション コードを変更する、および

  3. アプリ マニフェスト (以前は Teams アプリ マニフェストと呼ばれる) をバージョン 1.13 以降に更新する。

詳細については、「Teams アプリを Microsoft 365 全体に拡張する」を参照してください。

コールバックの Promise への変換

注:

API は getTabInstances 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 コメントが含まれます。

API の機能への編成

機能は、同様の機能を提供する API の (名前空間を介した) 論理グループです。 Microsoft Teams、Outlook、Microsoft 365 アプリは、タブ アプリのホストと考えることができます。 ホストは、特定の機能内で定義されているすべての API をサポートしている場合、その機能をサポートします。 ホストが機能を部分的に実装することはできません。 機能は、認証やダイアログのように、機能ベースまたはコンテンツ ベースです。 ページなどのアプリケーションの種類や他のグループの機能もあります。

TeamsJS v.2.0 以降では、API は JavaScript 名前空間の関数として定義されます。この名前は、必要な機能と一致します。 たとえば、アプリがダイアログ機能をサポートするホストで実行されている場合、アプリは (名前空間で定義されている他のダイアログ関連の API に加えて) dialog.open などの API を安全に呼び出すことができます。 アプリがそのホストでサポートされていない API を呼び出そうとすると、API によって例外が生成されます。

ヒント

その機能 (名前空間) で isSupported() 関数を呼び出して、特定の機能の実行時にホスト サポートを確認します。

アプリ エクスペリエンスを差別化する

その機能 (名前空間) で isSupported() 関数を呼び出して、特定の機能の実行時にホスト サポートを確認できます。 サポートされている場合とfalseサポートされていない場合は が返trueされ、必要に応じてアプリの動作を調整できます。 これにより、アプリは、サポートするホストの UI と機能を明らかにしながら、サポートしないホストで引き続き実行できます。

アプリが動作するホスト名は、Context インターフェイス (app.Context.app.host.name) の hostName プロパティとして表示されます。 を呼び出 getContextすことで、実行時にこれを照会できます。 以前の Teams クライアントの場合、この値は 不明 または 未定義として返される場合があります。 このような場合は、これらの値を古い Teams にマップします。

URL プレースホルダーの{hostName}値も使用できます。 ただし、 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 名前空間

TeamsJS タスク 名前空間の名前が ダイアログに変更され、次の API の名前が変更されます。

元の名前空間 tasks 新しい名前空間 dialog
tasks.startTask dialog.open (名前の変更)
tasks.submitTasks dialog.submit (名前の変更)
tasks.updateTasks dialog.update.resize (名前の変更)
tasks.TaskModuleDimension 列挙 dialog.DialogDimension (名前の変更)
tasks.TaskInfo インターフェイス dialog.DialogInfo (名前の変更)

さらに、この機能は、HTML ベースのダイアログをサポートするためのメイン機能 (dialog) と、ボットベースのダイアログのサブキャパビリティに分割されますdialog.bot。

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 の機能への編成」に関する以下のセクションを参照してください。

  1. 最新の Teams Toolkit (バージョン 2.10.0 以降) があることを確認します
  2. コマンド パレットを開きます: Ctrl+Shift+P
  3. コマンド 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 ファイルは次のように更新されます。

重要

.html ファイル内のコードはアップグレード ツールではサポートされていないため、手動で変更する必要があります。

3. アプリ マニフェストを更新する (省略可能)

Microsoft 365 アプリと Outlook で実行するように Teams アプリを更新する場合は、アプリ マニフェストをバージョン 1.13 以降に更新する必要もあります。 これは、Teams Toolkit で簡単に行うか、手動で行うことができます。

  1. コマンド パレットを開きます: Ctrl+Shift+P
  2. Teams を実行する: Outlook と Microsoft 365 apps コマンドをサポートするように Teams マニフェストをアップグレードし、アプリ マニフェスト ファイルを選択します。 変更が行われます。

Teams Toolkit を使用して個人用アプリを作成した場合は、それを使用してアプリ マニフェスト ファイルの変更を検証し、エラーを特定することもできます。 コマンド パレットを開いてTeams をCtrl+Shift+P見つけます。マニフェスト ファイルを検証するか、Teams ツールキットの [配置] メニューからオプションを選択します (Visual Studio Code の左側にある Teams アイコンを探します)。

Teams ツールキット [配置] メニューの [マニフェスト ファイルの検証] オプション

次の手順