From 06837d4a563cb61160e4c4816e12a373f27fae88 Mon Sep 17 00:00:00 2001 From: Artin Date: Fri, 29 Jan 2021 14:29:29 +0800 Subject: [PATCH] :memo: add ding-guide --- docs/guide/ding-guide.md | 116 +++++++++++++++++++++++++++++++++- docs/guide/getting-started.md | 2 +- 2 files changed, 116 insertions(+), 2 deletions(-) diff --git a/docs/guide/ding-guide.md b/docs/guide/ding-guide.md index 88c62ca9..45a5a658 100644 --- a/docs/guide/ding-guide.md +++ b/docs/guide/ding-guide.md @@ -1,3 +1,117 @@ # 钉钉机器人使用指南 -~~TODO~~ +基于企业机器人的outgoing(回调)机制,用户@机器人之后,钉钉会将消息内容POST到开发者的消息接收地址。开发者解析出消息内容、发送者身份,根据企业的业务逻辑,组装响应的消息内容返回,钉钉会将响应内容发送到群里。 + +::: warning 只有企业内部机器人支持接收消息 +普通的机器人尚不支持应答机制,该机制指的是群里成员在聊天@机器人的时候,钉钉回调指定的服务地址,即Outgoing机器人。 +::: + +首先你需要有钉钉机器人的相关概念,请参阅相关文档: + +- [群机器人概述](https://developers.dingtalk.com/document/app/overview-of-group-robots) +- [开发企业内部机器人](https://developers.dingtalk.com/document/app/develop-enterprise-internal-robots) + +## 关于 DingAdapter 的说明 + +你需要显式的注册 ding 这个适配器: + +```python{2,6} +import nonebot +from nonebot.adapters.ding import Bot as DingBot + +nonebot.init() +driver = nonebot.get_driver() +driver.register_adapter("ding", DingBot) +nonebot.load_builtin_plugins() + +if __name__ == "__main__": + nonebot.run() +``` + +注册适配器的目的是将 `/ding` 这个路径挂载到程序上,并且和 DingBot 适配器关联起来。之后钉钉把收到的消息回调到 `http://xx.xxx.xxx.xxx:{port}/ding` 时,Nonebot 才知道要用什么适配器去处理该消息。 + +## 第一个命令 + +因为 Nonebot 可以根据你的命令处理函数的类型注解来选择使用什么 Adapter 进行处理,所以你如果需要使用钉钉相关的功能,你的 handler 中 `bot` 类型的注解需要是 DingBot 及其父类。 + +对于 Event 来说也是如此,Event 也可以根据标注来判断,比如一个 handler 的 event 标注位 `PrivateMessageEvent`,那这个 handler 只会处理私聊消息。 + +举个栗子: + +```python +test = on_command("test", to_me()) + + +@test.handle() +async def test_handler1(bot: DingBot, event: PrivateMessageEvent): + await test.finish("PrivateMessageEvent") + + +@test.handle() +async def test_handler2(bot: DingBot, event: GroupMessageEvent): + await test.finish("GroupMessageEvent") +``` + +这样 Nonebot 就会根据不同的类型注解使用不同的 handler 来处理消息。 + +## 多种消息格式 + +发送 markdown 消息: + +```python +@markdown.handle() +async def markdown_handler(bot: DingBot): + message = MessageSegment.markdown( + "Hello, This is NoneBot", + "#### NoneBot \n> Nonebot 是一款高性能的 Python 机器人框架\n> ![screenshot](https://v2.nonebot.dev/logo.png)\n> [GitHub 仓库地址](https://github.com/nonebot/nonebot2) \n" + ) + await markdown.finish(message) +``` + +可以按自己的需要发送原生的格式消息(需要使用 `MessageSegment` 包裹,可以很方便的实现 @ 等操作): + +```python +@raw.handle() +async def raw_handler(bot: DingBot, event: MessageEvent): + message = MessageSegment.raw({ + "msgtype": "text", + "text": { + "content": f"@{event.senderId},你好" + }, + }) + message += MessageSegment.atDingtalkIds(event.senderId) + await raw.send(message) +``` + +其他消息格式请查看 [钉钉适配器的 MessageSegment](https://github.com/nonebot/nonebot2/blob/master/nonebot/adapters/ding/message.py#L8),里面封装了很多有关消息的方法,比如 `code`、`image`、`feedCard` 等。 + +## 创建机器人并连接 + +在钉钉官方文档 「开发企业内部机器人 -> 步骤一:创建机器人应用] 中有详细介绍,这里就省去创建的步骤,介绍一下如何连接上程序。 + +### 本地开发机器人 + +在本地开发机器人的时候可能没有公网 IP,钉钉官方给我们提供一个 [内网穿透工具](https://developers.dingtalk.com/document/resourcedownload/http-intranet-penetration?pnamespace=app),方便开发测试。 + +::: tip +究其根源这是一个魔改版的 ngrok,钉钉提供了一个服务器。 + +本工具不保证稳定性,仅适用于开发测试阶段,禁止当作公网域名使用。如线上应用使用本工具造成稳定性问题,后果由自己承担。如使用本工具传播违法不良信息,钉钉将追究法律责任。 +::: + +官方文档里已经讲了如何使用。我们再以 Windows(终端使用 Powershell) 为例,来演示一下。 + +1. 将仓库 clone 到本地,打开 `windows_64` 文件夹。 +2. 执行 `.\ding.exe -config="./ding.cfg" -subdomain=rcnb 8080` 就可以将 8080 端口暴露到公网中。 + 你访问 http://rcnb.vaiwan.com/xxxxx 都会映射到 http://127.0.0.1:8080/xxxxx。 + +假设我们的机器人监听的端口是 `2333`,并且已经注册了钉钉适配器。那我们就执行 `.\ding.exe -config="./ding.cfg" -subdomain=rcnb 2333`,然后在机器人的后台设置 POST 的地址:`http://rcnb.vaiwan.com/ding`。 +这样钉钉接收到消息之后就会 POST 消息到 `http://rcnb.vaiwan.com/ding` 上,然后这个服务会把消息再转发到我们本地的开发服务器上。 + +### 生产模式 + +生产模式你的机器需要有一个公网 IP,然后到机器人的后台设置 POST 的地址就好了。 + +## 示例 + +关于钉钉机器人能做啥,你可以查看 `https://github.com/nonebot/nonebot2/blob/master/tests/test_plugins/test_ding.py`,里面有一些例子。 diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index d35665a2..b23a0de7 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -12,7 +12,7 @@ nb create 根据脚手架引导,将在当前目录下创建一个项目目录,项目目录内包含 `bot.py`。 -如果未安装 `nb-cli`,使用你最熟悉的编辑器或 IDE,创建一个名为 `bot.py` 的文件,内容如下(这里以 CQHTTP 为例): +如果未安装 `nb-cli`,使用你最熟悉的编辑器或 IDE,创建一个名为 `bot.py` 的文件,内容如下(这里以 CQHTTP 适配器为例): ```python{4,6,7,10} import nonebot