Bot を使用してアダプティブカードタブを構築する - Teams

Teams のアダプティブカードタブには、情報を表示するための一意の方法が用意されています。 Web コンテンツを iFrame に埋め込む代わりに、アダプティブカードをタブにレンダリングできます。フロントエンドはアダプティブカードでレンダリングされますが、バックエンドはボットによって動作します。ボットは、要求を受け入れ、レンダリングされたアダプティブカードで適切に応答します。

警告

アダプティブカードタブは、新しい Teams クライアントでは使用できません。クラシック Teams クライアントは、2024 年 3 月 31 日までに非推奨となる予定です。アプリでアダプティブカードタブを使用している場合は、 Web ベースのタブとしてタブを再構築することをお勧めします。

デスクトップ、Web、モバイルにネイティブな関連ユーザーインターフェイス (UI) の構成要素を使用してタブを構築できます。

この記事は、次の内容を理解するのに役立ちます。

アプリマニフェストに対して行う必要がある変更。
呼び出しアクティビティがアダプティブカードを使用してタブで情報を要求および送信する方法を識別します。
ダイアログ (TeamsJS v1.x のタスクモジュールと呼ばれる) ワークフローへの影響。

このステップバイステップガイドは、デスクトップとモバイルでアダプティブカードを使用してタブを構築するのに役立ちます。次の出力が表示されます。

ステップバイステップガイドが正常に完了した後のタブアダプティブカード出力のスクリーンショット。

前提条件

残り 15 分

次のツールをインストールし、開発環境を設定していることを確認します。

	インストール	使用するには...
	Microsoft Teams	Microsoft Teams、チャット、会議、通話を 1 か所で行うためにアプリを通じて作業するすべてのユーザーと共同作業を行うことができます。
	Visual Studio 2022	Visual Studio 2022 でエンタープライズバージョンをインストールし、ASP.NET および Web 開発ワークロードをインストールできます。最新バージョンを使用します。
	.NET Core SDK	ローカルデバッグと Azure Functions アプリのデプロイ用にカスタマイズされたバインド。最新バージョンを使用するか、移植可能なバージョンをインストールします。
	開発トンネル	Teams アプリの機能 (会話型ボット、メッセージ拡張機能、受信 Webhook) には、受信接続が必要です。トンネルは、開発システムを Teams に接続します。開発トンネルは、localhost をインターネットに安全に開き、アクセス権を持つユーザーを制御するための強力なツールです。開発トンネルは、Visual Studio 2022 バージョン 17.7.0 以降で使用できます。または ngrok をトンネルとして使用して、開発システムを Teams に接続することもできます。タブのみを含むアプリには必要ありません。このパッケージは、(npm devDependencies を使用して) プロジェクトディレクトリ内にインストールされます。
	Microsoft 365 開発者アカウント	アプリをインストールするための適切なアクセス許可を持つ Teams アカウントにアクセスします。

注:

ngrok をダウンロードしたら、サインアップして authtoken をインストールします。

ローカル環境を設定する

残り 14 分

Microsoft-Teams-Samples を開きます。
[ コード] を選択します。
ドロップダウンメニューから、[ GitHub Desktop で開く] を選択します。
[ 複製] を選択します。

Microsoft Entra アプリを登録する

残り 13 分

Microsoft Entra ID でボットを作成して登録するには、次の手順に従います。

Web サーバーのエンドポイントへの ngrok トンネルを作成します。
Azure Bot サービスにボットを登録する Azure Bot リソースを作成します。
ボットのシングルサインオン (SSO) 認証を有効にするクライアントシークレットを作成します。
Teams チャネルを追加してボットをデプロイします。
作成した ngrok または開発トンネルにメッセージングエンドポイントを追加します。

アプリの登録を追加する

Azure ポータルに移動します。
[アプリの登録] を選択します。
[ + 新規登録] を選択します。
アプリの名前を入力します。
任意の組織ディレクトリ (任意の Microsoft Entra ID テナント - マルチテナント) で [アカウント] を選択します。
[登録] を選択します。

アプリは Microsoft Entra ID に登録されています。アプリの概要ページが表示されます。

注:

さらに使用するために 、アプリケーション (クライアント) ID と ディレクトリ (テナント) ID からアプリ ID を 保存します。

トンネルを作成する

dev tunnel
ngrok

Visual Studio を開きます。
[ 新しいプロジェクトの作成] を選択します。
検索ボックスに「ASP.NET」と入力します。検索結果から [ ASP.NET Core Web App] を選択します。
[次へ] を選択します。
「プロジェクト名」と入力し、[次へ] を選択します。
[作成] を選択します。

概要ウィンドウが表示されます。
デバッグドロップダウンリストで、[Dev Tunnel (アクティブトンネルなし)]>[トンネルの作成]を選択します。...

ポップアップウィンドウが表示されます。
ポップアップウィンドウで次の詳細を更新します。
1. アカウント: Microsoft または GitHub アカウントを入力します。
2. [名前]: トンネルの名前を入力します。
3. トンネルの種類: ドロップダウンリストから [ 一時] を選択します。
4. アクセス: ドロップダウンリストから [パブリック] を選択 します。
[OK] を選択します。

開発トンネルが正常に作成されたことを示すポップアップウィンドウが表示されます。
[OK] を選択します。

作成したトンネルは、次のようにデバッグドロップダウンリストにあります。
F5 キーを押して、デバッグモードでアプリケーションを実行します。
[セキュリティ警告] ダイアログが表示されたら、[はい] を選択します。

ポップアップウィンドウが表示されます。
[続行] を選択します。

開発トンネルのホームページが新しいブラウザーウィンドウで開き、開発トンネルがアクティブになりました。
Visual Studio に移動し、[ 表示] > [出力] を選択します。
[出力コンソール] ドロップダウンメニューで、[Dev Tunnels]\(開発トンネル\) を選択します。

出力コンソールには、開発トンネル URL が表示されます。

ngrok またはコマンドプロンプトを使用して、ローカルで実行されている Web サーバーのパブリックに利用可能な HTTPS エンドポイントへのトンネルを作成します。 ngrok で次のコマンドを実行します。

ngrok http --host-header=localhost 3978

ヒント

ERR_NGROK_4018が発生した場合は、コマンドプロンプトに記載されている手順に従ってサインアップし、ngrok を認証します。 ngrok http --host-header=localhost 3978 コマンドを実行します。

ウィンドウに HTTPS URL が表示されます。

ngrok HTTPS URL を示すスクリーンショット。

Web 認証を追加する

左側のウィンドウの [ 管理] で、[ 認証] を選択します。
[プラットフォームの追加>Web] を選択します。
完全修飾ドメイン名に auth-end を追加して、アプリのリダイレクト URI を入力します。たとえば、https://your-devtunnel-domain/auth-end および https://your-ngrok-domain/auth-end が禁止となります。
[ 暗黙的な許可とハイブリッドフロー] で、[ アクセストークン と ID トークン ] チェックボックスをオンにします。
[構成] を選択します。
[ Web] で、[ URI の追加] を選択します。
https://token.botframework.com/.auth/web/redirect を入力します。
[保存] を選択します。

クライアントシークレットを作成する

左側のウィンドウの [ 管理] で、[ 証明書 & シークレット] を選択します。
[ クライアントシークレット] で、[ + 新しいクライアントシークレット] を選択します。

[ クライアントシークレットの追加] ウィンドウが表示されます。
「説明」と入力します。
[追加] を選択します。
[ 値] で、[ クリップボードにコピー ] を選択して、クライアントシークレットの値を保存して、さらに使用します。

API アクセス許可の追加

左側のウィンドウの [ 管理] で、[ API のアクセス許可] を選択します。
[ + アクセス許可の追加] を選択します。
[Microsoft Graph] を選択します。
[委任されたアクセス許可] を選択します。
[ User.Read in permission]\(User.Read in アクセス許可\) を選択します。
[アクセス許可の追加] を選択します。
注:
- アプリに IT 管理者の同意が付与されていない場合、ユーザーは初めてアプリを使用する際に同意を提供する必要があります。
- ユーザーは、Microsoft Entra アプリが別のテナントに登録されている場合にのみ、API のアクセス許可に同意する必要があります。

アプリケーション ID URI の追加

左側のウィンドウの [ 管理] で、[ API の公開] を選択します。
[アプリケーション ID URI] の横にある [追加] を選択します。
アプリケーション ID URI をapi://your-devtunnel-domain/botid-{AppID}またはapi://your-ngrok-domain/botid-{AppID}形式で更新し、[保存] を選択します。

次の図は、ドメイン名を示しています。

スコープを追加する

左側のウィンドウの [ 管理] で、[ API の公開] を選択します。
[ + スコープの追加] を選択します。
スコープ名として「access_as_user」と入力します。
[ 同意できるユーザー] で、[ 管理者とユーザー] を選択します。
残りのフィールドの値を次のように更新します。
- 「Teams は管理者の同意表示名としてユーザーのプロファイルにアクセスできます」と入力します。
- 「Teams でアプリの Web API を現在のユーザーとして管理者の同意の説明として呼び出すことができます」と入力します。
- 「Teams」と入力すると、ユーザープロファイルにアクセスし、ユーザーの代わりにユーザーの同意表示名として要求を行うことができます。
- ユーザーの同意の説明と同じ権限を持つこのアプリの API を呼び出すには、「Teams を有効にする」と入力します。
[状態] が [有効] に設定されていることを確認してください。
[スコープの追加] を選択します。

次の図は、フィールドと値を示しています。

注:

スコープ名は、最後に追加/access_as_userアプリケーション ID URI と一致する必要があります。

クライアントアプリケーションを追加する

左側のウィンドウの [ 管理] で、[ API の公開] を選択します。

[ 承認されたクライアントアプリケーション] で、アプリの Web アプリケーションに対して承認するアプリケーションを特定します。
[ + クライアントアプリケーションの追加] を選択します。
Teams モバイルまたはデスクトップと Teams Web アプリケーションを追加します。
1. Teams モバイルまたはデスクトップの場合: 1fec8e78-bce4-4aaf-ab1b-5451cc387264としてクライアント ID を入力します。
2. Teams Web の場合: 5e3ce6c0-2b1f-4285-8d4b-75ee78787346としてクライアント ID を入力します。
[ 承認されたスコープ ] チェックボックスをオンにします。
[アプリケーションの追加] を選択します。

次の図は、 クライアント ID を表示します。

ボットを作成する

残り 8 分

ボットサービスでユーザーがボットにサインインしてアクセスできるようにするには、ボットのシングル Sign-On (SSO) を構成する必要があります。次の手順を実行して構成します。

Azure Bot リソースにリダイレクト URI を追加します。
ダウンストリーム呼び出しに必要な API アクセス許可を追加します。
暗黙的な許可とハイブリッドフローを有効にします。
アプリマニフェストを更新します。
ボットサービス接続を設定します。

Azure ボットリソースを作成する

注:

Teams でボットを既にテストしている場合は、このアプリと Teams からサインアウトします。この変更を確認するには、もう一度サインインします。

[ホーム] に移動します。
[ + リソースの作成] を選択します。
検索ボックスに「 Azure Bot」と入力します。
Enter キーを押します。
[ Azure Bot] を選択します。
[作成] を選択します。
ボットハンドルにボット名を入力します。
ドロップダウンリストから [サブスクリプション] を選択します。
ドロップダウンリストから [リソースグループ] を選択します。

既存のリソースグループがない場合は、新しいリソースグループを作成できます。新しいリソースグループを作成するには、次の手順に従います。
1. [ 新規作成] を選択します。
2. リソース名を入力し、[ OK] を選択します。
3. [ 新しいリソースグループの場所 ] ドロップダウンリストから場所を選択します。
[ 価格] で、[ プランの変更] を選択します。
[ FO Free>Select] を選択します。
[Microsoft アプリ ID] で、[マルチテナントとしてのアプリの種類] を選択します。
[ 作成の種類] で、[ 既存のアプリの登録を使用する] を選択します。
アプリ ID を入力します。

注:

同じ Microsoft アプリ ID を持つ複数のボットを作成することはできません。
[確認 + 作成] を選びます。
検証に合格したら、[ 作成] を選択します。

ボットのプロビジョニングには数分かかります。
[リソースに移動] を選びます。

Azure ボットが正常に作成されました。

Teams チャネルを追加する

左側のウィンドウで、[チャネル] を選択 します。
[ 使用可能なチャネル] で、[ Microsoft Teams] を選択します。
チェックボックスをオンにして 、利用規約に同意します。
[ 同意する] を選択します。
[適用] を選択します。

メッセージングエンドポイントを追加するには

dev tunnel
ngrok

出力コンソールの開発トンネル URL をメッセージングエンドポイントとして使用します。
左側のウィンドウの [ 設定] で、[ 構成] を選択します。
メッセージングエンドポイントを https://your-devtunnel-domain/api/messages 形式で更新します。
[適用] を選択します。

Azure Bot サービスでボットが正常に設定されました。

注:

Application Insights Instrumentation キーにエラーが表示される場合は、アプリ ID で更新します。

ngrok から HTTPS URL をコピーします。

注:

ngrok の HTTPS URL は、完全修飾ドメイン名です。 WebAppDomainは、https://を含まない完全修飾ドメイン名です。
左側のウィンドウの [ 設定] で、[ 構成] を選択します。
メッセージングエンドポイントを https://your-ngrok-domain/api/messages 形式で更新します。
[適用] を選択します。

Azure Bot サービスでボットを正常に設定しました。

注:

Application Insights Instrumentation キーにアプリ ID を使用したエラー更新が表示される場合。

マニフェストファイルを更新する

左側のウィンドウで [マニフェスト] を選択します。
構成項目 "accessTokenAcceptedVersion":2 を設定します。設定されていない場合は、その値を 2 に変更し、[保存] を選択 します。

注:

Teams でボットを既にテストしている場合は、このアプリからサインアウトして Teams からサインアウトします。この変更を確認するには、もう一度サインインします。

Bot Service 接続を設定するには

[構成] ページに移動します。
[OAuth 接続設定の追加] を選択します。
[ 新しい接続設定] に、次の詳細を入力します。
- [名前]: 新しい接続設定の名前を入力します。名前は、ボットサービスコードの設定で使用できます。
- サービスプロバイダー: [Azure Active Directory v2] を選択します。
- クライアント ID: Microsoft アプリ ID を更新します。
- クライアントシークレット: クライアントシークレット ID の値を更新します。
- トークン交換 URL: アプリケーション ID URI を使用します。
- テナント ID: 共通を入力します。
- スコープ: User.Read と入力します。
[保存] を選択します。

アプリ設定とマニフェストファイルを設定する

残り 6 分

複製されたリポジトリ内の appsettings.json ファイルに移動します。
appsettings.json ファイルを開き、次の情報を更新します。
- "MicrosoftAppId"をボットの Microsoft アプリ ID に置き換えます。
- "MicrosoftAppPassword"をボットのクライアントシークレットの値に置き換えます。
- "ConnectionName"をボットの名前に置き換えます。
- "ApplicationBaseUrl"を ngrok または dev tunnel ドメイン名に置き換えます。
複製されたリポジトリ内の manifest.json ファイルに移動します。
manifest.json ファイルを開き、次の変更を更新します。
{contentBotId}と{Microsoft App ID}のすべての出現箇所をボットの Microsoft アプリ ID に置き換えます。

サービスをビルドして実行する

残り 5 分

サービスをビルドして実行するには、Visual Studio を使用します。

Visual Studio を開きます。
[ファイル>Open>Project/Solution..] に移動します。
csharp>TabWithAdpativeCardFlow フォルダーから TabWithAdpativeCardFlow.csproj ファイルを選択します。
F5 キーを押してプロジェクトを実行します。プロジェクトは、適切なフォルダー内の Visual Studio または .NET を使用して実行できます。

Web ページにメッセージが表示され、 ボットの準備ができました。

Teams でアプリを構成してアップロードする

残り 4 分

複製したリポジトリで、 csharp>TabWithAdpativeCardFlow>AppManifest に移動します。
AppManifest フォルダーに存在する次のファイルを含む .zip ファイルを作成します。
- manifest.json
- outline.png
- color.png
  
  注:
  
  manifest.zipに追加のフォルダーを含めてはなりません。これには、 マニフェスト json ソースファイル、色アイコン、および zip フォルダー内の アウトライン アイコンが必要です。
Teams クライアントで、[ アプリ ] アイコンを選択します。
[アプリの管理] を選択します。
[ アプリのアップロード] を選択します。
[カスタムアプリのアップロード] オプションを探します。オプションが表示された場合は、カスタムアプリのアップロードが有効になります。
TeamsAppManifest フォルダーに作成した .zip ファイルを選択し、[開く] を選択します。
[追加] を選択します。

サインインすることで、このタブを操作できます。
タブにメッセージを送信します。