Microsoft Teams のコンテンツと機能への詳細なリンクを作成するCreate deep links to content and features in Microsoft Teams

Teams クライアント内の情報と機能へのリンクを作成できます。You can create links to information and features within the Teams client. この例は、役に立ちます。Examples of where this may be useful:

  • アプリのタブのいずれか内のコンテンツにユーザーを移動します。Navigating the user to content within one of your app's tabs. たとえば、アプリには、重要なアクティビティをユーザーに通知するメッセージを送信する bot がある場合があります。For instance, your app may have a bot that sends messages notifying the user of an important activity. ユーザーが通知をタップすると、ディープリンクがタブに移動し、ユーザーがアクティビティの詳細を表示できるようになります。When the user taps on the notification, the deep link navigates to the tab so the user can view more details about the activity.
  • アプリでは、必要なパラメーターでディープリンクを事前に設定することによって、チャットの作成、会議のスケジュール設定など、特定のユーザータスクを自動化または簡素化します。Your app automates or simplifies certain user tasks, such as creating a chat or scheduling a meeting, by pre-populating the deep links with required parameters. これにより、ユーザーが情報を手動で入力する必要がなくなります。This avoids the need for users to manually enter information.

タブへの詳細なリンクDeep linking to your tab

Teams のエンティティへの詳細なリンクを作成できます。You can create deep links to entities in Teams. 通常、これは、タブ内のコンテンツと情報に移動するリンクを作成するために使用されます。たとえば、タブにタスクリストが含まれている場合は、チームメンバーが個々のタスクへのリンクを作成して共有することがあります。Typically, this is used to create links that navigate to content and information within your tab. For example, if your tab contains a task list team members may create and share links to individual tasks. このリンクをクリックすると、特定の項目を中心とするタブに移動します。When clicked, the link navigates to your tab which focuses on the specific item. これを実装するには、UI に最適な方法で、各アイテムに "リンクのコピー" アクションを追加します。To implement this, you add a "copy link" action to each item, in whatever way best suits your UI. ユーザーがこのアクションを実行すると、を呼び出して、 shareDeepLink() クリップボードにコピーできるリンクを含むダイアログボックスを表示します。When the user takes this action, you call shareDeepLink() to display a dialog box containing a link that the user can copy to the clipboard. この呼び出しを行うと、アイテムの ID も渡されます。この ID は、リンクの後に tab キーが再読み込みされたときに コンテキスト に戻されます。When you make this call, you also pass an ID for your item, which you get back in the context when the link is followed and your tab is reloaded.

または、このトピックで後述する形式を使用して、プログラムによってディープリンクを生成することもできます。Alternatively, you can also generate deep links programmatically, using the format specified later in this topic. これらのメッセージを ボット および コネクタ メッセージで使用して、タブの変更やその中のアイテムについてユーザーに通知することができます。You might want to use these in bot and Connector messages that inform users about changes to your tab, or to items within it.

注意

これは、[ リンクのリンク] タブ メニュー項目で提供されるリンクとは異なり、このタブをポイントするディープリンクのみを生成します。This is different from the links provided by the Copy link to tab menu item, which just generates a deep link that points to this tab.

タブ内のアイテムへの詳細なリンクを含むダイアログボックスを表示するには、 microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })To show a dialog box that contains a deep link to an item within your tab, call microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

次のフィールドを指定します。Provide these fields:

  • subEntityId タブ内で詳細にリンクしているアイテムの一意識別子。subEntityId A unique identifier for the item within your tab to which you are deep linking
  • subEntityLabel ディープリンクの表示に使用するアイテムのラベルsubEntityLabel A label for the item to use for displaying the deep link
  • subEntityWebUrl クライアントがタブのレンダリングをサポートしていない場合に使用するフォールバック URL を含むオプションフィールドsubEntityWebUrl An optional field with a fallback URL to use if the client does not support rendering the tab

注意

静的タブのスコープは "personal" で、構成可能なタブの範囲は "team" です。Static tabs have a scope of "personal" and configurable tabs have a scope of "team". 2つのタブの種類の構文は、構成可能なタブだけに channel コンテキストオブジェクトに関連付けられているプロパティがあるため、構文が若干異なります。The two tab types have a slightly different syntax since only the configurable tab has a channel property associated with its context object. 個人とチームのスコープの詳細については、「 マニフェスト リファレンス」を参照してください。See the Manifest reference for more information on personal and team scopes.

注意

ディープリンクは、タブが v2.0 以降のライブラリを使用して構成されている場合にのみ正しく機能し、そのためにはエンティティ ID を持っている必要があります。Deep links work properly only if the tab was configured using the v0.4 or later library and because of that has an entity ID. エンティティ Id のないタブへの深いリンクは、タブに移動しますが、サブエンティティ ID をタブに提供することはできません。Deep links to tabs without entity IDs still navigate to the tab but can't provide the sub-entity ID to the tab.

Bot、コネクタ、またはメッセージング拡張カードで使用できるディープリンクには、次の形式を使用します。Use this format for a deep link that you can use in a bot, Connector, or messaging extension card:

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

クエリパラメーターは次のとおりです。The query parameters are:

  • appId マニフェストからの ID。たとえば、"fe4a8eba-2a31-4737-8e33-e5fae6fee194" のようになります。appId The ID from your manifest; for example, "fe4a8eba-2a31-4737-8e33-e5fae6fee194"
  • entityId タブ内のアイテムの ID。タブを 構成するときに指定します。たとえば、"tasklist123" のようになります。entityId The ID for the item in the tab, which you provided when configuring the tab; for example, "tasklist123"
  • entityWebUrlまたは、 subEntityWebUrl   クライアントがタブのレンダリングをサポートしていない場合に使用するフォールバック URL を持つオプションフィールド。たとえば、" https://tasklist.example.com/123 " または " https://tasklist.example.com/list123/task456 "entityWebUrl or subEntityWebUrl An optional field with a fallback URL to use if the client does not support rendering the tab; for example, "https://tasklist.example.com/123" or "https://tasklist.example.com/list123/task456"
  • entityLabelまたは、 subEntityLabel   タブ内のアイテムのラベルを使用して、ディープリンクを表示するときに使用します。たとえば、"タスクリスト 123" や "タスク 456" などです。entityLabel or subEntityLabel A label for the item in your tab, to use when displaying the deep link; for example, "Task List 123" or "Task 456"
  • context 次のフィールドを含む JSON オブジェクト。context A JSON object containing the following fields:
    • subEntityId タブ のアイテムの ID。たとえば、"task456" のようになります。subEntityId An ID for the item within the tab; for example, "task456"
    • channelId Microsoft Teams channel ID (タブ コンテキストから使用可能)。たとえば、"19: cbe3683f25094106b826c9cada3afbe0@thread" です。channelId The Microsoft Teams channel ID (available from the tab context; for example, "19:cbe3683f25094106b826c9cada3afbe0@thread.skype". このプロパティは、範囲が "team" である構成可能なタブでのみ使用できます。This property is only available in configurable tabs with a scope of "team". これは、スコープが "personal" である静的タブでは使用できません。It is not available in static tabs, which have a scope of "personal".

例:Examples:

  • 構成可能なタブ自体にリンクします。 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"}Link to a configurable tab itself: 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"}Link to a task item within the configurable tab: 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&label=Task List 123Link to a static tab itself: 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"}Link to a task item within the static tab: 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"}

重要

すべてのクエリパラメーターが正しい URI エンコードになっていることを確認します。Ensure that all query parameters are properly URI encoded. 読みやすくするために、上記の例は含まれていませんが、指定する必要があります。For the sake of readability, the above examples are not, but you should. 最後の例を使用します。Using the last example:

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

深いリンクに移動すると、Microsoft Teams は単にタブに移動し、Microsoft Teams の JavaScript ライブラリを使用して、サブエンティティ ID (存在する場合) を取得するためのメカニズムを提供します。When navigating to a deep link, Microsoft Teams simply navigates to the tab and provides a mechanism via the Microsoft Teams JavaScript library to retrieve the sub-entity ID (if it exists).

この microsoftTeams.getContext 呼び出しは、 subEntityId ディープリンクを介してタブが移動された場合に、フィールドを含むコンテキストを返します。The microsoftTeams.getContext call returns a context that includes the subEntityId field if the tab was navigated to via a deep link.

タブからの詳細なリンクDeep linking from your tab

タブから Teams のコンテンツにディープリンクすることができます。これは、チャネル、メッセージ、別のタブなど、Teams の他のコンテンツにリンクする必要がある場合や、スケジュール設定ダイアログを開く場合にも役立ちます。You can deeplink to content in Teams from your tab. This is useful if your tab needs to link to other content in Teams such as to a channel, message, another tab or even to open a scheduling dialog. タブからディープリンクを開始するには、次のように呼び出します。To trigger a deeplink from your tab you should call:

microsoftTeams.executeDeepLink(/*deepLink*/);

これにより、正しい URL に移動するか、スケジュール設定またはアプリのインストールダイアログを開くなど、クライアントの動作を開始することができます。This will navigate you to the correct URL, or trigger a client action such as opening a scheduling or app install dialog. 例: Example:

// Open a scheduling dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=test%3Acontent");

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/f46ad259-0fe5-4f12-872d-c737b174bcb4");

チャットへの詳細なリンクDeep linking to a chat

参加者のセットを指定することによって、ユーザー間のプライベートチャットへの詳細なリンクを作成できます。You can create deep links to private chats between users by specifying the set of participants. 指定した参加者のチャットが存在しない場合、リンクによってユーザーは空の新しいチャットに移動されます。If a chat doesn't exist with the specified participants, the link will navigate the user to an empty new chat. 新しいチャットは、ユーザーが最初のメッセージを送信するまで下書き状態で作成されます。New chats will be created in draft state until the user sends the first message. 必要に応じて、チャットの名前 (まだ存在しない場合)、およびユーザーの新規作成ボックスに挿入するテキストを指定できます。Optionally, you can specify the name of the chat (if it doesn't already exist), along with text that should be inserted into the user's compose box. この機能は、ユーザーが手動でチャットに移動したり、メッセージを入力したりする操作を実行するためのショートカットと考えることができます。You can think of this feature as a shortcut for the user taking the manual action of navigating to or creating the chat, and then typing out the message.

ユースケースの例として、ボットから Office 365 ユーザープロファイルをカードとして返す場合、このディープリンクを使用すると、その人物と簡単にチャットすることができます。As an example use case, if you are returning an Office 365 user profile from your bot as a card, this deep link can allow the user to easily chat with that person.

Bot、コネクタ、またはメッセージング拡張カードで使用できるディープリンクには、次の形式を使用します。Use this format for a deep link that you can use in a bot, Connector, or messaging extension card:

https://teams.microsoft.com/l/chat/0/0?users=<user1>,<user2>,...&topicName=<chat name>&message=<precanned text>

例: https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrowExample: https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow

クエリパラメーターは次のとおりです。The query parameters are:

  • users チャットの参加者を表すユーザー Id のコンマ区切りのリスト。users The comma-separated list of user IDs representing the participants of the chat. アクションを実行するユーザーは、常に参加者として含まれます。The user performing the action is always included as a participant. 現時点では、ユーザー ID フィールドは Azure AD UserPrincipalName のみをサポートしています (通常はメールアドレス)。The User ID field currently only supports the Azure AD UserPrincipalName (typically an email address).
  • topicName 3人以上のユーザーとチャットする場合は、チャットの表示名のオプションフィールド。topicName An optional field for chat's display name, in the case of a chat with 3 or more users. このフィールドが指定されていない場合、チャットの表示名は参加者の名前に基づきます。If this field is not specified, the chat's display name will be based on the names of the participants.
  • message 現在のユーザーの新規作成ボックスに挿入するメッセージテキストのオプションフィールドで、チャットは下書きの状態になっています。message An optional field for the message text that you want to insert into the current user's compose box while the chat is in a draft state.

この深いリンクを bot と組み合わせて使用するには、カードのボタンの URL のターゲットとしてこれを指定するか、アクションの種類の [アクション] をタップし openUrl ます。To use this deep link with your bot, you can specify this as the URL target in your card's button or tap action through the openUrl action type.

[スケジュール] ダイアログにリンクするLinking to the scheduling dialog

注意

この機能は現在、開発者向けプレビューに含まれています。This feature is currently in developer preview.

Teams クライアントの組み込みのスケジュールダイアログへの詳細なリンクを作成できます。You can create deep links to the Teams client's built-in scheduling dialog. これは、ユーザーが予定表またはスケジュール関連のタスクを完了するのにアプリが役立つ場合に特に便利です。This is especially useful if your app helps the user complete calendar or scheduling-related tasks.

Bot、コネクタ、またはメッセージング拡張カードで使用できるディープリンクには、次の形式を使用します。 https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...Use this format for a deep link that you can use in a bot, Connector, or messaging extension card: https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...

例: https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=test%3AcontentExample: https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=test%3Acontent

クエリパラメーターは次のとおりです。The query parameters are:

  • attendees 会議の出席者を表すユーザー Id のコンマ区切りリスト (オプション)。attendees The optional comma-separated list of user IDs representing the attendees of the meeting. アクションを実行するユーザーは、会議の開催者です。The user performing the action is the meeting organizer. 現時点では、ユーザー ID フィールドは Azure AD UserPrincipalName のみをサポートしています (通常はメールアドレス)。The User ID field currently only supports the Azure AD UserPrincipalName (typically an email address).
  • startTime イベントのオプションの開始時刻。startTime The optional start time of the event. これは、"2018-03-12T23:55:25 + 02:00" のような 長い ISO 8601 形式にする必要があります。This should be in long ISO 8601 format, for example “2018-03-12T23:55:25+02:00”.
  • endTime イベントのオプションの終了時刻 (ISO 8601 形式の場合もあります)。endTime The optional end time of the event, also in ISO 8601 format.
  • subject 会議の件名のオプションフィールド。subject An optional field for the meeting subject.
  • content 会議の詳細フィールドのオプションフィールド。content An optional field for the meeting details field.

現在、場所を指定することはサポートされていません。Currently, specifying the location is not supported. 開始時刻と終了時刻を生成するときは、必ず UTC オフセット (タイムゾーン) を指定してください。When generating your start and end times be sure to specify the UTC offset (time zones).

この深いリンクを bot と組み合わせて使用するには、カードのボタンの URL のターゲットとしてこれを指定するか、アクションの種類の [アクション] をタップし openUrl ます。To use this deep link with your bot, you can specify this as the URL target in your card's button or tap action through the openUrl action type.