azure-bot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Bot Registration & Deployment

Azure Bot注册与部署

Create and manage Azure Bot resources using the Azure CLI (

az bot

). This skill covers the full lifecycle: identity creation, bot registration, channel configuration, and deployment.

使用Azure CLI（

az bot

）创建和管理Azure Bot资源，本技能覆盖完整操作生命周期：身份创建、Bot注册、渠道配置和部署。

Prerequisites

前置条件

Before running any commands, verify the user has:

bash

undefined

运行任何命令前，请确认用户已满足以下要求：

bash

undefined

Check Azure CLI is installed and logged in

检查Azure CLI是否已安装并登录

az account show --query "{subscription:name, tenantId:tenantId}" -o table


If not logged in, run `az login` first.

Required tools:
- Azure CLI 2.39.0+ (`az --version`)
- An active Azure subscription

az account show --query "{subscription:name, tenantId:tenantId}" -o table


如果未登录，请先运行`az login`。

所需工具：
- Azure CLI 2.39.0及以上版本（可通过`az --version`查看）
- 有效的Azure订阅

When to Use This Skill

何时使用该技能

Use when the user asks to:

Create an Azure Bot resource
Register a bot with Azure AI Bot Service
Connect a bot to channels (Teams, Slack, Telegram, Direct Line, etc.)
Deploy a bot to Azure App Service
Manage bot identity (single-tenant, user-assigned managed identity)
Set up a messaging endpoint for an existing bot

当用户需要执行以下操作时可使用：

创建Azure Bot资源
在Azure AI Bot Service中注册Bot
将Bot接入不同渠道（Teams、Slack、Telegram、Direct Line等）
将Bot部署到Azure App Service
管理Bot身份（单租户、用户分配的托管身份）
为现有Bot设置消息端点

Important Notes

注意事项

Multi-tenant bot creation is deprecated after July 31, 2025. Always default to SingleTenant or UserAssignedMSI.
Bot names must be 4-42 characters, alphanumeric + hyphens + underscores only.
The free tier (F0) is suitable for development; use S1 for production.

2025年7月31日之后将不再支持创建多租户Bot，请始终默认选择SingleTenant或UserAssignedMSI。
Bot名称长度需为4-42个字符，仅支持字母、数字、连字符和下划线。
免费层（F0）适合开发环境使用，生产环境请使用S1层。

Step-by-Step: Create an Azure Bot

分步指南：创建Azure Bot

Step 1: Gather Required Information

步骤1：收集所需信息

Ask the user for these values (provide sensible defaults):

Parameter	Description	Default
`BOT_NAME`	Resource name (4-42 chars, alphanumeric/hyphens/underscores)	— (required)
`RESOURCE_GROUP`	Azure resource group	`rg-<BOT_NAME>`
`LOCATION`	Azure region	`eastus`
`APP_TYPE`	Identity type: `SingleTenant` or `UserAssignedMSI`	`SingleTenant`
`DISPLAY_NAME`	Human-readable display name	Same as BOT_NAME
`ENDPOINT`	Messaging endpoint URL (https://...)	Can be set later
`SKU`	Pricing tier: `F0` (free) or `S1` (standard)	`F0`

向用户询问以下参数（可提供合理默认值）：

参数	描述	默认值
`BOT_NAME`	资源名称（4-42个字符，支持字母/数字/连字符/下划线）	— （必填）
`RESOURCE_GROUP`	Azure资源组	`rg-<BOT_NAME>`
`LOCATION`	Azure区域	`eastus`
`APP_TYPE`	身份类型： `SingleTenant` 或 `UserAssignedMSI`	`SingleTenant`
`DISPLAY_NAME`	可读性强的展示名称	与BOT_NAME相同
`ENDPOINT`	消息端点URL（需以https://开头）	可后续设置
`SKU`	定价层： `F0` （免费）或 `S1` （标准）	`F0`

Step 2: Create Resource Group (if needed)

步骤2：创建资源组（如果需要）

bash

az group create \
  --name "${RESOURCE_GROUP}" \
  --location "${LOCATION}"

bash

az group create \
  --name "${RESOURCE_GROUP}" \
  --location "${LOCATION}"

Step 3: Create Identity

步骤3：创建身份

Option A: Single-Tenant App Registration (Recommended)

bash

undefined

选项A：单租户应用注册（推荐）

bash

undefined

Create the app registration

创建应用注册

az ad app create
--display-name "${BOT_NAME}"
--sign-in-audience "AzureADMyOrg"

Note the appId from the output, then generate a password

记录输出中的appId，然后生成密码

az ad app credential reset --id "<appId>"


Record these values:
- `APP_ID` — the `appId` from `az ad app create` output
- `APP_PASSWORD` — the `password` from `az ad app credential reset` output
- `TENANT_ID` — from `az account show --query tenantId -o tsv`

**Option B: User-Assigned Managed Identity**

```bash

az ad app credential reset --id "<appId>"


记录以下值：
- `APP_ID` — `az ad app create`输出中的`appId`
- `APP_PASSWORD` — `az ad app credential reset`输出中的`password`
- `TENANT_ID` — 可通过`az account show --query tenantId -o tsv`获取

**选项B：用户分配的托管身份**

```bash

Create the managed identity

创建托管身份

az identity create
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}-identity"


Record:
- `CLIENT_ID` — the `clientId` from output
- `TENANT_ID` — from `az account show --query tenantId -o tsv`
- `MSI_RESOURCE_ID` — the `id` from output (full ARM resource ID)

az identity create
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}-identity"


记录以下值：
- `CLIENT_ID` — 输出中的`clientId`
- `TENANT_ID` — 可通过`az account show --query tenantId -o tsv`获取
- `MSI_RESOURCE_ID` — 输出中的`id`（完整ARM资源ID）

Step 4: Create the Azure Bot Resource

步骤4：创建Azure Bot资源

For Single-Tenant:

bash

az bot create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --app-type "SingleTenant" \
  --appid "${APP_ID}" \
  --tenant-id "${TENANT_ID}" \
  --display-name "${DISPLAY_NAME}" \
  --endpoint "${ENDPOINT}" \
  --sku "${SKU}"

For User-Assigned Managed Identity:

bash

az bot create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --app-type "UserAssignedMSI" \
  --appid "${CLIENT_ID}" \
  --tenant-id "${TENANT_ID}" \
  --msi-resource-id "${MSI_RESOURCE_ID}" \
  --display-name "${DISPLAY_NAME}" \
  --endpoint "${ENDPOINT}" \
  --sku "${SKU}"

单租户场景：

bash

az bot create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --app-type "SingleTenant" \
  --appid "${APP_ID}" \
  --tenant-id "${TENANT_ID}" \
  --display-name "${DISPLAY_NAME}" \
  --endpoint "${ENDPOINT}" \
  --sku "${SKU}"

用户分配托管身份场景：

bash

az bot create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --app-type "UserAssignedMSI" \
  --appid "${CLIENT_ID}" \
  --tenant-id "${TENANT_ID}" \
  --msi-resource-id "${MSI_RESOURCE_ID}" \
  --display-name "${DISPLAY_NAME}" \
  --endpoint "${ENDPOINT}" \
  --sku "${SKU}"

Step 5: Verify Bot Creation

步骤5：验证Bot创建结果

bash

az bot show \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  -o table

bash

az bot show \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  -o table

Channel Configuration

渠道配置

Microsoft Teams

bash

az bot msteams create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}"

bash

az bot msteams create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}"

Slack

bash

undefined

bash

undefined

Requires: Slack App client ID, client secret, verification token, and landing page URL

需要：Slack App客户端ID、客户端密钥、验证令牌和落地页URL

az bot slack create
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}"
--client-id "<slack-client-id>"
--client-secret "<slack-client-secret>"
--verification-token "<slack-verification-token>"
--landing-page-url "<landing-page-url>"

undefined

undefined

bash

undefined

bash

undefined

Requires: Telegram bot token from @BotFather

需要：从@BotFather获取的Telegram Bot令牌

az bot telegram create
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}"
--access-token "<telegram-bot-token>"

undefined

az bot telegram create
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}"
--access-token "<telegram-bot-token>"

undefined

Direct Line (for web/mobile apps)

Direct Line（适用于Web/移动应用）

bash

az bot directline create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}"

Get the Direct Line secret:

bash

az bot directline show \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --query "properties.properties.sites[0].key" -o tsv

bash

az bot directline create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}"

获取Direct Line密钥：

bash

az bot directline show \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --query "properties.properties.sites[0].key" -o tsv

Facebook Messenger

bash

az bot facebook create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --appid "<facebook-app-id>" \
  --app-secret "<facebook-app-secret>" \
  --page-id "<facebook-page-id>" \
  --access-token "<facebook-page-access-token>"

bash

az bot facebook create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --appid "<facebook-app-id>" \
  --app-secret "<facebook-app-secret>" \
  --page-id "<facebook-page-id>" \
  --access-token "<facebook-page-access-token>"

Email

邮箱

bash

az bot email create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --email-address "<email@outlook.com>" \
  --password "<email-password>"

bash

az bot email create \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --email-address "<email@outlook.com>" \
  --password "<email-password>"

Web Chat (enabled by default)

Web Chat（默认启用）

Web Chat is automatically configured. Get the secret:

bash

az bot webchat show \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --query "properties.properties.sites[0].key" -o tsv

Web Chat会自动配置，获取密钥方式：

bash

az bot webchat show \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --query "properties.properties.sites[0].key" -o tsv

Show Channel Details

查看渠道详情

bash

undefined

bash

undefined

Teams

az bot msteams show --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

Slack

az bot slack show --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

az bot telegram show --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

Direct Line

az bot directline show --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

undefined

az bot directline show --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

undefined

Update Bot Configuration

更新Bot配置

Update Messaging Endpoint

更新消息端点

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --endpoint "https://your-bot.azurewebsites.net/api/messages"

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --endpoint "https://your-bot.azurewebsites.net/api/messages"

Update Display Name and Description

更新展示名称和描述

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --display-name "My Bot Display Name" \
  --description "Bot description here"

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --display-name "My Bot Display Name" \
  --description "Bot description here"

Upgrade SKU

升级SKU

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --sku S1

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --sku S1

Deploy Bot Code to App Service

将Bot代码部署到App Service

Step 1: Create App Service Plan + Web App (if hosting on Azure)

步骤1：创建App Service计划 + Web应用（如果托管在Azure上）

bash

undefined

bash

undefined

Create App Service Plan

创建App Service计划

az appservice plan create
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}-plan"
--sku B1
--is-linux

Create Web App (Python example)

创建Web应用（Python示例）

az webapp create
--resource-group "${RESOURCE_GROUP}"
--plan "${BOT_NAME}-plan"
--name "${BOT_NAME}-app"
--runtime "PYTHON:3.11"

Or for Node.js

Node.js示例

az webapp create
--resource-group "${RESOURCE_GROUP}"
--plan "${BOT_NAME}-plan"
--name "${BOT_NAME}-app"
--runtime "NODE:20-lts"

undefined

az webapp create
--resource-group "${RESOURCE_GROUP}"
--plan "${BOT_NAME}-plan"
--name "${BOT_NAME}-app"
--runtime "NODE:20-lts"

undefined

Step 2: Configure App Settings

步骤2：配置应用设置

For Single-Tenant:

bash

az webapp config appsettings set \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}-app" \
  --settings \
    MicrosoftAppType=SingleTenant \
    MicrosoftAppId="${APP_ID}" \
    MicrosoftAppPassword="${APP_PASSWORD}" \
    MicrosoftAppTenantId="${TENANT_ID}"

For User-Assigned Managed Identity:

bash

az webapp config appsettings set \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}-app" \
  --settings \
    MicrosoftAppType=UserAssignedMSI \
    MicrosoftAppId="${CLIENT_ID}" \
    MicrosoftAppPassword="" \
    MicrosoftAppTenantId="${TENANT_ID}"

单租户场景：

bash

az webapp config appsettings set \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}-app" \
  --settings \
    MicrosoftAppType=SingleTenant \
    MicrosoftAppId="${APP_ID}" \
    MicrosoftAppPassword="${APP_PASSWORD}" \
    MicrosoftAppTenantId="${TENANT_ID}"

用户分配托管身份场景：

bash

az webapp config appsettings set \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}-app" \
  --settings \
    MicrosoftAppType=UserAssignedMSI \
    MicrosoftAppId="${CLIENT_ID}" \
    MicrosoftAppPassword="" \
    MicrosoftAppTenantId="${TENANT_ID}"

Step 3: Prepare & Deploy Code

步骤3：准备并部署代码

bash

undefined

bash

undefined

Prepare deployment files (run from bot project root)

准备部署文件（在Bot项目根目录执行）

az bot prepare-deploy --lang <Csharp|Javascript|Typescript> --code-dir "."

Deploy via zip

打包为zip

zip -r bot.zip . -x ".git" "node_modules/" "pycache/" ".env" az webapp deploy
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}-app"
--src-path bot.zip
--type zip

undefined

zip -r bot.zip . -x ".git" "node_modules/" "pycache/" ".env" az webapp deploy
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}-app"
--src-path bot.zip
--type zip

undefined

Step 4: Update Bot Endpoint

步骤4：更新Bot端点

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --endpoint "https://${BOT_NAME}-app.azurewebsites.net/api/messages"

bash

az bot update \
  --resource-group "${RESOURCE_GROUP}" \
  --name "${BOT_NAME}" \
  --endpoint "https://${BOT_NAME}-app.azurewebsites.net/api/messages"

OAuth Connection Settings

OAuth连接设置

For bots that need OAuth (e.g., accessing Microsoft Graph):

bash

undefined

如果Bot需要OAuth认证（例如访问Microsoft Graph）：

bash

undefined

List available OAuth providers

列出可用的OAuth提供商

az bot authsetting list-providers
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}"

Create an OAuth connection

创建OAuth连接

az bot authsetting create
--resource-group "${RESOURCE_GROUP}"
--name "${BOT_NAME}"
--setting-name "<connection-name>"
--provider-scope-string "<scopes>"
--client-id "<oauth-client-id>"
--client-secret "<oauth-client-secret>"
--service "Aadv2"

undefined

undefined

Bot Configuration File Templates

Bot配置文件模板

Python (

config.py

)

Python (

config.py

)

python

import os

class DefaultConfig:
    PORT = 3978
    APP_TYPE = os.environ.get("MicrosoftAppType", "SingleTenant")
    APP_ID = os.environ.get("MicrosoftAppId", "")
    APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
    APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")

python

import os

class DefaultConfig:
    PORT = 3978
    APP_TYPE = os.environ.get("MicrosoftAppType", "SingleTenant")
    APP_ID = os.environ.get("MicrosoftAppId", "")
    APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
    APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")

JavaScript (

.env

)

JavaScript (

.env

)

MicrosoftAppType=SingleTenant
MicrosoftAppId=<your-app-id>
MicrosoftAppPassword=<your-app-password>
MicrosoftAppTenantId=<your-tenant-id>

MicrosoftAppType=SingleTenant
MicrosoftAppId=<your-app-id>
MicrosoftAppPassword=<your-app-password>
MicrosoftAppTenantId=<your-tenant-id>

C# (

appsettings.json

)

C# (

appsettings.json

)

json

{
  "MicrosoftAppType": "SingleTenant",
  "MicrosoftAppId": "<your-app-id>",
  "MicrosoftAppPassword": "<your-app-password>",
  "MicrosoftAppTenantId": "<your-tenant-id>"
}

json

{
  "MicrosoftAppType": "SingleTenant",
  "MicrosoftAppId": "<your-app-id>",
  "MicrosoftAppPassword": "<your-app-password>",
  "MicrosoftAppTenantId": "<your-tenant-id>"
}

Management Commands

管理命令

bash

undefined

bash

undefined

List all bots in a resource group

列出资源组中的所有Bot

az bot list --resource-group "${RESOURCE_GROUP}" -o table

Show bot details

查看Bot详情

az bot show --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

Delete a bot

删除Bot

az bot delete --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

Delete a channel

删除渠道

az bot msteams delete --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}" az bot slack delete --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}" az bot telegram delete --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}" az bot directline delete --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}"

Generate a new app password

生成新的应用密码

az ad app credential reset --id "${APP_ID}"

undefined

az ad app credential reset --id "${APP_ID}"

undefined

Troubleshooting

故障排查

Bot not responding

Bot无响应

Check the messaging endpoint is correct and starts with
```
https://
```
Verify App ID and password match between Azure Bot and your app settings

Check App Service logs:

az webapp log tail --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}-app"

检查消息端点是否正确，且以
```
https://
```
开头
确认Azure Bot和应用设置中的App ID与密码一致

查看App Service日志：

az webapp log tail --resource-group "${RESOURCE_GROUP}" --name "${BOT_NAME}-app"

Channel-specific issues

渠道专属问题

Teams: Ensure the bot is also registered in the Teams Developer Portal
Slack: Verify the verification token and OAuth redirect URLs
Telegram: Check the bot token from @BotFather is correct

Teams: 确认Bot也已在Teams开发者门户中注册
Slack: 验证验证令牌和OAuth重定向URL是否正确
Telegram: 检查从@BotFather获取的Bot令牌是否正确

Common errors

常见错误

MicrosoftAppId or MicrosoftAppPassword is not correct

— regenerate password with

az ad app credential reset

Endpoint must start with https

— update endpoint:

az bot update --endpoint "https://..."

```
Bot name already taken
```
— bot names are globally unique, choose a different name

MicrosoftAppId or MicrosoftAppPassword is not correct

— 执行

az ad app credential reset

重新生成密码

Endpoint must start with https

— 更新端点：

az bot update --endpoint "https://..."

```
Bot name already taken
```
— Bot名称是全局唯一的，请选择其他名称

Reference Links

参考链接

Azure Bot registration: https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration
Deploy a bot: https://learn.microsoft.com/en-us/azure/bot-service/provision-and-publish-a-bot
Channel configuration: https://learn.microsoft.com/en-us/azure/bot-service/bot-service-manage-channels
az bot CLI reference: https://learn.microsoft.com/en-us/cli/azure/bot
Bot Framework Samples: https://github.com/microsoft/BotBuilder-Samples

Azure Bot注册: https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration
部署Bot: https://learn.microsoft.com/en-us/azure/bot-service/provision-and-publish-a-bot
渠道配置: https://learn.microsoft.com/en-us/azure/bot-service/bot-service-manage-channels
az bot CLI参考: https://learn.microsoft.com/en-us/cli/azure/bot
Bot Framework示例: https://github.com/microsoft/BotBuilder-Samples