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

[アーティクル]
11/18/2024

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

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

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

構成

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

再構成

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

ボットとタブの機能をサポートするアプリの既定のランディング機能としてボットを構成するには、「既定のランディング機能を構成する」を参照してください。

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

注:

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

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

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

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

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

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

"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/fetchまたはconfig/submitが開始されます。

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

false: ボットはダイアログまたはアダプティブカードをフェッチしません。代わりに、ボットは、ボットの呼び出し時に使用される静的ダイアログまたはカードを提供する必要があります。詳細については、「ダイアログ」を参照してください。
true: ボットは、定義された config/fetch または config/submit を開始します。ボットが呼び出されると、 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` 応答の種類を使用したグループチャットについて説明します。	表示	表示	表示

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

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

次の方法で共有

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

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

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

ボットを構成する

ベストプラクティス

コードサンプル

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

関連項目

その他のリソース

次の方法で共有

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

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

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

ボットを構成する

ベスト プラクティス

コード サンプル

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

関連項目

その他のリソース

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

ベストプラクティス

コードサンプル

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