快速入門：將 Bot 新增至聊天應用程式

發行項
04/29/2024

了解如何使用 Azure Bot Service 中提供的 Azure 通訊服務聊天傳訊通道，在聊天應用程式中建置交談式 AI 體驗。在本快速入門中，您會使用 BotFramework SDK 建立 Bot。然後，您會使用通訊服務聊天 SDK 將 Bot 整合到您建立的聊天應用程式中。

在此快速入門中，您可了解如何：

在 Azure 中建立和部署 Bot
取得通訊服務資源
為 Bot 啟用通訊服務聊天通道
建立聊天應用程式並將 Bot 新增為參與者
探索適用於 Bot 的更多功能

必要條件

一個 Azure 帳戶和作用中的訂用帳戶。免費建立帳戶。
Visual Studio 2019 或更新版本。
最新版本的 .NET Core。在本快速入門中，我們會使用 .NET Core 3.1 (英文)。請務必安裝與您 Visual Studio 執行個體對應的版本 (32 位元或 64 位元)。
Bot framework SDK (英文)

在 Azure 中建立和部署 Bot

若要使用 Azure 通訊服務聊天作為 Azure Bot Service 中的通道，請先部署 Bot。若要部署 Bot，請完成下列步驟：

建立 Azure Bot Service 資源
取得 Bot 的應用程式識別碼和密碼
建立 Web 應用程式以保存 Bot 邏輯
建立 Bot 的傳訊端點

建立 Azure Bot Service 資源

首先，請使用 Azure 入口網站建立 Azure Bot Service 資源 (部分機器翻譯)。通訊服務聊天通道支援單一租用戶 Bot、受控識別 Bot 和多租用戶 Bot。基於本快速入門的目的，我們將使用「多租用戶」Bot。

若要設定單一租用戶或受控識別 Bot，請檢閱 Bot 身分識別資訊 (部分機器翻譯)。

針對受控識別 Bot，您可能必須更新 Bot 服務識別 (部分機器翻譯)。

取得 Bot 的應用程式識別碼和應用程式密碼

接下來，請取得部署 Bot 時指派給 Bot 的 Microsoft 應用程式識別碼和密碼 (部分機器翻譯)。您稍後會使用這些值進行設定。

建立 Web 應用程式以保存 Bot 邏輯

若要為您的 Bot 建立 Web 應用程式，您可以針對您的案例修改 Bot Builder 範例 (英文)，或使用 Bot Builder SDK (英文) 來建立 Web 應用程式。其中一個最簡單的範例是 Echo Bot (英文)。

Azure Bot Service 通常會預期 Bot 應用程式 Web 應用程式控制器會以 /api/messages 的形式公開端點。該端點會處理傳送至 Bot 的所有訊息。

若要建立 Bot 應用程式，請使用 Azure CLI 建立 Azure App Service 資源 (部分機器翻譯)，或在 Azure 入口網站中建立應用程式。

若要使用 Azure 入口網站建立 Bot Web 應用程式：

在入口網站中，選取 [建立資源]。在搜尋方塊中，輸入 Web 應用程式。選取 [Web 應用程式] 圖格。
在 [建立 Web 應用程式] 中，選取或輸入應用程式的詳細資料，包括您要將應用程式部署到哪一個區域。
選取 [檢閱 + 建立] 來驗證部署，並檢閱部署詳細資料。然後，選取 [建立]。
建立 Web 應用程式資源時，請複製資源詳細資料中顯示的主機名稱 URL。該 URL 是您為 Web 應用程式建立之端點的一部分。

建立 Bot 的傳訊端點

接下來，在 Bot 資源中，建立 Web 應用程式傳訊端點：

在 Azure 入口網站中，移至您的 Azure Bot 資源。在資源功能表中，選取 [設定]。
在 [設定] 中，針對 [傳訊端點]，請貼上您在上一節中複製之 Web 應用程式的主機名稱 URL。將 /api/messages 附加至該 URL。
選取 [儲存]。

部署 Web 應用程式

建立 Bot 的最後一個步驟是部署 Web 應用程式。針對本快速入門，請使用 Echo Bot 範例。 Echo Bot 功能僅限於回應使用者輸入。以下是在 Azure 中將其部署到 Web 應用程式的方式：

使用 Git 複製此 GitHub 存放庫：

git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

在 Visual Studio 中，開啟 Echo Bot 專案 (英文)。
在 Visual Studio 專案中，開啟 Appsettings.json 檔案。貼上您稍早複製的 Microsoft 應用程式識別碼和應用程式密碼：
```
   {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }
```
接下來，請使用 Visual Studio for C# Bot 來部署 Bot。

您也可以使用命令提示字元視窗來部署 Azure Bot (部分機器翻譯)。
在 Visual Studio 中，於 [方案總管] 中以滑鼠右鍵按一下 [EchoBot] 專案，然後選取 [發佈]：
選取 [新增] 以建立新的發行設定檔。針對 [目標]，請選取 [Azure]：

針對特定目標，請選取 [Azure App Service]：
在部署設定中，請選取您登入 Azure 帳戶後所顯示之結果中的 Web 應用程式。若要完成設定檔，請選取 [完成]，然後選取 [發佈] 以啟動部署。

取得通訊服務資源

在建立並部署 Bot 之後，請建立用來設定通訊服務通道的通訊服務資源：

完成建立通訊服務資源 (部分機器翻譯) 的步驟。
建立通訊服務使用者，並核發使用者存取權杖 (部分機器翻譯)。請務必將範圍設定為 [聊天]。 複製權杖字串和使用者識別碼字串。

啟用通訊服務聊天通道

當您有通訊服務資源時，您可以在 Bot 資源中設定通訊服務通道。在此流程中，會為 Bot 產生使用者識別碼。

在 Azure 入口網站中，移至您的 Azure Bot 資源。在資源功能表中，選取 [通道]。在可用通道的清單中，選取 [Azure 通訊服務 - 聊天]。
選取 [連線] 以查看您訂用帳戶中可用的通訊服務資源清單。
在 [新增連線] 窗格中，選取 [通訊服務聊天] 資源，然後選取 [套用]。
驗證資源詳細資料之後，會在 [Bot Azure 通訊服務識別碼] 資料行中顯示 Bot 識別碼。您可以透過通訊服務聊天 AddParticipant API，在聊天對話中使用 Bot 識別碼來代表 Bot。將 Bot 新增至聊天作為參與者之後，Bot 會開始接收聊天相關活動，並且可以在聊天對話中回應。

建立聊天應用程式並將 Bot 新增為參與者

在您擁有 Bot 的通訊服務識別碼之後，您現在可以建立聊天對話並將 Bot 作為參與者。

建立新的 C# 應用程式

執行下列命令以建立 C# 應用程式：
```
dotnet new console -o ChatQuickstart
```
將您的目錄變更為新的應用程式資料夾，然後使用 dotnet build 命令來編譯您的應用程式：
```
cd ChatQuickstart
dotnet build
```

Install the package

安裝適用於 .NET 的通訊服務聊天 SDK：

dotnet add package Azure.Communication.Chat

建立聊天用戶端

若要建立聊天用戶端，請使用通訊服務端點，以及您稍早產生的使用者存取權杖。請使用身分識別 SDK 中的 CommunicationIdentityClient 類別來建立使用者，並核發要傳遞至聊天用戶端的權杖。您可以使用下列指示 (部分機器翻譯) 在入口網站中產生存取權杖。

複製下列程式碼並貼到 Program.cs 來源檔案中：

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

開始與 Bot 的聊天對話

在 chatClient 上使用 createChatThread 方法來建立聊天對話。將識別碼取代為 Bot 的通訊服務識別碼。

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

取得聊天對話用戶端

GetChatThreadClient 方法會針對已經存在的對話傳回對話用戶端：

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

將訊息傳送至聊天對話

使用 SendMessage 以將訊息傳送至對話：

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

從聊天對話接收聊天訊息

您可以透過依固定間隔對聊天對話用戶端上的 GetMessages 方法進行輪詢來取得聊天訊息：

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

檢查訊息清單，尋找 Bot 對 "Hello World" 的 Echo 回覆。

您可以使用 JavaScript 或 Azure 行動 SDK 來訂閱傳入訊息通知：

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

清理聊天對話

在您使用完聊天對話之後，請刪除對話：

chatClient.DeleteChatThread(threadId);

部署 C# 聊天應用程式

部署聊天應用程式：

在 Visual Studio 中，開啟聊天專案。
以滑鼠右鍵按一下 [ChatQuickstart] 專案，然後選取 [發佈]：
發佈解決方案之後，請加以執行並在命令提示字元上檢查 Echobot 是否會對使用者訊息進行 Echo 回覆。在擁有解決方案之後，您現在便可以繼續針對您需要解決之商務案例所需的各種活動進行實驗。

可以使用 Bot 做到的更多事情

Bot 不僅只是能在通訊服務聊天通道中接收來自使用者的純文字訊息而已。 Bot 可以從使用者接收的一些活動包括：

對話更新
訊息更新
訊息刪除
輸入指標
事件活動
各種附件，包括調適型卡片
Bot 通道資料

下列各節會示範一些範例來說明這些功能。

在將新使用者新增至對話時傳送歡迎訊息

目前的 Echo Bot 邏輯會接受來自使用者的輸入，並以 Echo 回覆的方式傳回訊息。如果您想要新增更多邏輯，例如回應由參與者新增的通訊服務事件，請複製下列程式碼，並將其貼到 EchoBot.cs (英文) 來源檔案中：

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

傳送調適型卡片

注意

只有在所有聊天參與者都是 Azure 通訊服務使用者的 Azure 通訊服務使用案例內才支援調適型卡片，且不支援 Teams 互通性使用案例。

您可以將調適型卡片傳送至聊天對話，以提高參與度和效率。調適型卡片也協助您以各種方式與使用者通訊。您可以將調適型卡片新增為 Bot 活動附件，以從 Bot 傳送調適型卡片。

以下是如何傳送調適型卡片的範例：

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

在範例和範本 (英文) 取得調適型卡片的範例承載。

針對聊天使用者，通訊服務聊天通道會將欄位新增至訊息中繼資料，其能指出該訊息具有附件。在中繼資料中，microsoft.azure.communication.chat.bot.contenttype 屬性會設定為 azurebotservice.adaptivecard。

以下是附加調適型卡片的聊天訊息範例：

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

將訊息從使用者傳送至 Bot

您可以使用和將簡訊傳送給另一個使用者的相同方式，將基本簡訊從使用者傳送至 Bot。

不過，當您將具有附件的訊息從使用者傳送至 Bot 時，請將此旗標新增至通訊服務聊天中繼資料：

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

若要將事件活動從使用者傳送至 Bot，請將此旗標新增至通訊服務聊天中繼資料：

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

下列各節示範適用於從使用者到 Bot 之聊天訊息的範例格式。

簡單的簡訊

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

具有附件的訊息

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

具有事件活動的訊息

事件承載包括訊息內容中的所有 JSON 欄位，除了 Name 以外。 Name 欄位包含事件的名稱。

在下列範例中，會將具有 "{field1":"value1", "field2": { "nestedField":"nestedValue" }} 承載的 endOfConversation 事件名稱傳送至 Bot：

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

只有在從使用者傳送至 Bot 的訊息中，才會需要 microsoft.azure.communication.chat.bot.contenttype 中繼資料欄位。

支援的 Bot 活動欄位

下列各節說明針對 Bot 對使用者流程和使用者對 Bot 流程所支援的 Bot 活動欄位。

Bot 對使用者流程

Bot 對使用者流程支援下列 Bot 活動欄位。

活動

訊息
輸入

訊息活動欄位

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name (轉換為通訊服務 SenderDisplayName。)
ChannelData (轉換為通訊服務 Chat Metadata。如果有任何 ChannelData 對應值是物件，則會以 JSON 格式序列化，並以字串形式傳送。)

使用者對 Bot 流程

使用者對 Bot 流程支援這些 Bot 活動欄位。

活動和欄位

訊息
- Id (通訊服務聊天訊息識別碼)
- TimeStamp
- Text
- Attachments
對話更新
- MembersAdded
- MembersRemoved
- TopicName
訊息更新
- Id (更新的通訊服務聊天訊息識別碼)
- Text
- Attachments
訊息刪除
- Id (刪除的通訊服務聊天訊息識別碼)
Event
- Name
- Value
輸入

其他通用欄位

Recipient.Id 和 Recipient.Name (通訊服務聊天使用者識別碼和顯示名稱)
From.Id 和 From.Name (通訊服務聊天使用者識別碼和顯示名稱)
Conversation.Id (通訊服務聊天對話識別碼)
ChannelId (通訊服務聊天 (若為空白))
ChannelData (通訊服務聊天訊息中繼資料)

Bot 遞交模式

有時候，Bot 沒辦法了解問題，或是無法回答問題。客戶可能會在聊天中要求連線到人類代理人。在這些案例中，聊天對話必須從 Bot 遞交給人類代理人。您可以將應用程式設計為將交談從 Bot 轉換至人類 (部分機器翻譯)。

處理 Bot 對 Bot 通訊

在某些使用案例中，必須將兩個 Bot 新增至相同的聊天對話，以提供不同的服務。在此案例中，建議您確保 Bot 不會對另一個 Bot 的訊息傳送自動化回覆。如果未正確處理，Bot 之間的自動化互動可能會導致訊息的無限迴圈。

您可以在活動的 From.Id 屬性中驗證訊息傳送者的通訊服務使用者身分識別。檢查以查看其是否屬於另一個 Bot。然後，採取必要的動作來防止 Bot 對 Bot 通訊流程。如果這種類型的案例產生高通話量，通訊服務聊天通道便會對要求進行節流，且 Bot 將無法傳送和接收訊息。

深入了解節流限制 (部分機器翻譯)。

疑難排解

以下各節說明對常見案例進行疑難排解的方式。

無法新增聊天通道

在 Microsoft Bot Framework 開發人員入口網站中，移至 [設定]>[Bot 傳訊]，以確認端點已正確設定。

Bot 在回覆訊息時會取得禁止的例外狀況

確認 Bot 的 Microsoft 應用程式識別碼和密碼已正確儲存在您上傳至 Web 應用程式的 Bot 設定檔中。

無法將 Bot 新增為參與者

在傳送要求以將 Bot 新增至聊天對話中時，確認使用的是該 Bot 正確的通訊服務識別碼。

下一步

嘗試透過 BotFramework WebChat UI 元件使用聊天 Bot 示範應用程式 (英文)，以在聊天使用者和 Bot 之間進行一對一聊天。

共用方式為