服务端Stream模式

​

什么是Stream模式

Stream 模式是钉钉开放平台提供的一种集成方式，它可以监听机器人回调、事件订阅回调和注册卡片回调。使用 Stream 模式接入，钉钉开放平台将通过 Websocket 连接与应用程序通讯，Stream 模式将极大降低接入门槛和资源依赖，不需要公网服务器、IP、域名等资源，只需集成钉钉开放平台 SDK 即可。

​

Stream模式原理

在 Stream 模式下，开发者的应用程序通过集成 SDK 的方式与钉钉开放平台建立一条 WebSocket 连接，建立连接过程中开放平台将对连接进行鉴权。当有卡片回调发生时，开放平台将通过 WebSocket 连接将数据通知到开发者的应用程序。开发者的应用程序可以接收到这些数据并进行相应处理，从而实现与钉钉开放平台的实时通信，参考下图所示

​

Stream模式优势

在钉钉开放平台向应用程序发送请求的场景中，大部分都是采用 Webhook （注册公网 HTTPS 服务）的方式，包括卡片回调，使用 Webhook 方式开发过程中会遇到较多的问题，包括

• 申请公网域名和TLS证书
• 申请公网IP并部署接入网关
• 部署应用防火墙并配置白名单
• 独立处理请求的鉴权，以及加解密处理
• 搭建内网穿透环境进行本地开发调试

针对以上问题，Stream 模式将为开发者提供”五零”接入体验，将1~2周的接入开发周期降低到5分钟，包括

• 零公网IP 不需要依赖公网IP或域名，也不需要暴露公网IP，减少了公网暴露服务的安全风险并降低了开发门槛。
• 零加解密/签名/TLS证书管理 使用应用身份对连接进行鉴权，通过反向连接的方式与钉钉开放平台建立TLS加密连接，提供了快速、安全的通信体验。
• 零防火墙白名单 Stream 模式下开发者无需向公网开放提供任何服务端口，无需部署防火墙和配置白名单。
• 零网关部署 通过反向连接的方式建立通道，开发者只需保证运行环境具备公网访问能力即可，无需部署网关。
• 零内网穿透 开发者无需在本地搭建内网穿透工具，通过 Stream 模式在本地开发环境中即可接收卡片回调。

​

接入方式

重要 客户端启动后即可收到对应卡片的回调，测试、开发环境部署要避免影响生产环境。

​

接入限制

1. 应用程序所部署环境具备访问公网的能力。
2. 仅适用于企业内部开发和第三方企业应用。
3. 每个客户端实例默认启用一条 WebSocket 连接，一个应用默认最多建立50条连接。

​

Java

• ​

  运行环境

  JDK1.8及以上。

• ​

  安装Java SDK

  添加依赖项到工程的pom.xml文件或下载对应的jar包，最新的 SDK 版本可以在这里查看和下载。
  <dependency>
    <groupId>com.dingtalk.open</groupId>
    <artifactId>dingtalk-stream</artifactId>
    <version>{sdk-version}</version>
  </dependency>
  

• ​

  示例代码

  机器人回调
  public static void main(String[] args) throws Exception {
          OpenDingTalkStreamClientBuilder
                  .custom()
                  .credential(new AuthClientCredential("${clientId}", "${clientSecret}"))
                  //注册机器人监听器
                  .registerCallbackListener("${topic}", robotMessage -> {
                      log.info("receive robotMessage, {}", robotMessage);
                      //开发者根据自身业务需求，处理机器人回调
                      return new JSONObject();
  
                  })
                  .build().start();
  }
  
  详情参见机器人开发文档。 参数说明

  参数名	说明
  clientId	企业内部开发 AppKey/第三方企业应用 SuiteKey。
  clientSecret	企业内部开发 AppSecret/第三方企业应用 SuiteSecret。
  topic	机器人回调名称，固定值：/v1.0/im/bot/messages/get。

  事件订阅回调
  public static void main(String[] args) {
    OpenDingTalkStreamClientBuilder
      .custom()
      .credential(new AuthClientCredential("${clientId}", "${clientSecret}"))
      //注册事件监听
      .registerAllEventListener(new GenericEventListener() {
        public EventAckStatus onEvent(GenericOpenDingTalkEvent event) {
          try {
            //事件唯一Id
            String eventId = event.getEventId();
            //事件类型
            String eventType = event.getEventType();
            //事件产生时间
            Long bornTime = event.getEventBornTime();
            //获取事件体
            JSONObject bizData = event.getData();
            //处理事件
            process(bizData);
            //消费成功
            return EventAckStatus.SUCCESS;
          } catch (Exception e) {
            //消费失败
            return EventAckStatus.LATER;
          }
        }
      })
      .build().start();
  }
  
  详情参见配置Stream推送。 参数说明

  参数名	说明
  clientId	企业内部开发 AppKey/第三方企业应用 SuiteKey。
  clientSecret	企业内部开发 AppSecret/第三方企业应用 SuiteSecret。

  卡片回调
  public static void main(String[] args) throws Exception {
          OpenDingTalkStreamClientBuilder
                  .custom()
                  .credential(new AuthClientCredential("${clientId}", "${clientSecret}"))
                  //注册卡片回传监听器
                  .registerCallbackListener("/v1.0/card/instances/callback", callbackData -> {
                      log.info("receive call back request, {}", callbackData);
                      //your code is here
  
                      //开发者根据自身业务需求，变更卡片内容，返回response
                      CardCallbackResponse resp = new CardCallbackResponse();
                      return resp;
  
                  })
                  .build().start();
  }
  
  详情参见互动卡片 Stream 。 参数说明

  参数名	说明
  clientId	企业内部开发 AppKey/第三方企业应用 SuiteKey。
  clientSecret	企业内部开发 AppSecret/第三方企业应用 SuiteSecret。
  topic	注册的卡片回调名称，固定值：/v1.0/card/instances/callback。

​

Golang

• ​

  运行环境

  1.16及以上。

• ​

  安装SDK

  go get github.com/open-dingtalk/dingtalk-stream-sdk-go
  

• ​

  示例代码

  机器人回调
  func OnChatReceive(ctx context.Context, data *chatbot.BotCallbackDataModel) error {
  	return nil
  }
  
  func StartRobot() {
  	logger.SetLogger(logger.NewStdTestLogger())
  	cli := client.NewStreamClient(
      client.WithAppCredential(client.NewAppCredentialConfig(${clientId}, ${clientSecret})),
  		client.WithUserAgent(client.NewDingtalkGoSDKUserAgent()),
      client.WithSubscription(utils.SubscriptionTypeKCallback, ${topic}, chatbot.NewDefaultChatBotFrameHandler(OnChatReceive).OnEventReceived),
  	)
  
  	err := cli.Start(context.Background())
  	if err != nil {
  		panic(err)
  	}
  
  	defer cli.Close()
  
  	select {}
  }
  
  参数说明

  参数名	说明
  clientId	企业内部开发 AppKey/第三方企业应用 SuiteKey。
  clientSecret	企业内部开发 AppSecret/第三方企业应用 SuiteSecret。
  topic	机器人回调名称，固定值：/v1.0/im/bot/messages/get。

​

其他语言接入方式

• Java SDK接入示例工程
• Golang SDK及示例代码
• Python SDK及示例代码
• Node.js SDK及示例代码

过程中有问题也可以通过技术支持提交反馈和问题交流。

​

技术支持

开发过程中如有任何疑问，可加入钉钉 Stream 模式共创群咨询答疑，Stream 模式共创群。