ボット構成エクスペリエンス

[アーティクル]
04/13/2024

ボット構成エクスペリエンスを使用すると、ユーザーはボットの設定をチャネルまたはグループチャットのインストール後に直接設定および再構成できるため、最初から運用効率が向上します。この機能により、以前はアプリの実現をタイムリーに妨げたユーザー介入を繰り返す必要がなくなります。ユーザーは、インストール中にボットを特定のワークフローと好みに合わせて調整し、必要に応じて設定を再構成して、変化する要件に適応し、ボットの継続的な関連性と価値を確保できるようになりました。

たとえば、ニューストピックを追跡して共有したり、GitHub リポジトリを監視したりするボットを考えてみましょう。ユーザーワークフローに合わせて最初に構成されたこれらのボットは、グループチャットから直接新しいトピックまたはリポジトリに応答するように簡単に再構成でき、コンテンツ管理を合理化し、Teams 環境を離れることなく対話できます。この柔軟な構成エクスペリエンスにより、ボットを毎日の運用にシームレスに統合することで、ユーザーエクスペリエンスと生産性が大幅に向上します。

ユーザーがグループチャットにボットを追加し、特定の要件に合わせてボットを構成する例を次に示します。その後、ユーザーはボットを再構成して状態を変更します。

構成

図は、ボットを Teams チャネルに構成するプロセスを示しています。

再構成

メッセージ作成領域のボットの構成オプションを示すスクリーンショット。

ボット構成エクスペリエンスを構築する

注:

ボット構成エクスペリエンスは、チャネルまたはグループチャットでのみサポートされます。

ボット構成エクスペリエンスを構築するときは、ユーザーが最初のインストール時にボットを構成し、いつでも再構成できるようにする必要があります。

ボット構成エクスペリエンスを構築するには、次の手順に従います。

アプリマニフェストの更新
ボットを構成する

アプリマニフェストの更新

アプリマニフェスト (以前は Teams アプリマニフェストと呼ばれる) ファイルで、オブジェクトの下のプロパティをfetchTaskbots.configuration次のように更新します。

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

詳細については、「アプリマニフェストスキーマ」を参照してください。

ボットを構成する

ユーザーがチャネルまたはグループチャットにボットをインストールすると、fetchTaskアプリマニフェストファイル内のプロパティによって、ファイル内teamsBot.jsで定義されているとおりまたはconfig/submitがconfig/fetch開始されます。

アプリマニフェストのプロパティを fetchTask 次のように設定した場合:

false: ボットはダイアログまたはアダプティブカードをフェッチしません。代わりに、ボットは、ボットの呼び出し時に使用される静的ダイアログまたはカードを提供する必要があります。詳細については、「ダイアログ」を参照してください。
true: ボットは、またはconfig/submit定義どおりに開始しますconfig/fetch。ボットが呼び出されると、 channelData と userdata で提供されるコンテキストに応じて、アダプティブカードまたはダイアログを返すことができます。

次の表に、呼び出し要求に関連付けられている応答の種類を示します。

呼び出し要求	応答の種類
`config/fetch`	`Type: "continue"` または `Type = "auth"`
`config/submit`	`Type: "continue"` または `Type: "message"`

type: "continue": type: "continue" は、ボット構成内のダイアログまたはアダプティブカードの継続を定義するために使用されます。型がに continue設定されている場合は、ボットがユーザーからの追加の操作で構成プロセスを続行することを期待していることを示します。

adaptiveCardForContinueは、ボットのワークフローのさまざまな段階で使用されるアダプティブカードの JSON を返すカスタム関数です。これらの関数は、ユーザーとボットとの対話に基づいて、さまざまなシナリオでアダプティブカードを返すために使用されます。

ユーザーが構成を送信すると、呼び出し config/submit がトリガーされます。ユーザーの入力を読み取り、別のアダプティブカードを返します。ボット構成を更新してダイアログを返すこともできます。
- C#
- JavaScript
サンプルコードリファレンス
```
protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = adaptiveCardForContinue();
    return Task.FromResult(response);
}
```
サンプルコードリファレンス
```
async handleTeamsConfigFetch(_context, _configData) {
    let response = {};
    const adaptiveCard = CardFactory.adaptiveCard(this.adaptiveCardForContinue());
    response = {
       config: {
          value: {
             card: adaptiveCard,
             height: 500,
             width: 600,
             title: 'test card',
          },
          type: 'continue',
       },
    };
    return response;
}
```

type: "auth": 要求に対する応答としてユーザーに認証を config/fetch 要求することもできます。構成では type: "auth" 、指定した URL を使用してサインインするようにユーザーに求められます。これは、ブラウザーで開くことができる有効な認証ページにリンクする必要があります。認証は、ボットがユーザーの認証を要求するシナリオに不可欠です。これにより、ユーザーの ID が検証され、セキュリティが維持され、ボットの機能内のエクスペリエンスがカスタマイズされます。

注:

type: "auth"サードパーティ認証のみがサポートされています。シングルサインオン (SSO) はサポートされていません。サードパーティ認証の詳細については、「認証の追加」を参照してください。

C#
JavaScript

サンプルコードリファレンス

protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = new ConfigResponse<BotConfigAuth> {
       Config = new BotConfigAuth {
          SuggestedActions = new SuggestedActions {
             Actions = new List<CardAction> {
                new CardAction {
                   type: "openUrl",
                   value: "https://example.com/auth",
                   title: "Sign in to this app"
                }
             }
          },
       Type = "auth"
    }
};

サンプルコードリファレンス

async handleTeamsConfigFetch(_context, _configData) {
    let response = {};
    response = {
       config: {
          type: "auth",
          suggestedActions: {
             actions: [{
                type: "openUrl",
                value: "https://example.com/auth",
                title: "Sign in to this app"
             }]
          },
      },
    };
    return response;
}

type="message": 型が message に設定されている場合、ボットが単純なメッセージをユーザーに送信していることを示し、対話の終わりを示すか、さらに入力を必要とせずに情報を提供します。

C#
JavaScript

サンプルコードリファレンス

protected override Task<ConfigResponseBase> OnTeamsConfigSubmitAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = new ConfigResponse<TaskModuleResponseBase>
    {
       Config = new TaskModuleMessageResponse
       {
          Type = "message",
          Value = "You have chosen to finish setting up bot"
       }
    };
    return Task.FromResult(response);
}

サンプルコードリファレンス

async handleTeamsConfigSubmit(context, _configData) {
    let response = {};
    response = {
       config: {
          type: 'message',
          value: 'You have chosen to finish setting up bot',
       },
    }
    return response;
}

ユーザーがボットを再構成すると、 fetchTask アプリマニフェストファイルのプロパティがボットロジックで開始されます config/fetch 。ユーザーは、次の 2 つの方法で、インストール後にボット設定を再構成できます。

@mention メッセージ作成領域のボット。メッセージ作成領域の上に表示される [設定] オプションを選択します。ダイアログが表示、更新、またはダイアログでボットの構成設定を変更します。
ボットにカーソルを合わせると、ボットプロファイルカードが表示されます。ボットの構成設定を更新または変更するには、ボットプロファイルカードの設定アイコンを選択します。

ベストプラクティス

ボットの個々のチャネルレベルの構成を作成する場合は、チャネルに従って構成を追跡してください。構成データは格納されておらず、呼び出しペイロードには十分な channelData が含まれています。
URL、エリアパス、ダッシュボードリンクなど、ボットが正常に動作するために必要な情報を入力するようにユーザーに求めるわかりやすいダイアログを提供します。
ユーザーが混乱する可能性があるため、インストール後に複数の通知や構成要求を送信しないようにします。

コードサンプル

サンプルの名前	説明	.NET	Node.js	マニフェスト
ボット構成アプリ	このサンプルコードでは、チーム内のボットとグループチャット `continue` と応答の種類の構成と `message` 再構成について説明します。	表示	表示	表示
認証を使用したボット構成アプリ	このサンプルコードでは、チーム内のボットとグループチャット `auth` と応答の種類の構成と `message` 再構成について説明します。	表示	表示	表示

ステップバイステップのガイド

インストール中、またはボットがインストールされているチームまたはグループチャットからのインストール後にボットを構成するには、ステップバイステップガイドに従います。

ボット構成エクスペリエンス

ボット構成エクスペリエンスを構築する

アプリマニフェストの更新

ボットを構成する

ベストプラクティス

コードサンプル

ステップバイステップのガイド

関連項目

フィードバック

その他のリソース

ボット構成エクスペリエンス

ボット構成エクスペリエンスを構築する

アプリ マニフェストの更新

ボットを構成する

ベスト プラクティス

コード サンプル

ステップ バイ ステップのガイド

関連項目

フィードバック

その他のリソース

アプリマニフェストの更新

ベストプラクティス

コードサンプル

ステップバイステップのガイド