アプリケーションへのディープリンク

[アーティクル]
09/22/2023

ディープリンクは、タブを開く、アプリのインストールダイアログを開始する、アプリ内で参照するなど、さまざまなアクションを実行するように構成されています。ボットとコネクタメッセージのディープリンクを使用して、タブまたはその項目の変更についてユーザーに通知します。

カスタムアプリのディープリンクを作成できます。ただし、Microsoft Teams ストア内のアプリがカスタムアプリ ID と同じアプリ ID を共有している場合、ディープリンクはカスタムアプリではなく Teams ストアからアプリを開きます。アプリが Teams モバイルプラットフォームに対して承認された後に、モバイル用アプリへのディープリンクを作成することもできます。 Teams iOS でディープリンクを機能させるには、Apple App Store Connect チーム ID が必要です。詳細については、「Apple App Store Connect チーム ID を更新する方法」を参照してください。

ディープリンクを使用すると、ユーザーはアプリの詳細を把握し、さまざまなスコープでインストールできます。アプリユーザーがアプリ内の特定のページに移動するためのディープリンクを作成することもできます。この記事では、ディープリンクを作成する方法について説明します。

アプリケーションのインストールダイアログを開くには
アプリ内で参照するには
アプリケーションとのチャットに移動するには
タブのディープリンクを共有するには
ダイアログを開くには (TeamsJS v1.x でタスクモジュールと呼ばれます)
Stageview を呼び出すには

注:

このトピックでは、Microsoft Teams JavaScript クライアントライブラリ (TeamsJS) のバージョン 2.0.x を反映しています。以前のバージョンを使用している場合は、最新の TeamsJS と以前のバージョンの違いに関するガイダンスについては、TeamsJS ライブラリの概要を参照してください。

アプリケーションのインストールダイアログを開くディープリンク

ディープリンクを使用すると、アプリユーザーはアプリケーションのインストールダイアログを開いて、アプリに関する詳細情報を知ったり、さまざまなコンテキストでインストールしたりできます。アプリケーションへのディープリンクは、次の方法で作成できます。

アプリ ID を使用してディープリンクを手動で構成する
TeamsJS を使用してタブへのディープリンクを構成する

アプリ ID を使用してディープリンクを手動で構成する

アプリ ID を使用して Teams クライアントからアプリのインストールダイアログを開くために必要なディープリンク形式を次に示します。

https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>

はアプリケーション <your-app-id> ID です (f46ad259-0fe5-4f12-872d-c737b174bcb4)。

さまざまな種類のアプリのアプリ ID

次の表に、ディープリンク用のさまざまな種類のアプリに使用されるさまざまな種類のアプリ ID を示します。

アプリの種類	アプリ ID の種類
Teams でアップロードされたカスタムアプリ	マニフェスト ID
組織カタログに送信されたアプリ	組織カタログ ID
Teams ストアに送信されたアプリ	ストア ID

詳細については、アプリマニフェスト ID に基づいて ID を検索する方法に関するページを参照してください。

アプリケーションでは TeamsJS ライブラリを使用してアプリのインストールダイアログを開始できるため、手動によるディープリンクの生成が不要になります。アプリケーション内で TeamsJS を使用してアプリのインストールダイアログをトリガーする方法の例を次に示します。

TeamsJS v2
TeamsJS v1

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: "<appId>" });
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

モジュールの詳細 appInstallDialog については、「 appInstallDialog モジュール」を参照してください。

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/<appId>");

アプリ内で参照するためのディープリンク

アプリユーザーは、TeamsJS を使用して、タブから Teams のコンテンツを参照できます。チャネル、メッセージ、別のタブなど、Teams 内の他のコンテンツとユーザーを接続する必要がある場合、またはスケジュールダイアログを開く場合は、アプリ内でディープリンクを使用して参照できます。場合によっては、TeamsJS を使用してナビゲーションを実行することもできます。可能な限り、TeamsJS の型指定された機能を使用することをお勧めします。

TeamsJS を使用すると、Outlook と Microsoft 365 の間で拡張された Teams アプリは、ホストが使用しようとしている機能をサポートしている場合にチェックできます。ホストによる機能のサポートを確認するには、API の名前空間に関連付けられている isSupported() 関数を使用できます。 TeamsJS は、名前空間を使用して API を機能に整理します。たとえば、名前空間で API を使用する前にpages、からpages.isSupported()返されたブール値をチェックし、アプリとアプリの UI のコンテキスト内で適切なアクションを実行できます。

TeamsJS の機能と API の詳細については、「TeamsJS ライブラリでのタブとその他のホストされたエクスペリエンスの構築」を参照してください。

アプリ内で参照するディープリンクは、次の方法で構成できます。

アプリ内で手動で参照するようにディープリンクを構成する
TeamsJS を使用してタブへのディープリンクを構成する

アプリ内で手動で参照するようにディープリンクを構成する

ボット、コネクタ、またはメッセージ拡張機能カードのディープリンクには、次の形式を使用します。

https://teams.microsoft.com/l/entity/<appId>/<entityId>?tenantId=<tenantId>&webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

ボットがディープリンクを使用して TextBlock を含むメッセージを送信する場合、ユーザーがリンクを選択すると、新しいブラウザータブが開きます。これは、Linux で実行されている Chrome と Teams デスクトップアプリで発生します。
ボットがに同じディープリンク URL を送信する Action.OpenUrl場合、ユーザーがリンクを選択すると、現在のブラウザータブで [Teams] タブが開きます。

クエリパラメーターは次のとおりです。

パラメーター名	説明	例
`appId`	Microsoft Teams 管理センターの ID。	fe4a8eba-2a31-4737-8e33-e5fae6fee194
`entityId`	タブを構成するときに指定したタブの ID。ディープリンク用の URL を生成する場合は、引き続き URL のパラメーター名としてエンティティ ID を使用します。タブを構成する場合、コンテキストオブジェクトはとして `page.id`を`entityId`参照します。	タスクリスト 123
`entityWebUrl` または `subEntityWebUrl`	クライアントがタブのレンダリングをサポートしていない場合に使用するフォールバック URL を含むオプションのフィールド。	`https://tasklist.example.com/123` または `https://tasklist.example.com/list123/task456`
`entityLabel` または `subEntityLabel`	ディープリンクを表示するときに使用するタブ内の項目のラベル。	タスクリスト 123 またはタスク 456
`context.subEntityId`	タブ内の項目の ID。ディープリンク用の URL を生成する場合は、引き続き URL のパラメーター名としてを使用 `subEntityId` します。タブを構成する場合、コンテキストオブジェクトはとして `page.subPageId`を`subEntityId`参照します。	タスク 456
`context.channelId`	タブコンテキストから使用可能な Microsoft Teams チャネル ID。このプロパティは、チームのスコープを持つ構成可能なタブでのみ使用できます。個人用スコープを持つ静的タブでは使用できません。	19:cbe3683f25094106b826c9cada3afbe0@thread.skype
`context.chatId`	グループチャットと会議チャットのタブコンテキストから使用できるチャット ID。	17:b42de192376346a7906a7dd5cb84b673@thread.v2
`context.contextType`	チャットは、会議でサポートされている `contextType` 唯一の方法です。	チャット
`&openInMeeting=false`	を使用して `openInMeeting` 、ターゲットタブが会議に関連付けられているときにユーザーエクスペリエンスを制御します。ユーザーが進行中の会議エクスペリエンスのディープリンクと対話する場合、Teams は会議内のサイドパネルでアプリを開きます。この値をに `false` 設定すると、会議の状態に関係なく、サイドパネルではなく会議チャットタブでアプリが常に開きます。 Teams では、以外 `false`の値は無視されます。	`false`

注:

個人用タブには personal スコープがあり、チャネルタブとグループタブには team または group スコープが使用されます。構成可能なタブだけがコンテキストオブジェクトに関連付けられている channel プロパティを持つため、2 つのタブの種類の構文はわずかに異なります。タブスコープの詳細については、アプリマニフェストに関するページを参照してください。
ディープリンクは、タブがエンティティ ID を持つライブラリ v0.4 以降を使用して構成されている場合にのみ正しく機能します。エンティティ ID のないタブへのディープリンクは引き続きタブに移動しますが、サブエンティティ ID をタブに指定することはできません。

例:

静的 (個人用) タブ自体へのリンク:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123
静的 (個人用) タブ内のタスクアイテムへのリンク:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}
構成可能なタブ自体へのリンク:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}
構成可能なタブ内のタスクアイテムへのリンク:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}
会議またはグループチャットに追加されたタブアプリへのリンク:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456?context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

重要

すべてのクエリパラメーターと空白が適切に URI エンコードされていることを確認します。最後の例を使用して、前述の例に従う必要があります:

var encodedWebUrl = encodeURIComponent('https://tasklist.example.com/123/456&label=Task 456');
var encodedContext = encodeURIComponent(JSON.stringify({"subEntityId": "task456"}));
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

TeamsJS を使用してタブへのディープリンクを構成する

アプリユーザーがアプリ内のさまざまなページを閲覧できるように、TeamsJS を使用してアプリ内のディープリンクを構成できます。次のコードは、Teams アプリ内の特定のエンティティに移動する方法を示しています。

TeamsJS v2
TeamsJS v1

次のコードに示すように、pages.navigateToApp() 関数を使用してタブからナビゲーションをトリガーできます。

if (pages.isSupported()) {
  const navPromise = pages.navigateToApp({ appId: <appId>, pageId: <pageId>, webUrl: <webUrl>, subPageId: <subPageId>, channelId:<channelId>});
  navPromise.
     then((result) => {/*Successful navigation*/}).
     catch((error) => {/*Failed navigation*/});
}
else { /* handle case where capability isn't supported */ }

タブアプリ内のナビゲーションの詳細については、「タブアプリ内を移動する」を参照してください。ページ機能の使用の詳細については、「pages.navigateToApp() とその他のナビゲーションオプションのための pages 名前空間」を参照してください。必要に応じて、 app.openLink() 関数を使用してディープリンクを直接開きます。

タブからディープリンクをトリガーするには、次を呼び出します:

microsoftTeams.executeDeepLink(/*deepLink*/);

Microsoft 365 Office 全体に拡張された Teams アプリのナビゲーション動作は、次の 2 つの要因に依存します。

ディープリンクが指すターゲット。
Teams アプリが実行されているホスト。

Teams アプリがディープリンクの対象となるホスト内で実行されている場合、アプリはホスト内で直接開きます。ただし、Teams アプリがディープリンクをターゲットとする別のホストで実行されている場合、アプリは最初にブラウザーで開きます。

アプリケーションとのチャットへのディープリンク

次の形式を使用してディープリンクを手動で構成することで、アプリユーザーがアプリケーションとの個人用チャットを参照できるようにします。

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>は appId アプリケーション ID です。使用されるさまざまなアプリ ID については、「さまざまな種類のアプリのアプリ ID」を参照してください。

Teams アプリ内のエンティティへのディープリンクを共有して、タブアプリ内のコンテンツと情報に移動できます。たとえば、タブアプリにタスクリストが含まれている場合、チームメンバーは個々のタスクへのリンクを作成して共有できます。アプリユーザーがリンクを選択すると、特定の項目に焦点を当てたタブに移動します。

TeamsJS v2
TeamsJS v1

UI に最適な方法で、各項目に コピーリンク アクションを追加します。ユーザーがこのアクションを実行すると、を呼び出して pages.shareDeepLink() 、ユーザーがクリップボードにコピーできるリンクを含むダイアログを表示します。この呼び出しを行うときは、アイテムの ID を渡します。リンクがフォローされ、タブが再読み込みされると、コンテキストに戻されます。

pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

次のパラメーターを適切な情報に置き換える必要があります。

subPageId: ディープリンク先であるページ内のアイテムの一意の ID。
subPageLabel: ディープリンクの表示に使用するアイテムのラベル。
subPageWebUrl: クライアントがページをレンダリングできない場合に使用するフォールバック URL。

詳細については、「 pages.shareDeepLink()」を参照してください。

UI に最適な方法で、各項目に コピーリンク アクションを追加します。ユーザーがこのアクションを実行すると、を呼び出して shareDeepLink() 、ユーザーがクリップボードにコピーできるリンクを含むダイアログを表示します。この呼び出しを行うときは、アイテムの ID を渡します。リンクがフォローされ、タブが再読み込みされると、コンテキストに戻されます。

microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

次のパラメーターを適切な情報に置き換える必要があります。

subEntityId: ディープリンクしているタブ内のアイテムの一意の識別子。
subEntityLabel: ディープリンクの表示に使用するアイテムのラベル。
subEntityWebUrl: クライアントがタブのレンダリングをサポートしていない場合に使用するフォールバック URL を持つ省略可能なパラメーター。

注:

このディープリンクは、[ リンクをタブにコピー ] メニュー項目によって提供されるリンクとは異なります。このリンクは、このタブを指すディープリンクのみを生成します。
shareDeepLink は Teams モバイルプラットフォームでは機能しません。

SharePoint Framework タブのディープリンク

ボット、コネクタ、またはメッセージ拡張機能のカードでは、次のディープリンク形式を使用できます。 https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>

注:

ボットがディープリンクを含むメッセージを TextBlock 送信すると、ユーザーがリンクを選択すると新しいブラウザータブが開きます。これは、Linuxで実行されている Chrome および Microsoft Teams デスクトップアプリで発生します。
ボットがに同じディープリンク URL を送信する Action.OpenUrl場合、ユーザーがリンクを選択すると、現在のブラウザーで [Teams] タブが開きます。新しいブラウザータブは開きません。

クエリパラメーターは次のとおりです。

appID: マニフェスト ID、たとえば fe4a8eba-2a31-4737-8e33-e5fae6fee194。
entityID: タブを構成するときに提供したアイテム ID。たとえば、tasklist123 です。
entityWebUrl: クライアントがタブ https://tasklist.example.com/123 または https://tasklist.example.com/list123/task456のレンダリングをサポートしていない場合に使用するフォールバック URL を持つ省略可能なパラメーター。
entityName: ディープリンクを表示するときに使用するタブ内の項目のラベル (または Task 456などTask List 123)。

例: https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList

ダイアログを開くディープリンク

ダイアログディープリンクは、オブジェクトの TaskInfo シリアル化であり、その他の 2 つの詳細と、 APP_ID 必要に応じてです BOT_APP_ID。

https://teams.microsoft.com/l/task/APP_ID?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID
https://teams.microsoft.com/l/task/APP_ID?card=<TaskInfo.card>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

<TaskInfo.url>、<TaskInfo.card>、<TaskInfo.height>、<TaskInfo.width>、および <TaskInfo.title> のデータ型と許容値については、「taskInfo オブジェクト」を参照してください。

ヒント

パラメーター (JavaScript encodeURI() 関数など) をcard使用する場合は、ディープリンク URL をエンコードします。

次の表に、APP_ID と BOT_APP_ID に関する情報を示します:

値	型	必須	説明
`APP_ID`	string	はい	サードパーティ製アプリの場合は、マニフェストからアプリ `id` を使用するか、Teams 管理センターからアプリを `APP_ID` 使用します。これらは同じであるためです。組織 (LOB アプリ) 用に構築されたカスタムアプリまたはカスタムアプリの場合は、Teams 管理センターからを`APP_ID`使用するか、Graph APIを使用します。マニフェスト`APP_ID`の validDomains 配列には、のドメイン`url`が含まれている必要があります (ディープリンク URL に存在する場合`url`)。アプリ ID は、ダイアログがタブまたはボットから呼び出されたときに既に認識されているため、に `TaskInfo`含まれていない理由です。
`BOT_APP_ID`	文字列	いいえ	`completionBotId` の値を指定した場合、オブジェクト `result` はメッセージ `task/submit invoke` を使用して指定したボットに送信されます。 [指定 `BOT_APP_ID` ] は、アプリのマニフェストでボットとして指定する必要があります。ボットに送信することはできません。

注:

APP_ID 多 BOT_APP_ID くの場合、アプリにアプリの ID として使用することをお勧めするボットがあり、存在する場合は同じになる可能性があります。

また、ディープリンクを生成して、アプリを共有して、会議のステージングと開始または参加を行うこともできます。

ステージにコンテンツを共有するためのディープリンクについては、「会議でステージにコンテンツを共有するためのディープリンク」を参照してください。

注:

会議のステージにコンテンツを共有するためのディープリンクの生成は、パブリック開発者プレビューでのみ使用できます。
会議のステージにコンテンツを共有するためのディープリンクは、Teams デスクトップクライアントでのみサポートされています。

会議サイドパネルへのディープリンク

会議の会議側パネルへのディープリンクを生成できます。会議側パネルへのディープリンクには、次の形式を使用します。

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>.

例:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

既定では、会議のサイドパネルにディープリンクが開きます。会議のサイドパネルではなくアプリでディープリンクを直接開くには、ディープリンク形式を追加 openInMeeting=false します。

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

詳細については、「タブへのディープリンク」を参照してください。

次のシナリオでは、会議側パネルにディープリンクが開きません。

アクティブな会議はありません。
アプリには、アプリマニフェストで宣言されたコンテキストがありません sidePanel 。
openInMeeting はディープリンクでに false 設定されます。
ディープリンクは、会議ウィンドウまたはコンポーネントの外部で選択されます。
ディープリンクが現在の会議と一致しません。たとえば、ディープリンクが別の会議から作成された場合などです。

Stageview を呼び出すためのディープリンク

API でディープリンク URL をラップすることで、タブからディープリンクを使用して Stageview を app.openLink(url) 呼び出すことができます。ディープリンクは、カード内の OpenURL アクションを介して渡すこともできます。 API で定義されているプロパティによって openMode 、Stageview 応答が決まります。詳細については、「ディープリンクを使用して Stageview を呼び出す」を参照してください。

コードサンプル

サンプルの名前	説明	.NET	Node.js
ディープリンクを使用するサブエンティティ ID	このサンプルでは、ボットチャットからサブエンティティ ID を使用するタブへのディープリンクを使用する方法を示します。また、次のディープリンクも表示されます。 - アプリへの移動 - チャットへの移動 - プロファイルダイアログを開く - スケジュール設定ダイアログを開く	表示	表示

アプリケーションへのディープリンク

アプリケーションのインストールダイアログを開くディープリンク

アプリ ID を使用してディープリンクを手動で構成する

さまざまな種類のアプリのアプリ ID

アプリ内で参照するためのディープリンク

アプリ内で手動で参照するようにディープリンクを構成する

TeamsJS を使用してタブへのディープリンクを構成する

アプリケーションとのチャットへのディープリンク

SharePoint Framework タブのディープリンク

ダイアログを開くディープリンク

会議サイドパネルへのディープリンク

Stageview を呼び出すためのディープリンク

コードサンプル

フィードバック

その他のリソース

アプリケーションへのディープ リンク

アプリケーションのインストール ダイアログを開くディープ リンク

アプリ ID を使用してディープ リンクを手動で構成する

さまざまな種類のアプリのアプリ ID

アプリ内で参照するためのディープ リンク

アプリ内で手動で参照するようにディープ リンクを構成する

TeamsJS を使用してタブへのディープ リンクを構成する

アプリケーションとのチャットへのディープ リンク

タブのディープ リンクを共有する

SharePoint Framework タブのディープ リンク

ダイアログを開くディープ リンク

会議のステージにコンテンツを共有するためのディープ リンクを生成する

会議サイド パネルへのディープ リンク

Stageview を呼び出すためのディープ リンク

コード サンプル

フィードバック

その他のリソース

アプリケーションへのディープリンク

アプリケーションのインストールダイアログを開くディープリンク

アプリ ID を使用してディープリンクを手動で構成する

アプリ内で参照するためのディープリンク

アプリ内で手動で参照するようにディープリンクを構成する

TeamsJS を使用してタブへのディープリンクを構成する

アプリケーションとのチャットへのディープリンク

タブのディープリンクを共有する

SharePoint Framework タブのディープリンク

ダイアログを開くディープリンク

会議のステージにコンテンツを共有するためのディープリンクを生成する

会議サイドパネルへのディープリンク

Stageview を呼び出すためのディープリンク

コードサンプル