ボットを Direct Line に接続する

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

この記事では、ボットを Direct Line チャネルに接続する方法について説明します。このチャネルを使用して、クライアントアプリケーション経由でボットと通信します。

Note

Direct Line は、クライアントアプリケーションとボット間の通信を可能にする HTTPS プロトコル経由の標準チャネルです。代わりにネットワーク分離が必要な場合は、WebSocket 経由の Direct Line App Service Extension を使用してください。

前提条件

Azure アカウント。まだお持ちでない場合は、開始する前に無料アカウントを作成してください。
Azure に公開された既存のボット。

Direct Line チャネルを追加する

最初に行う必要があるのは、Direct Line チャネルをボットに追加することです。

Azure ポータルにアクセスします。
Azure Bot リソースに移動します。 [ボットの設定] で、[チャネル] を選択します。
利用可能なチャネルのリストから [Direct Line] を選択します。

既定のサイトを使用して Direct Line を使用するようにボットが構成されました。

または、既定のサイトを使用する代わりに、新しいサイトを追加することもできます。 [Direct Line] チャネルページの [新しいサイト] ボタンを選択して、新しいサイトを作成します。 Direct Line new site button in Azure portal

秘密鍵を管理する

ダイレクトチャネルを追加すると、Bot Framework によって秘密鍵が生成されます。クライアントアプリケーションは、これらの鍵を使用して、ボットと通信するために発行する Direct Line API 要求を認証します。詳細については、認証に関するページをご覧ください。

サイトの Direct Line シークレットをプレーンテキストで表示するには、[Direct Line] チャネルページに移動します。
[Direct Line] タブを選択し、キーを取得するサイト (Default_Site など) を選択します。 Azure で [サイトの構成] ウィンドウが開きます。
[秘密鍵] で、対応するキーの横にある目のアイコンを選択します。
鍵をコピーして安全に保管します。この鍵を使用して、クライアントアプリケーションがボットと通信するために発行する Direct Line API 要求を認証します。

Note

シークレットを公開したり、クライアントアプリケーションに埋め込んだりしないでください。「次のステップ」を参照してください。
成功事例は、Direct Line API を使用してキーをトークンと交換することです。その後、クライアントアプリケーションはトークンを使用して、1 つの会話のスコープ内で要求を認証します。

設定の構成

サイト設定を構成するには:

[Direct Line チャネル] ページで、[サイト] リストから構成するサイトを選択します。以下に示すように、[サイトの構成] ウィンドウが開きます:
クライアントアプリケーションがボットとの通信に使用する Direct Line プロトコルのバージョンを選択します。

ヒント

クライアントアプリケーションとボットの間の新しい接続を作成する場合は、Direct Line API 3.0 を使います。
終わったら、[適用] をクリックしてサイトの構成を保存します。ボットに接続するクライアントアプリケーションごとに、このプロセスを [新しいサイトの追加] から繰り返します。

強化された認証を構成する

使用可能なサイト構成の 1 つに拡張認証オプションがあります。これは、ボットに接続するときのセキュリティリスクを軽減するのに役立ちます (たとえば、Web チャットコントロールを使用)。詳細については、「Direct Line 拡張認証」を参照してください。

強化された認証を追加するには

[認証オプションの拡張] を有効にします。「信頼できる配信元が少なくとも 1 つ必要です」というメッセージが、[信頼された配信元の追加] リンクと共に表示されます。拡張認証を有効にする場合は、少なくとも 1 つの信頼された配信元を指定する必要があります。

信頼された配信元は、ユーザーの認証にシステムによって使用されるドメインです。この場合、Direct Line はドメインを使用してトークンを生成します。
- 構成 UI ページの一部として信頼できるオリジンを構成する場合、これらの設定は常にトークン生成の唯一のセットとして使用されます。トークンの生成や会話の開始時に、追加の信頼できる配信元を送信する場合 (または信頼できるオリジンを none に設定する) と、無視されます (リストへの追加や相互検証は行われません)。
- 拡張認証を有効にしなかった場合は、API 呼び出しの一部として送信した配信元 URL が使用されます。
信頼される側のドメイン URL を追加したら、[適用] を選択します。

Direct Line のサンプルボット

.NET の例は、Direct Line Bot サンプルからダウンロードできます。

サンプルには、以下の 2 つのプロジェクトが含まれています。

DirectLineBot。 Direct Line チャネル経由で接続するボットが作成されます。
DirectLineClient。これは、Direct Line チャネル経由で前のボットと通信するコンソールアプリケーションです。

Direct Line API

Direct Line API の資格情報は、Azure Bot の登録から取得する必要があります。これにより、呼び出し元は生成されたボットにのみ接続できるようになります。ボットプロジェクトで、これらの値で appsettings.json ファイルを更新します。
```
{
"MicrosoftAppId": "",
"MicrosoftAppPassword": ""
}
```
Azure portal で、チャネルの一覧で Direct Line を有効にし、Direct Line シークレットを構成します。バージョン 3.0 のチェックボックスがチェックされていることを確認します。コンソールクライアントプロジェクトで、Direct Line シークレットキーとボットハンドル (ボット ID) で App.config ファイルを更新します。
```
<appSettings>
    <add key="DirectLineSecret" value="YourBotDirectLineSecret" />
    <add key="BotId" value="YourBotHandle" />
</appSettings>
```

ユーザーメッセージは、以前に生成された Direct Line Client Conversations.PostActivityAsync メソッドを生成された ConversationId を使用してボットに送信されます。

while (true)
{
    string input = Console.ReadLine().Trim();

    if (input.ToLower() == "exit")
    {
        break;
    }
    else
    {
        if (input.Length > 0)
        {
            Activity userMessage = new Activity
            {
                From = new ChannelAccount(fromUser),
                Text = input,
                Type = ActivityTypes.Message
            };

            await client.Conversations.PostActivityAsync(conversation.ConversationId, userMessage);
        }
    }
}