为 Microsoft Teams 创建自动程序Create a bot for Microsoft Teams

需要完成以下步骤才能创建对话自动程序:You'll need to complete the following steps to create a conversational bot:

  1. 准备开发环境。Prepare your development environment.
  2. 创建 Web 服务。Create your web service.
  3. 使用 Microsoft Bot Framework 将你的 Web 服务注册为自动程序。Register your web service as a bot with Microsoft Bot Framework.
  4. 创建应用程序清单和应用程序包。Create your app manifest and your app package.
  5. 将程序包上传到 Microsoft Teams。Upload your package to Microsoft Teams.

可使用 Bot Framework 按照任何顺序创建 Web 服务、注册 Web 服务和创建应用程序包:但是,由于这三个部分交织在一起,因此无论按什么顺序执行操作,都需要返回以更新其他部分。Creating your web service, registering your web service, and creating your app package, with the Bot Framework can be done in any order; however, because the three pieces are so intertwined, no matter in which order you do them, you'll need to return to update the others. 注册需要来自部署的 Web 服务的消息传递终结点,并且 Web 服务需要从注册中创建的 ID 和密码。Your registration needs the messaging endpoint from your deployed web service and your web service needs the ID and password created from your registration. 应用程序清单还需要注册 ID 才能将 Teams 连接到 Web 服务。Your app manifest also needs the registration ID to connect Teams to your web service.

构建自动程序时,你将定期在更改应用程序清单与将代码部署到 Web 服务之间切换。As you're building your bot, you'll regularly move between changing your app manifest and deploying code to your web service. 使用应用程序清单时,请记住,你可以手动操作 JSON 文件,也可以通过 App Studio 进行更改。When working with the app manifest, keep in mind you can either manually manipulate the JSON file, or make changes through App Studio. 无论采用哪种方法,当你对清单进行更改时,都需要在 Teams 中重新部署(上传)你的应用;但是,在将更改部署到 Web 服务时无需这样做。Either way, you'll need to re-deploy (upload) your app in Teams when you make a change to the manifest; however, there's no need to do so when you deploy changes to your web service.

有关 Bot Framework 的其他信息,请参阅 Bot Framework 文档See the Bot Framework Documentation for additional information on the Bot Framework.

准备开发环境Prepare your development environment

您需要做的第一件事是准备开发环境。The first thing you'll need to do is prepare your development environment. 您需要确保为您要在其中构建您的应用程序的 Office 365 组织启用自定义应用程序上载。You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. 如果需要专用开发租户,可以注册Office 365 开发人员计划If you need a dedicated development tenant, you can sign up for the Office 365 developer program. 有关其他信息,请参阅设置您的开发环境For additional information see Setup your development environment.

创建 Web 服务Create your web service

自动程序的核心是 Web 服务。The heart of your bot is your web service. 它将定义用于接收所有请求的路由,通常为 /api/messagesIt will define a single route, typically /api/messages, on which to receive all requests. 若要开始,可选择以下选项之一:To get started, you have a few options to choose from:

  • 从采用 C#/dotnetJavaScript 编写的 Teams 对话自动程序示例开始。Start with the Teams conversation bot sample in either C#/dotnet or JavaScript.
  • 如果你使用的是 JavaScript,请使用适用于 Microsoft Teams 的 Yeoman 生成器来搭建 Teams 应用,包括你的 Web 服务。If you're using JavaScript, use the Yeoman Generator for Microsoft Teams to scaffold your Teams app, including your web service. 当构建包含多个对话自动程序的 Teams 应用时,它尤其有用。This is particularly helpful when building a Teams app that contains more than just a conversational bot.
  • 从头开始创建 Web 服务。Create your web service from scratch. 可选择添加面向你的语言的 Bot Framework SDK,也可以直接使用 JSON 有效负载。You can choose to add the Bot Framework SDK for your language, or you can work directly with the JSON payloads.

使用 Bot Framework 注册你的 Web 服务Register your web service with the Bot Framework

重要

注册 Web 服务时,请确保将显示名称设置为与应用程序清单中的简短名称相同的名称。When registering your web service, be sure to set the Display name to the same name you used for your Short name in your app manifest. 通过直接上传或利用组织的应用程序目录分发应用程序时,由自动程序发送到对话的消息将使用注册的显示名称,而不是应用程序的简短名称When your app is distributed by either direct uploading or through an organization's app catalog, messages sent to a conversation by your bot will use the registration's Display name rather than the app's Short name.

通过使用 Bot Framework 来注册 Web 服务,可在 Teams 客户端与 Web 服务之间建立安全的通信通道。Registering your web service with the Bot Framework provides a secure communication channel between the Teams client and your web service. Teams 客户端与 Web 服务永远不会直接通信。The Teams client and your web service never communicate directly. 相反,消息通过 Bot Framework Service 进行路由(Microsoft Teams 使用此服务的单独实例,它符合 Office 365 标准)。Instead, messages are routed through the Bot Framework Service (Microsoft Teams uses a separate instance of this service that is compliant with Office 365 standards).

使用 Bot Framework 注册 Web 服务时,有两个选项可供选择。You have two options when registering your web service with the Bot Framework. 可以使用 App Studio旧门户来注册你的自动程序,而无需使用 Azure 订阅。You can use either App Studio or the legacy portal to register your bot without using an Azure subscription. 或者,如果你已拥有 Azure 订阅(或者不介意创建一个),则可以使用 Azure 门户来注册 Web 服务。Or, if you already have an Azure subscription (or don't mind creating one), you can use the Azure portal to register your web service.

无 Azure 订阅Without an Azure subscription

如果你不想在 Azure 中创建自动程序注册,则必须使用此链接 - https://dev.botframework.com/bots/new 或 App Studio。If you do not wish to create your bot registration in Azure, you must use either this link - https://dev.botframework.com/bots/new, or App Studio. 如果单击 Bot Framework 门户中的“创建自动程序”按钮,将在 Microsoft Azure 中创建自动程序注册,并且需要提供 Azure 订阅。If you click on the Create a bot button in the Bot Framework portal, you will create your bot registration in Microsoft Azure, and will need to provide an Azure subscription. 若要在创建后管理注册或将其迁移到 Azure 订阅,请转到:https://dev.botframework.com/bots。To manage your registration or migrate it to an Azure subscription after creation go to: https://dev.botframework.com/bots.

当你编辑未在 Azure 中注册的现有 Bot Framework 注册的属性时,你将看到“迁移状态”列和蓝色“迁移”按钮,该按钮会将你带到 Microsoft Azure 门户。When you edit the properties of an existing Bot Framework registration not registered in Azure, you'll see A "Migration status" column and a blue "Migrate" button that will take you to the Microsoft Azure portal. 除非你希望这样做,否则不要选择“迁移”按钮。Don't select the "Migrate" button unless that's what you want to do. 相反,请选择自动程序的名称,然后可以编辑其属性:Instead, select the name of the bot and you can edit its properties:

编辑自动程序属性

必须在 Azure 中注册自动程序(通过在 Azure 门户中创建或通过迁移)的应用场景:Scenarios when you must have your bot registration in Azure (either by creating it in the Azure portal or via migration):

  • 你希望使用 Bot Framework 的 OAuthPrompt 进行身份验证。You want to use the Bot Framework's OAuthPrompt for authentication.
  • 你希望启用其他频道,例如网上聊天、Direct Line 或 Skype。You want to enable additional channels like Web Chat, Direct Line, or Skype.

使用 App StudioUsing App Studio

App Studio 是一种 Teams 应用程序,可帮助你构建 Teams 应用,包括将 Web 服务注册为自动程序、创建应用清单和应用包,以及更新设置和配置。App Studio is a Teams application that helps you build Teams apps, including registering your web service as a bot, creating an app manifest and your app package, and updating settings and configurations. 它还包含 React 控件库和卡的可配置示例。It also contains a React control library and configurable samples for cards. 请参阅开始使用 Teams App StudioSee Getting started with Teams App Studio.

请记住,如果使用 App Studio 注册你的 Web 服务,则需要转到 https://dev.botframework.com/bots 以管理你的注册。Remember, if you use App Studio to register your web service you'll need to go to https://dev.botframework.com/bots to manage your registration.

在旧门户中In the legacy portal

使用此链接创建自动程序注册:https://dev.botframework.com/bots/new。Create your bot registration using this link: https://dev.botframework.com/bots/new. 创建自动程序后,请确保从特色频道列表中将 Microsoft Teams 添加为频道。Be sure to add Microsoft Teams as a channel from the featured channels list after creating your bot. 如果你已经创建应用程序包/清单,请随意重复使用你生成的任何 Microsoft 应用 ID。Feel free to re-use any Microsoft App ID you generated if you've already created your app package/manifest.

Bot Framework 注册页面

拥有 Azure 订阅With an Azure subscription

你还可以通过在 Azure 门户中创建“自动程序频道注册”资源来注册 Web 服务。You can also register your web service by creating a Bot Channels Registration resource in the Azure portal.

  1. azure 门户中的 "azure 服务" 下,选择 "创建资源"。In the Azure portal, under Azure services, select Create a resource.

  2. 在 "搜索" 框中,输入 "bot"。In the search box enter "bot". 在下拉列表中,选择 " Bot 通道注册"。And in the drop-down list, select Bot Channels Registration.

  3. 选择 "创建" 按钮。Select the Create button.

  4. 机器人频道注册刀片中,提供有关你的 bot 的请求信息。In the Bot Channel Registration blade, provide the requested information about your bot.

  5. 将 "消息终结点保留为空" 框现在,您将在部署 bot 后输入所需的 URL。Leave the Messaging endpoint box empty for now, you will enter the required URL after deploying the bot. 下图显示了注册设置的示例:The following picture shows an example of the registration settings:

    机器人应用程序通道注册

  6. 单击 " Microsoft 应用程序 ID 和密码",然后创建 "新建"。Click Microsoft App ID and password and then Create New.

  7. 单击 "应用注册门户" 链接中的 "创建应用程序 ID "。Click Create App ID in the App Registration Portal link.

  8. 在显示的 "应用注册" 窗口中,单击左上角的 "新建注册" 选项卡。In the displayed App registration window, click the New registration tab in the upper left.

  9. 输入要注册的 bot 应用程序的名称,我们使用BotTeamsAuth (您需要选择自己的唯一名称)。Enter the name of the bot application you are registering, we used BotTeamsAuth (you need to select your own unique name).

  10. 对于受支持的帐户类型,请选择 "任何组织目录(任何 Azure AD Directory-多租户)" 和 "个人 Microsoft 帐户" (例如 Skype、Xbox)中的 "帐户"For the Supported account types select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).

  11. 单击 "注册" 按钮。Click the Register button. 完成后,Azure 将显示应用程序的 "概述" 页。Once completed, Azure displays the Overview page for the application.

  12. 应用程序(客户端) ID值复制并保存到文件中。Copy and save to a file the Application (client) ID value.

  13. 在左面板中,单击 "证书和密码"。In the left panel, click Certificate and secrets.

    1. 在 "客户端密码" 下,单击 "新建客户端密码"。Under Client secrets, click New client secret.
    2. 添加描述以标识来自其他人的此机密,您可能需要为此应用程序创建。Add a description to identify this secret from others you might need to create for this app.
    3. 过期时间设置为您所做的选择。Set Expires to your selection.
    4. 单击“添加”。Click Add.
    5. 复制客户端密码并将其保存到文件中。Copy the client secret and save it to a file.
  14. 返回到 " Bot 通道注册" 窗口,并分别复制 " Microsoft 应用 id " 和 "密码" 框中的应用程序 id客户端密码Go back to the Bot Channel Registration window and copy the App ID and the Client secret in the Microsoft App ID and Password boxes, respectively.

  15. 单击“确定”****。Click OK.

  16. 最后,单击 "创建"。Finally, click Create.

在 Azure 创建注册资源之后,它将包含在资源组列表中。After Azure has created the registration resource it will be included in the resource group list.

机器人应用程序通道注册组

一旦创建了你的 bot 通道注册,你将需要启用团队频道。Once your bot channels registration is created, you'll need to enable the Teams channel.

  1. azure 门户中,在 "azure 服务" 下,选择刚刚创建的Bot 频道注册In the Azure portal, under Azure services, select the Bot Channel Registration you just created.
  2. 在左面板中,单击 "频道"。In the left panel, click Channels.
  3. 单击 "Microsoft 团队" 图标,然后选择 "保存"。Click the Microsoft Teams icon, then choose Save.

Bot Framework 门户已针对在 Microsoft Azure 中注册自动程序进行了优化。The Bot Framework portal is optimized for registering bots in Microsoft Azure. 以下是几个注意事项:Here are some things to know:

  • 在 Azure 中注册的自动程序的 Microsoft Teams 频道是免费的。The Microsoft Teams channel for bots registered on Azure is free. 通过 Teams 渠道发送的消息将不会计入自动程序使用的消息中。Messages sent over the Teams channel will NOT count towards the consumed messages for the bot.
  • 如果你使用 Microsoft Azure 注册自动程序,则无需在 Microsoft Azure 上托管自动程序代码。If you register your bot using Microsoft Azure, your bot code doesn't need to be hosted on Microsoft Azure.
  • 如果你使用 Microsoft Azure 门户注册自动程序,则必须拥有 Microsoft Azure 帐户。If you do register a bot using Microsoft Azure portal, you must have a Microsoft Azure account. 你可以免费创建一个You can create one for free. 若要在创建 Azure 帐户时验证你的身份,必须提供信用卡,但不会收费;在 Microsoft Teams 中创建和使用自动程序始终是免费的。To verify your identity when you create an Azure account, you must provide a credit card, but it won't be charged; it's always free to create and use bots with Microsoft Teams.

创建应用程序清单和程序包Create your app manifest and package

应用程序清单定义了应用程序的元数据、应用程序正在使用的扩展点以及指向这些扩展点连接到的 Web 服务的指针。Your app manifest defines the metadata for your app, the extension points your app is using, and pointers to the web services those extension points connect to. 你可以使用 App Studio 帮助创建应用程序清单,也可以手动创建。You can either use App Studio to help you create your app manifest, or create it manually.

使用 App Studio 添加Add using App Studio

  1. 在 Teams 客户端中,从左侧导航栏上的“”溢出菜单中打开 App Studio。In the Teams client, open App Studio from the ... overflow menu on the left navigation rail. 如果尚未安装 App Studio,则可以通过搜索它来执行此操作。If App Studio isn't already installed, you can do so by searching for it.
  2. 在“清单编辑器”选项卡上,选择“创建新应用”(或者,如果要将自动程序添加到现有应用中,则可以导入应用程序包)On the Manifest editor tab select Create a new app (or if you're adding a bot to an existing app, you can import your app package)
  3. 添加应用详细信息(有关每个字段的完整说明,请参阅清单架构定义)。Add your app details (see manifest schema definition for full descriptions of each field).
  4. 在“自动程序”选项卡上,选择“设置”按钮。On the Bots tab select the Setup button.
  5. 你可以创建新的 Web 服务注册(新自动程序),或者如果已经注册了一个,请选择现有自动程序You can either create a new web service registration (New bot), or if you've already registered one, select Existing bot.
  6. 选择自动程序所需的功能和作用域。Select the capabilities and scopes your bot will need.
  7. 如有必要,请更新自动程序终结点地址以指向你的自动程序。If necessary, update your bot endpoint address to point to your bot. 它应该类似于 https://someplace.com/api/messagesIt should look something like https://someplace.com/api/messages.
  8. (可选)添加自动程序命令Optionally, add bot commands.
  9. (可选)你可以从“测试和分发”选项卡下载完整的应用程序包。Optionally, you can download your completed app package from the Test and distribute tab.

手动创建Create it manually

与消息传递扩展和选项卡一样,你可以更新应用程序清单以定义你的自动程序。As with messaging extensions and tabs, you update the app-manifest to define your bot. 使用 bots 属性在你的应用程序清单中添加新的顶级 JSON 结构。Add new top-level JSON structure in your app manifest with the bots property.

姓名Name 类型Type 最大大小Maximum size 必需Required 说明Description
botId 字符串String 64 个字符64 characters 使用 Bot Framework 注册的自动程序的唯一 Microsoft 应用 ID。The unique Microsoft app ID for the bot as registered with the Bot Framework. 它可能与整个应用 ID 相同。This may well be the same as the overall app ID.
needsChannelSelector 布尔值Boolean 描述自动程序是否利用用户提示将自动程序添加到特定频道。Describes whether or not the bot utilizes a user hint to add the bot to a specific channel. 默认值:falseDefault: false.
isNotificationOnly 布尔值Boolean 指示自动程序是否为单向、仅通知的自动程序,而不是对话自动程序。Indicates whether a bot is a one-way, notification-only bot, as opposed to a conversational bot. 默认值:falseDefault: false.
supportsFiles 布尔值Boolean 指示自动程序是否支持在个人聊天中上传/下载文件。Indicates whether the bot supports the ability to upload/download files in personal chat. 默认值:falseDefault: false.
scopes 枚举数组Array of enum 33 指定自动程序是在 team 内的频道上下文中提供体验、在群组聊天 (groupchat) 中提供体验,还是仅在单个用户 (personal) 范围内提供体验。Specifies whether the bot offers an experience in the context of a channel in a team, in a group chat (groupchat), or an experience scoped to an individual user alone (personal). 这些选项不具排他性。These options are non-exclusive.

(可选)你可以定义由自动程序向用户推荐的一个或多个命令列表。Optionally, you can define one or more lists of commands that your bot can recommend to users. 对象是一个数组(最多 2 个元素),所有元素的类型均为 objectThe object is an array (maximum of 2 elements) with all elements of type object. 你必须为自动程序支持的每个作用域定义一个单独的命令列表。You must define a separate command list for each scope that your bot supports. 有关详细信息,请参阅自动程序菜单See Bot menus, for more information.

姓名Name 类型Type 最大大小Maximum size 必需Required 说明Description
items.scopes 枚举数组array of enum 33 指定命令列表有效的作用域。Specifies the scope for which the command list is valid. 选项包括 teampersonalgroupchatOptions are team, personal, and groupchat.
items.commands 对象数组array of objects 1010 自动程序支持的命令数组:An array of commands the bot supports:
title:自动程序命令名称(字符串,32)title: the bot command name (string, 32)
description:命令语法及其参数的简单描述或示例(字符串,128)description: a simple description or example of the command syntax and its argument (string, 128)

简单清单示例Simple manifest example

下面的示例是一个简单的自动程序对象,其中定义了两个命令列表。The example below is a simple bot object, with two command lists defined. 这不是整个应用程序清单文件,只是特定于消息传递扩展的部分。This is not the entire app manifest file, just the part specific to messaging extensions.

...
  "bots": [
    {
      "botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%",
      "needsChannelSelector": false,
      "isNotificationOnly": false,
      "scopes": [ "team", "personal", "groupchat" ],
      "supportsFiles": true,
      "commandLists": [
        {
          "scopes": [ "team", "groupchat" ],
          "commands": [
            {
              "title": "Command 1",
              "description": "Description of Command 1"
            },
            {
              "title": "Command N",
              "description": "Description of Command N"
            }
          ]
        },
        {
          "scopes": [ "personal", "groupchat" ],
          "commands": [
            {
              "title": "Personal command 1",
              "description": "Description of Personal command 1"
            },
            {
              "title": "Personal command N",
              "description": "Description of Personal command N"
            }
          ]
        }
      ]
    }
  ],
...

手动创建应用程序包Create your app package manually

若要创建应用程序包,你需要将应用程序清单和(可选)应用程序图标添加到 .zip 存档文件中。To create an app package, you need to add your app manifest and (optionally) your app icons to a .zip archive file. 有关完整详细信息,请参阅创建应用程序包See Create your app package for complete details. 请确保 .zip 存档文件仅包含必需的文件,并且内部没有其他文件夹结构。Make sure your .zip archive contains only the necessary files, and has no additional folder structure inside of it.

将你的程序包上传到 Microsoft TeamsUpload your package to Microsoft Teams

备注

要成功上传你的自动程序,你的租户管理员必须首先允许在 Teams 中上传第三方或自定义应用。To successfully upload your bot, your tenant admin must first allow uploading third-party or custom apps in Teams.

如果你一直在使用 App Studio,则可以从清单编辑器的“测试和分发”选项卡中安装应用。If you've been using App Studio, you can install your app from the Test and distribute tab of the Manifest editor. 或者,你也可以通过以下方法安装应用程序包,即单击左侧导航栏中的 ... 溢出菜单,单击“更多应用”,然后单击“上载自定义应用”链接。Alternatively, you can install your app package by clicking the ... overflow menu from the left navigation rail, clicking More apps, then the Upload a custom app link. 你还可以将应用程序清单或应用程序包导入到 App Studio 中,以在上传之前进行其他更新。You can also import an app manifest or app package into App Studio to make additional updates before uploading.

Teams 会议的自动程序Bots in Teams meetings

Teams 支持在会议期间进行自动程序调用。Teams supports bot invocation during meetings. 当你的自动程序收到调用消息时,它可以识别来自 userIdtenantId 的用户和租户。When your bot receives the invoke message, it can identify the user and tenant from userId and tenantId. 可在 channelData 对象中找到 meetingIdThe meetingId can be found as part of the channelData object. 你的自动程序可以对 GetParticipant API 请求使用 userIdmeetingId 来检索用户角色。Your bot can use the userId and meetingId for the GetParticipant API request to retrieve user roles.

后续步骤Next steps