数据传输服务 DTS：使用Kafka客户端消费订阅数据

注意事项

• 使用本文提供的Demo消费数据时，如果采用auto commit（自动提交），可能会因为数据还没被消费完就执行了提交操作，从而丢失部分数据，建议采用手动提交的方式以避免该问题。

  说明

  如果发生故障没有提交成功，重启客户端后会从上一个记录的位点进行数据消费，期间会有部分重复数据，您需要手动过滤。

• 数据以Avro序列化存储，详细格式请参见Record.avsc文档。

  警告

  如果您使用的不是本文提供的Kafka客户端，在进行反序列化解析（DTS Avro的反序列化示例）时，可能出现解析的数据有误，您需要自行验证数据的正确性。

• 关于offsetForTimes接口，DTS的搜索单位为秒，原生Kafka的搜索单位为毫秒。

• 由于数据订阅服务端会因容灾等原因导致网络闪断，若您未使用本文提供的Kafka客户端，您使用的Kafka客户端需具备网络重试能力。

• 若您使用原生的Kafka客户端消费订阅数据，则可能会在DTS发生增量数据采集模块切换行为，从而使subscribe模式下订阅客户端保存在服务端的消费位点被清除，您需要手动调整订阅的消费位点以实现按需消费数据。若您需要使用subscribe模式建议使用DTS提供的订阅SDK消费订阅数据，并且自行管理位点，详情请参见使用SDK消费订阅数据和管理位点。

Kafka客户端运行流程说明

请下载Kafka客户端Demo代码。更多关于代码使用的详细介绍，请参见Demo中的Readme文档。

操作步骤

本文以IntelliJ IDEA软件（Community Edition 2018.1.4 Windows版本）为例，介绍如何运行该客户端消费订阅通道中的数据。

1. 创建新版数据订阅通道，详情请参见订阅方案概览中的相关配置文档。

2. 创建一个或多个消费组，详情请参见新增消费组。

3. 下载Kafka客户端Demo代码，然后解压该文件。

   说明

   单击

4. 打开IntelliJ IDEA软件，然后单击Open。

5. 在弹出的对话框中，定位至Kafka客户端Demo代码下载的目录，参照下图依次展开文件夹，找到项目对象模型文件：pom.xml。

6. 在弹出对话框中，选择Open as Project。

7. 在IntelliJ IDEA软件界面，依次展开文件夹，找到并双击打开Kafka客户端Demo文件：NotifyDemoDB.java。

8. 设置NotifyDemoDB.java文件中的各参数对应的值。

   参数	说明	获取方式
   USER_NAME	消费组的账号。 警告 如您未使用本文提供的客户端，请按照<消费组的账号>-<消费组ID>的格式设置用户名（例如：dtstest-dtsae******bpv），否则无法正常连接。	在DTS控制台单击目标订阅实例ID，然后单击左侧导航栏的数据消费，您可以获取到消费组ID/名称和消费组的账号信息。 说明 消费组账号的密码已在您新建消费组时指定。
   PASSWORD_NAME	该账号的密码。
   SID_NAME	消费组ID。
   GROUP_NAME	消费组名称，需保持和消费组ID相同（即本参数也填入消费组ID）。
   KAFKA_TOPIC	数据订阅通道的订阅Topic。	在DTS控制台单击目标订阅实例ID，在基本信息页面，您可以获取到订阅Topic和网络信息。
   KAFKA_BROKER_URL_NAME	数据订阅通道的网络地址信息。 说明 如果您部署Kafka客户端所属的ECS实例与数据订阅通道属于经典网络或同一专有网络，建议通过内网地址进行数据订阅，网络延迟最小。 鉴于网络稳定性因素，不建议使用公网地址。
   INITIAL_CHECKPOINT_NAME	消费的数据时间点，格式为Unix时间戳，例如1592269238。 说明 您需要自行保存时间点信息，以便： 当业务程序中断后，传入已消费的数据时间点继续消费数据，防止数据丢失。 在订阅客户端启动时，传入所需的消费位点，调整订阅位点，实现按需消费数据。 若SUBSCRIBE_MODE_NAME为subscribe时，传入的INITIAL_CHECKPOINT_NAME仅在订阅客户端首次启动时生效。	消费的数据时间点必须在订阅实例的数据范围之内，并需转化为Unix时间戳。 说明 您可以在订阅任务列表的数据范围列，查看订阅实例的数据范围。 Unix时间戳转换工具可用搜索引擎获取。
   USE_CONFIG_CHECKPOINT_NAME	默认取值为true，即强制使用指定的数据时间点来消费数据，避免丢失已接收到的但未处理的数据。	无
   SUBSCRIBE_MODE_NAME	一个消费组下支持同时启动两个及以上Kafka客户端，如需实现该功能，请将所有客户端该参数的值设置为subscribe。 默认值为assign，即不使用该功能，建议只部署一个客户端。	无

9. 在IntelliJ IDEA软件界面的顶部，选择Run > Run运行该客户端。

   说明

   首次运行时，软件需要一定时间自动加载相关依赖包并完成安装。

执行结果

运行结果该客户端可正常订阅到源库的数据变更信息。

您也可以去除NotifyDemoDB.java文件中的打印日志详情的注释（即删除第25行//log.info(ret);中的//），然后再次运行该客户端即可查看详细的数据变更信息。

常见问题

• Q：为什么需要自行记录客户端的消费位点？

  A：由于DTS记录的消费位点是接收到Kafka消费客户端执行commit操作的时间点，可能与当前实际消费到的时间点存在一定的时间差。当业务程序或Kafka消费客户端异常中断后，您可以传入自行记录的消费位点以继续消费，避免消费到重复的数据或缺失部分数据。

管理位点

1. 配置订阅客户端监听DTS的数据采集模块的切换行为。

   通过配置订阅客户端的Consumer的properties，监听DTS的数据采集模块的切换行为，实现方法的主要内容如下所示：

   properties.setProperty(ConsumerConfig.INTERCEPTOR_CLASSES_CONFIG, ClusterSwitchListener.class.getName());

   ClusterSwitchListener的实现方法如下所示：

   public class ClusterSwitchListener implements ClusterResourceListener, ConsumerInterceptor {
       private final static Logger LOG = LoggerFactory.getLogger(ClusterSwitchListener.class);
       private ClusterResource originClusterResource = null;
       private ClusterResource currentClusterResource = null;
   
       public ConsumerRecords onConsume(ConsumerRecords records) {
           return records;
       }
   
   
       public void close() {
       }
   
       public void onCommit(Map offsets) {
       }
   
   
       public void onUpdate(ClusterResource clusterResource) {
           synchronized (this) {
               originClusterResource = currentClusterResource;
               currentClusterResource = clusterResource;
               if (null == originClusterResource) {
                   LOG.info("Cluster updated to " + currentClusterResource.clusterId());
               } else {
                   if (originClusterResource.clusterId().equals(currentClusterResource.clusterId())) {
                       LOG.info("Cluster not changed on update:" + clusterResource.clusterId());
                   } else {
                       LOG.error("Cluster changed");
                       throw new ClusterSwitchException("Cluster changed from " + originClusterResource.clusterId() + " to " + currentClusterResource.clusterId()
                               + ", consumer require restart");
                   }
               }
           }
       }
   
       public boolean isClusterResourceChanged() {
           if (null == originClusterResource) {
               return false;
           }
           if (originClusterResource.clusterId().equals(currentClusterResource.clusterId())) {
               return false;
           }
           return true;
       }
   
       public void configure(Map<String, ?> configs) {
       }
   
       public static class ClusterSwitchException extends KafkaException {
           public ClusterSwitchException(String message, Throwable cause) {
               super(message, cause);
           }
   
           public ClusterSwitchException(String message) {
               super(message);
           }
   
           public ClusterSwitchException(Throwable cause) {
               super(cause);
           }
   
           public ClusterSwitchException() {
               super();
           }
   
       }

2. 处理捕获到DTS数据采集模块的切换行为。

   将实际消费的最后一条订阅数据的时间位点（timestamp），设置为下一次订阅的初始位点，实现方法的主要内容如下所示：

   try{
      //do some action
   } catch (ClusterSwitchListener.ClusterSwitchException e) {
      reset();
   }
   
   //重置位点
   public reset() {
     long offset = kafkaConsumer.offsetsForTimes(timestamp);
     kafkaConsumer.seek(tp,offset);
   }

   说明

   实现方法示例，请参见KafkaRecordFetcher。

字段类型与dataTypeNumber数值的对应关系