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

[アーティクル]
05/02/2022

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

使用して呼び出される HTML または JavaScript を使用したタスクモジュール Adaptive Card を使用したタスクモジュール

タブ内の JavaScript 1. オプション submitHandler(err, result) のコールバック関数 tasks.startTask() を使用して、Teams クライアント SDK 関数を使用します。

2. タスクモジュールコードで、ユーザーがアクションを実行したら、result オブジェクトをパラメーターとして Teams SDK 関数 tasks.submitTask() を呼び出します。コールバック submitHandler が tasks.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 ボタンを押すと、そのオブジェクト data が result の値として返されます。

ボットカードボタン

使用して呼び出される	HTML または JavaScript を使用したタスクモジュール	Adaptive Card を使用したタスクモジュール
タブ内の JavaScript	1. オプション `submitHandler(err, result)` のコールバック関数 `tasks.startTask()` を使用して、Teams クライアント SDK 関数を使用します。 2. タスクモジュールコードで、ユーザーがアクションを実行したら、`result` オブジェクトをパラメーターとして Teams SDK 関数 `tasks.submitTask()` を呼び出します。コールバック `submitHandler` が `tasks.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` ボタンを押すと、そのオブジェクト `data` が `result` の値として返されます。
ボットカードボタン	1. ボットカードボタンは、ボタンの種類に応じて、ディープリンク URL またはメッセージ `task/fetch` の送信という 2 つの方法で、タスクモジュールを呼び出すことができます。 2. ボタンのアクション `type` が `task/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` を使用してデータを送信するボットを指定する必要があります。

1. ボットカードボタンは、ボタンの種類に応じて、ディープリンク URL またはメッセージ task/fetch の送信という 2 つの方法で、タスクモジュールを呼び出すことができます。

2. ボタンのアクション type が task/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	この属性は、タスクモジュールの高さをピクセル単位で表す数値、または `small`、`medium`、または `large` を指定します。詳細については、「タスクモジュールのサイズ策定」を参照してください。
`width`	number または string	この属性は、タスクモジュールの幅をピクセル単位で表す数値、または `small`、`medium`、または `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.width と TaskInfo.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_ID、BOT_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_ID と BOT_APP_ID に関する情報を示します:

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

注意

アプリに、アプリの ID として使用できる 1 つの推奨ボットがある場合、多くの場合 APP_ID と BOT_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	タスクモジュールを作成するためのサンプル。	表示	表示

次の手順

タブでタスクモジュールを使用する

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

このページはお役に立ちましたか?

TaskInfo オブジェクト

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

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