DingTalk Stream SDK Python 开发实战指南

DingTalk Stream SDK Python 开发实战指南

【免费下载链接】dingtalk-stream-sdk-python Python SDK for DingTalk Stream Mode API, Compared with the webhook mode, it is easier to access the DingTalk chatbot 项目地址: https://gitcode.com/gh_mirrors/di/dingtalk-stream-sdk-python

DingTalk Stream SDK for Python 是钉钉官方推出的Python集成工具包，专为构建企业级实时通讯应用而生。相比传统的Webhook模式，Stream模式提供了更简单、更稳定的接入方式，支持事件推送、机器人收消息以及卡片回调等功能。

快速开始

环境准备

首先需要安装DingTalk Stream SDK：

pip install dingtalk-stream

基础示例

以下是一个简单的Hello World示例，展示了如何使用Stream SDK接收和处理消息：

#!/usr/bin/env python

import argparse
from dingtalk_stream import AckMessage
import dingtalk_stream

def define_options():
    parser = argparse.ArgumentParser()
    parser.add_argument(
        '--client_id', dest='client_id', required=True,
        help='app_key or suite_key from https://open-dev.digntalk.com'
    )
    parser.add_argument(
        '--client_secret', dest='client_secret', required=True,
        help='app_secret or suite_secret from https://open-dev.digntalk.com'
    )
    options = parser.parse_args()
    return options

class MyEventHandler(dingtalk_stream.EventHandler):
    async def process(self, event: dingtalk_stream.EventMessage):
        print(event.headers.event_type,
              event.headers.event_id,
              event.headers.event_born_time,
              event.data)
        return AckMessage.STATUS_OK, 'OK'

class MyCallbackHandler(dingtalk_stream.CallbackHandler):
    async def process(self, message: dingtalk_stream.CallbackMessage):
        print(message.headers.topic,
              message.data)
        return AckMessage.STATUS_OK, 'OK'

def main():
    options = define_options()

    credential = dingtalk_stream.Credential(options.client_id, options.client_secret)
    client = dingtalk_stream.DingTalkStreamClient(credential)
    client.register_all_event_handler(MyEventHandler())
    client.register_callback_handler(dingtalk_stream.ChatbotMessage.TOPIC, MyCallbackHandler())
    client.start_forever()

if __name__ == '__main__':
    main()

核心功能详解

计算机器人示例

创建一个能够处理数学表达式的智能机器人：

class CalcBotHandler(dingtalk_stream.ChatbotHandler):
    def __init__(self, logger: logging.Logger = None):
        super(dingtalk_stream.ChatbotHandler, self).__init__()
        if logger:
            self.logger = logger

    async def process(self, callback: dingtalk_stream.CallbackMessage):
        incoming_message = dingtalk_stream.ChatbotMessage.from_dict(callback.data)
        expression = incoming_message.text.content.strip()
        try:
            result = eval(expression)
        except Exception as e:
            result = 'Error: %s' % e
        self.logger.info('%s = %s' % (expression, result))
        response = 'Q: %s\nA: %s' % (expression, result)
        self.reply_text(response, incoming_message)

        return AckMessage.STATUS_OK, 'OK'

卡片机器人功能

实现动态卡片交互功能，可以发送和更新卡片消息：

class CardBotHandler(dingtalk_stream.AsyncChatbotHandler):
    """
    接收回调消息。
    回复一个卡片，然后更新卡片的文本和图片。
    """

    def __init__(self, logger: logging.Logger = None, max_workers: int = 8):
        super(CardBotHandler, self).__init__(max_workers=max_workers)
        if logger:
            self.logger = logger

    def process(self, callback: dingtalk_stream.CallbackMessage):
        incoming_message = dingtalk_stream.ChatbotMessage.from_dict(callback.data)

        card_instance = self.reply_markdown_card("**这是一个markdown消息，初始状态，将于5s后更新**", incoming_message,
                                             title="钉钉AI卡片",
                                             logo="@lALPDfJ6V_FPDmvNAfTNAfQ")

        # 如果需要更新卡片内容的话，使用这个：
        time.sleep(5)
        card_instance.update("**这是一个markdown消息，已更新**")

        return AckMessage.STATUS_OK, 'OK'

卡片回调处理

处理用户对卡片的交互操作：

class CardCallbackHandler(dingtalk_stream.CallbackHandler):
    def __init__(self, logger: logging.Logger = None):
        super(dingtalk_stream.CallbackHandler, self).__init__()
        if logger:
            self.logger = logger

    async def process(self, callback: dingtalk_stream.CallbackMessage):
        # 卡片回调的数据构造
        response = {
            'cardData': {
                'cardParamMap': {
                    'intParam': '1',
                    'trueParam': 'true',
                }},
            'privateData': {
                'myUserId': {
                    'cardParamMap': {
                        'floatParam': '1.23',
                        'falseparam': 'false',
                    },
                }
            }
        }
        return AckMessage.STATUS_OK, response

高级用法

自定义事件循环

如果你需要在已有的asyncio事件循环中使用钉钉Stream模式，可以使用client.start()代替client.start_forever()：

try:
    await client.start()
except (asyncio.exceptions.CancelledError,
        websockets.exceptions.ConnectionClosedError) as e:
    ... # 处理网络断线异常

离线消息处理

设置机器人离线时的自动回复：

card_bot_handler.set_off_duty_prompt("不好意思，我已下班，请稍后联系我！")

实际应用场景

智能客服系统

利用Stream SDK的实时消息处理能力，结合自然语言理解技术，打造24/7不间断的智能客服系统。

工作流自动化

集成企业内部系统，实现审批流程、任务提醒的自动化推送，大幅提升团队协作效率。

实时数据监控

通过监听钉钉事件流，构建业务数据仪表盘，为企业决策提供实时数据支持。

最佳实践建议

1. 错误处理：在生产环境中，确保对所有可能的异常情况进行处理
2. 日志记录：配置适当的日志级别，便于问题排查和系统监控
3. 性能优化：合理设置线程池大小，避免资源浪费
4. 安全考虑：妥善保管client_id和client_secret等敏感信息

版本升级说明

从旧版本升级到v0.13.0时需要注意，由于拼写修正，需要将register_callback_hanlder修改为register_callback_handler

通过本指南，你可以快速掌握DingTalk Stream SDK的核心功能，构建强大的企业级实时通讯应用。

【免费下载链接】dingtalk-stream-sdk-python Python SDK for DingTalk Stream Mode API, Compared with the webhook mode, it is easier to access the DingTalk chatbot 项目地址: https://gitcode.com/gh_mirrors/di/dingtalk-stream-sdk-python