拡張機能のための .NET ボットの構成

[アーティクル]
12/26/2023

2023 年 9 月 1 日から、ネットワークの分離に Azure サービスタグメソッドを使用することを強くお勧めします。 DL-ASE の稼働率は、非常に具体的なシナリオに限定する必要があります。運用環境でこのソリューションを実装する前に、サポートチームに相談してガイダンスを受けることをお勧めします。

この記事の対象: SDK v4

この記事では、名前付きパイプを使って機能するように .NET ボットを更新する方法、およびボットがデプロイされている Azure App Service リソースで Direct Line App Service 拡張機能を有効にする方法について説明します。

前提条件

Azure アカウント。まだお持ちでない場合は、開始する前に無料アカウントを作成してください。
Azure でデプロイされる .NET ボット
.NET 向け Bot Framework SDK 4.14.1 以降。

Direct Line App Service 拡張機能を有効にする

このセクションでは、ボットの Direct Line チャンネル構成から App Service 拡張キーを使用して、Direct Line App Service 拡張機能を有効にする方法を説明します。

ボットコードを更新する

Note

Microsoft.Bot.Builder.StreamingExtensions NuGet プレビューパッケージは非推奨になりました。 v4.8 以降、SDK には Microsoft.Bot.Builder.Streaming 名前空間が含まれています。以前にボットでプレビューパッケージを使用していた場合は、次の手順を実行する前にそれらを削除する必要があります。

Visual Studio でボットプロジェクトを開きます。

名前付きパイプの使用をアプリに許可します。

Startup.cs ファイルを開きます。
Microsoft.Bot.Builder.Integration.AspNet.Core NuGet パッケージへの参照を追加します。
```
using Microsoft.Bot.Builder.Integration.AspNet.Core;
```

Configure メソッドで、UseNamedPipes メソッドに呼び出しを追加します。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseDefaultFiles()
        .UseStaticFiles()
        .UseWebSockets()
        // Allow the bot to use named pipes.
        .UseNamedPipes(System.Environment.GetEnvironmentVariable("APPSETTING_WEBSITE_SITE_NAME") + ".directline")
        .UseRouting()
        .UseAuthorization()
        .UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });

    // app.UseHttpsRedirection();
}

Startup.cs ファイルを保存します。

自分の更新ボットを Azure にデプロイする。

ボット Direct Line App Service 拡張機能を有効にする

Azure portal で Azure Bot リソースに移動します。
1. [設定]で、ボットがメッセージを受け入れるチャンネルを構成する[チャンネル]を選択します。
2. まだ有効になっていない場合は、[使用可能なチャンネル] の一覧から Direct Line チャンネルを選択してチャンネルを有効にします。
3. [Direct Line] を有効にした後、[チャンネル] ページからもう一度選択します。
4. [App Service 拡張機能] タブを選択します。
5. [App Service 拡張機能キー] で、対応するキーの横にある目のアイコンを選択します。
ホームページに移動し、ページの上部にある [App Services] を選択します。または、ポータルメニューを表示し、[App Services] メニュー項目を選択します。 Azure に「App Services」ページが表示されます。
検索ボックスに、[Azure Bot] リソース名を入力します。リソースが一覧表示されます。

アイコンまたはメニュー項目にカーソルを合わせると、最後に表示されたリソースの一覧が表示されます。 Azure Bot リソースが一覧表示される可能性があります。

リソースリンクを選択します。

[設定] セクションで、[構成] メニュー項目を選択します。
右のパネルで、次の設定を追加します。

名前値

DirectLineExtensionKey 前にコピーした App Service 拡張キーの値。

DIRECTLINE_EXTENSION_VERSION latest

名前	値
DirectLineExtensionKey	前にコピーした App Service 拡張キーの値。
DIRECTLINE_EXTENSION_VERSION	latest

パブリックポータルを介して Azure にアクセスしない主権者または制限された Azure クラウドでボットがホストされている場合は、次の設定も追加する必要があります。

名前	値
DirectLineExtensionABSEndpoint	ボットがホストされている Azure クラウドに固有のエンドポイント。たとえば、USGov クラウドの場合、エンドポイントは `https://directline.botframework.azure.us/v3/extension` です。

[構成] セクション内から、[全般] 設定セクションをクリックし、[Web ソケット をオンにします。
[保存] を選択して設定を保存します。これにより、Azure App Service が再起動されます。

Direct Line 拡張機能とボットが構成されていることを確認する

ブラウザーで https://<your_app_service>.azurewebsites.net/.bot に移動します。すべて正しければ、このページは次の JSON コンテンツを返します。

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}

v によって、Direct Line App Service 拡張機能のビルドバージョンが表示されます。
k は、拡張機能がその構成から拡張キーを読み取ることができたかどうかを示します。
initialized は、拡張機能が Azure AI Bot Service からボットメタデータをダウンロードできたかどうかを示します。
ib は、拡張機能がボットへの受信接続を確立できたかどうかを示します。
ob は、拡張機能がボットへの送信接続を確立できたかどうかを示します。

トラブルシューティング

.bot エンドポイント によって表示される ib と ob の値が false の場合、ボットと Direct Line App Service 拡張機能は相互に接続できません。
1. 名前付きパイプを使用するためのコードチェックダブルがボットに追加されました。
2. ボットが起動して実行できることを確認します。便利なツールは、WebChat でのテスト、追加のチャネルの接続、リモートデバッグ、またはログ記録です。
3. ボットがホストされている Azure App Service 全体を再起動して、すべてのプロセスのクリーンを確実に開始します。
.bot エンドポイントの初期化された値が false の場合、Direct Line App Service 拡張機能は、上記のボットのアプリケーション設定に追加された App Service 拡張機能キーを検証できません。
1. 値が正しく入力されたことを確認します。
2. ボットの [Direct Line の構成] ページに表示されている代替拡張キーに切り替えます。

プロセス外ホスティングモデルをボットが使用できるようにします。それ以外の場合は、HTTP エラー 500.34 - ANCM 混合ホスティング エラー (ANCM は ASP.NET コアモジュールを表します) が表示されます。このエラーは、ボットテンプレートが既定で InProcess ホスティングモデルを使用しているために発生します。プロセス外ホスティングを構成するには、「アウトプロセスホスティングモデル」を参照してください。詳細については、「aspNetCore 要素の属性」および「web.config による設定」を参照してください。

Direct Line App Service 拡張機能で OAuth を使用しようとして、"対象ユーザーの要求からボット AppId を取得できません" というエラーが発生した場合は、BotFrameworkHttpAdapter で ClaimsIdentity を AudienceClaim に設定します。これを行うには、アダプターをサブクラス化できます。次に例を示します。

public class AdapterWithStaticClaimsIdentity : BotFrameworkHttpAdapter
{
    public AdapterWithStaticClaimsIdentity(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, ConversationState conversationState = null)
        : base(configuration, logger)
    {
        // Manually create the ClaimsIdentity and create a Claim with a valid AudienceClaim and the AppID for a bot using the Direct Line App Service extension.
        var appId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;
        ClaimsIdentity = new ClaimsIdentity(new List<Claim>{
            new Claim(AuthenticationConstants.AudienceClaim, appId)
        });
    }
}

次のステップ

Web チャットを Direct Line App Service 拡張機能と共に使用する