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

發行項
11/05/2024

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

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

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

必要條件

一個 Azure 帳戶和作用中的訂用帳戶。免費建立帳戶。
Visual Studio 2019 或更新版本。
最新版本的 .NET Core。（https://dotnet.microsoft.com/download/dotnet/）。
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。

在本快速入門中，我們將使用 multitenant Bot。
若要設定 single-tenant 或 managed identity Bot，請檢閱 Bot 身分識別資訊。
針對 Bot managed identity ，您可能必須更新 Bot 服務身分識別。

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

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

建立 Bot 應用程式並將其發布至 Web 應用程式

若要建立 Bot，您可以執行下列其中一項動作：

修改案例的 Bot Builder 範例、建立 Web 應用程式，然後將 Bot 範例部署至其中。
使用 Bot Builder SDK 建立 Bot，並將 Bot 發佈至 Web 應用程式。

在本快速入門中，我們將使用 Bot Builder 範例中的 Echo Bot 範例。

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

若要建立 Web 應用程式，請使用 Azure CLI 來建立 Azure App 服務資源，或在 Azure 入口網站中建立應用程式。

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

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

建立 Bot 的傳訊端點

Azure Bot Service 通常會預期 Bot 應用程式 Web 應用程式控制器會以 /api/messages 的形式公開端點。該端點會處理傳送至 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 應用程式識別碼和應用程式密碼：
```
   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>",
       "MicrosoftAppTenantId": ""
   }
```
接下來，使用適用於 C# 的 Visual Studio 或 VS Code 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 作為參與者。

遵循「將聊天新增至您的應用程式」快速入門

請遵循將聊天新增至您的應用程式快速入門中的步驟來建立聊天應用程式。

從取得通訊服務資源步驟，>將Resource_Endpoint取代<為通訊服務端點。
使用取得通訊服務資源步驟中的使用者存取令牌取代<Access_Token>。
將 Access_ID> 取代<為啟用通訊服務聊天頻道步驟ACS_ID的 Bot。

在本機執行 C# 聊天應用程式

若要在本機執行聊天應用程式，請使用 dotnet run 命令：

dotnet run

您應該會在控制台中收到來自 Bot 的訊息，指出「Hello World」。

範例輸出：

1730405535010:Hello World

可以使用 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 正確的通訊服務識別碼。

下一步

開始聊天

您可能也會想要：

熟悉聊天概念
了解聊天定價運作方式

共用方式為