タスク モジュールを呼び出して閉じる

タスク モジュールは、タブ、ボット、またはディープ リンクから呼び出すことができます。 応答は、HTML、JavaScript、または Adaptive Card のいずれかになります。 タスク モジュールの呼び出し方法と、ユーザーの操作に対する応答の処理の方法に関しては、多くの柔軟性があります。 次の表はこのしくみを纏めています:

使用して呼び出される HTML または JavaScript を使用したタスク モジュール Adaptive Card を使用したタスク モジュール
タブ内の JavaScript 1. オプション submitHandler(err, result) のコールバック関数 tasks.startTask() を使用して、Teams クライアント SDK 関数を使用します。

2. タスク モジュール コードで、ユーザーがアクションを実行したら、result オブジェクトをパラメーターとして Teams SDK 関数 tasks.submitTask() を呼び出します。 コールバック submitHandlertasks.startTask() で指定されている場合、result をパラメーターとして Teams を呼び出します。 tasks.startTask() の呼び出し時にエラーが発生した場合は、代わりに文字列 err を使用して submitHandler 関数が呼び出されます。

3. teams.startTask() を呼び出すときに completionBotId を指定することもできます。 その後、代わりに result がボットに送信されます。
1. TaskInfo オブジェクト と、タスク モジュール ポップアップに表示する Adaptive Card の JSON を含む TaskInfo.card を使用して、Teams クライアント SDK 関数 tasks.startTask() を呼び出します。

2. tasks.startTask() でコールバック submitHandler が指定されているとき、tasks.startTask() を呼び出すときにエラーが発生した場合、または右上の X を使用してタスク モジュール ポップアップを閉じた場合、Teams は文字列 err を使用してコールバックを呼び出します。

3. ユーザーが Action.Submit ボタンを押すと、そのオブジェクト dataresult の値として返されます。
ボット カード ボタン 1. ボット カード ボタンは、ボタンの種類に応じて、ディープ リンク URL またはメッセージ task/fetch の送信という 2 つの方法で、タスク モジュールを呼び出すことができます。

2. ボタンのアクション typetask/fetch であり、それは Adaptive Card のボタンの種類 Action.Submit である場合は、HTTP POST イベント task/fetch invoke がボットに送信されます。 ボットは HTTP 200 で POST に応答し、応答本文には TaskInfo オブジェクトのラッパーが含まれています。 詳細については、「task/fetchを使用したタスク モジュールの呼び出し」を参照してください。 Teams はタスク モジュールを表示します。

3. ユーザーがアクションを実行したら、オブジェクト result をパラメーターとして指定して、Teams SDK 関数 tasks.submitTask() を呼び出します。 ボットは、オブジェクト result を含むメッセージ task/submit invoke を受け取ります。

4. メッセージ task/submit に応答する 3 つの方法があります。タスクが正常に完了したことを何も行わないか、ポップアップ ウィンドウでユーザーにメッセージを表示するか、別のタスク モジュール ウィンドウを呼び出すか、です。 詳細については、次の詳細な説明を参照してくださいtask/submit
  • Bot Framework カードのボタンと同様に、Adaptive Card のボタンでは、タスク モジュールの呼び出しについて、ボタン Action.openUrl を含むディープ リンク URL、およびボタン Action.Submit を使用する task/fetch の 2 つの方法がサポートされています。


  • Adaptive Card を使用するタスク モジュールは、HTML または JavaScript のケースとよく似ています。 主な違いは、Adaptive Card を使用しているときに JavaScript がないため、tasks.submitTask() を呼び出す方法がないことです。 代わりに、Teams はAction.Submitからオブジェクト data を取得し、イベント task/submit のペイロードとして返します。 詳細については、「task/submitの柔軟性」を参照してください。
ディープ リンク URL
URL 構文
1. Teams は、ディープ リンクの url パラメーター内で指定された <iframe> 内に表示される URL で示されるタスク モジュールを呼び出します。 コールバック submitHandler はありません。

2. タスク モジュールのページの JavaScript 内で、 tasks.submitTask() を呼び出して、タブまたはボット カード ボタンから呼び出すときと同じように、パラメーターとしてオブジェクト result 内で閉じます。 ただし、完了ロジックは若干異なります。 ボットがない場合で完了ロジックがクライアント上に存在する場合は、コールバック submitHandler がないため、tasks.submitTask() の呼び出しの前のコードに完了ロジックが含まれている必要があります。 呼び出しエラーは、コンソール経由でのみ報告されます。 ボットがある場合は、ディープ リンクでパラメーター completionBotId を指定して、イベント task/submit を介してオブジェクト result を送信できます。
1. Teams は、ディープ リンクのパラメーター card の URL エンコード値として指定された Adaptive Card の JSON カード本体であるタスク モジュールを呼び出します。

2. ユーザーは、タスク モジュールの右上にある X を選択するか、カードのボタン Action.Submit を押して、タスク モジュールを閉じます。 呼び出す submitHandler がないため、ユーザーは Adaptive Card フィールドの値を送信するボットを持っている必要があります。 ユーザーはディープ リンクのパラメーター completionBotId を使用して、イベント task/submit invoke を使用してデータを送信するボットを指定する必要があります。

次のセクションでは、タスク モジュールの特定の属性を定義するオブジェクト TaskInfo を指定します。

TaskInfo オブジェクト

オブジェクト TaskInfo には、タスク モジュールのメタデータが含まれています。 埋め込み iFrame のための url またはAdaptive Card のための card を定義します。 次の表は、オブジェクト定義を提示します:

属性 種類 説明
title string この属性は、アプリ名の下とアプリ アイコンの右側に表示されます。
height number または string この属性は、タスク モジュールの高さをピクセル単位で表す数値、または smallmedium、または large を指定します。 詳細については、「タスク モジュールのサイズ策定」を参照してください。
width number または string この属性は、タスク モジュールの幅をピクセル単位で表す数値、または smallmedium、または large で指定します。 詳細については、「タスク モジュールのサイズ策定」を参照してください。
url string この属性は、タスク モジュール内の <iframe> として読み込まれたページの URL です。 URL のドメインは、アプリのマニフェストにアプリの validDomains 配列 に含まれている必要があります。
card Adaptive Card または Adaptive Card ボット カードの添付ファイル この属性は、タスク モジュールに表示される Adaptive Card 向けの JSON です。 ユーザーがボットから呼び出している場合は、Bot Framework オブジェクト attachment でAdaptive Card JSON を使用します。 タブから、ユーザーは Adaptive Card を使用する必要があります。 詳細については、「Adaptive Card またはAdaptive Card ボット カードの添付ファイル」を参照してください。
fallbackUrl string クライアントがタスク モジュール機能をサポートしていない場合、この属性はブラウザー タブ内で URL を開きます。
completionBotId string この属性は、ユーザーがタスク モジュールとやり取りした結果を送信するボット App ID を指定します。 指定した場合、ボットはイベント ペイロードに JSON オブジェクトを含むイベント task/submit invoke を受け取ります。

注意

タスク モジュール機能では、読み込む URL のドメインが、アプリのマニフェストの配列 validDomains に含まれている必要があります。

次のセクションでは、ユーザーがタスク モジュールの高さと幅を設定できるように、タスク モジュールのサイズを指定します。

タスク モジュールのサイズ設定

TaskInfo.width および TaskInfo.height に整数を使用して、タスク モジュールの高さと幅をピクセル単位で設定します。 ただし、Teams のウィンドウのサイズと画面の解像度に応じて、幅または高さの縦横比を維持しながら比例して縮小されます。

TaskInfo.widthTaskInfo.height"small""medium"、または "large" の場合、次の図の赤い四角形のサイズは、使用可能な領域の割合、width の場合は 20%、50%、60% で、height の場合は 20%、50%、66% です:

タスク モジュールの例

タブから呼び出されたタスク モジュールのサイズを動的に変更できます。 tasks.startTask() を呼び出した後、newSize オブジェクトの高さプロパティと幅プロパティが TaskInfo 仕様に準拠する tasks.updateTask(newSize) を呼び出すことができます。 例えば { height: 'medium', width: 'medium' } です。

次のセクションでは、YouTube ビデオと Power Apps にタスク モジュールを埋め込む例を示します。

HTML または JavaScript タスク モジュール用のタスク モジュール CSS

HTML または JavaScript ベースのタスク モジュールは、ヘッダーの下にあるタスク モジュールの領域全体にアクセスできます。 柔軟性は非常に高くなりますが、エッジを埋め込んでヘッダー要素に合わせ、不要なスクロール バーを回避する場合は、ユーザーが適切な CSS を提供する必要があります。 次のセクションでは、2、3 のユース ケースについて幾つかの例を示します。

例 1: YouTube ビデオ

YouTube では、Web ページにビデオを埋め込むことができます。 単純なスタブ Web ページを使用して、タスク モジュール内の Web ページにビデオを簡単に埋め込むことができます。

YouTube の例

次のコードは、CSS を含まない Web ページの HTML の例を示しています:

<!DOCTYPE html>
<html lang="en">
<head>
  ⋮
</head>
<body>
  <div id="embed-container">
    <iframe width="1000" height="700" src="https://www.youtube.com/embed/rd0Rd8w3FZ0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen=""></iframe>
  </div>
</body>
</html>

次のコードは、CSS の例を示しています:

#embed-container iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 95%;
    height: 95%;
    padding-left: 20px;
    padding-right: 20px;
    padding-top: 10px;
    padding-bottom: 10px;
    border-style: none;
}

例 2: Power Apps

ユーザーは同じ方法を使用して Power Apps を埋め込むことができます。 個々の Power Apps の高さや幅をカスタマイズできるため、ユーザーは高さと幅を調整して目的のプレゼンテーションを実現できます。

Power Apps

次のコードは、Power Apps 用の HTML の例を示しています:

<iframe width="720" height="520" src="https://web.powerapps.com/webplayer/iframeapp?source=iframe&screenColor=rgba(104,101,171,1)&appId=/providers/Microsoft.PowerApps/apps/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></iframe>

次のコードは、CSS の例を示しています:

#embed-container iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 94%;
    height: 95%;
    padding-left: 20px;
    padding-right: 20px;
    padding-top: 10px;
    padding-bottom: 10px;
    border-style: none;
}

次のセクションでは、Adaptive Card またはAdaptive Card ボット カードの添付ファイルを使用してカードを呼び出す方法について詳しく説明します。

Adaptive Card または Adaptive Card ボット カードの添付ファイル

card の呼び出し方法に応じて、Adaptive Card またはAdaptive Card ボット カードの添付ファイルを使用する必要があります。これは、添付ファイル オブジェクトにラップされた Adaptive Card です。

タブから呼び出す場合、ユーザーはAdaptive Card を使用する必要があります。

次のコードは、Adaptive Card の例を示しています:

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "TextBlock",
            "text": "Here is a ninja cat:"
        },
        {
            "type": "Image",
            "url": "http://adaptivecards.io/content/cats/1.png",
            "size": "Medium"
        }
    ],
    "version": "1.0"
}

次のコードは、ボットから呼び出すときのAdaptive Card ボット カードの添付ファイルの例を示しています:

{
    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": {
        "type": "AdaptiveCard",
        "body": [
            {
                "type": "TextBlock",
                "text": "Here is a ninja cat:"
            },
            {
                "type": "Image",
                "url": "http://adaptivecards.io/content/cats/1.png",
                "size": "Medium"
            }
        ],
        "version": "1.0"
    }
}

次のセクションでは、TaskInfo オブジェクト、APP_IDBOT_APP_ID など、タスク モジュールのディープ リンク構文について詳しく説明します。

タスク モジュールのディープ リンクは、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 オブジェクト」を参照してください。

ヒント

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

次の表に、APP_IDBOT_APP_ID に関する情報を示します:

必須 説明
APP_ID string はい タスク モジュールを呼び出すアプリの IDAPP_IDのマニフェストの validDomains 配列には、url が URL 内に存在する場合、urlのドメインが含まれている必要があります。 タスク モジュールがタブまたはボットから呼び出された場合、アプリ ID は既にわかっています。それが、アプリ ID が TaskInfo に含まれていない理由です。
BOT_APP_ID 文字列 いいえ completionBotId の値を指定した場合、オブジェクト result はメッセージ task/submit invoke を使用して指定したボットに送信されます。 アプリのマニフェストで BOT_APP_ID はボットとして指定する必要があります。つまり、どのボットにも送信できません。

注意

アプリに、アプリの ID として使用できる 1 つの推奨ボットがある場合、多くの場合 APP_IDBOT_APP_ID は同じにすることができます。

次のセクションでは、アプリのタスク モジュールでキーボードを使用する方法について詳しく説明します。

キーボードとアクセシビリティのガイドライン

HTML または JavaScript ベースのタスク モジュールでは、アプリのタスク モジュールをキーボードで使用できることを確認する必要があります。 スクリーン リーダー プログラムは、キーボードを使用して移動する機能にも依存します。 これには、次の 2 つのことを含みます:

  • HTML タグで tabindex 属性 を使用して、フォーカスできる要素を制御します。 また、tabindex 属性を使用して、通常の Tab キーShift-Tabキーを使用してシーケンシャル キーボード ナビゲーションに関係する位置を特定します。

  • タスク モジュールのために JavaScript 内で Esc キーに対応します。 次のコードは、Esc キーに対応する方法の例を示しています:

    // Handle the Esc key
    document.onkeyup = function(event) {
    if ((event.key === 27) || (event.key === "Escape")) {
      microsoftTeams.submitTask(null); // this will return an err object to the completionHandler()
      }
    }
    

Microsoft Teams では、タスク モジュール ヘッダーから HTML へのキーボード ナビゲーションが正しく機能し、その逆も確実に行われます。

コード サンプル

サンプルの名前 説明 .NET Node.js
タスク モジュールのサンプル ボット - V4 タスク モジュールを作成するためのサンプル。 表示 表示
タスク モジュールのサンプル タブとボット - V3 タスク モジュールを作成するためのサンプル。 表示 表示

次の手順

関連項目