Structured Streaming + Kafka Integration Guide 结构化流+Kafka集成指南 (Kafka broker version 0.10.0 or higher)

用于Kafka 0.10的结构化流集成从Kafka读取数据并将数据写入到Kafka。

1. Linking

对于使用SBT/Maven项目定义的Scala/Java应用程序，用以下工件artifact连接你的应用程序：

对于Python应用程序，你需要在部署应用程序时添加上面的库及其依赖关系。查看Deploying子节点。

2. Reading Data from Kafka 从Kafka读取数据

2.1 Creating a Kafka Source for Streaming Queries 为流式查询创建一个Kafka来源

2.2 Creating a Kafka Source for Batch Queries 为批处理查询创建一个Kafka来源

如果你有一个更适合用于批处理的用例，你可以为定义的偏移量范围创建一个Dataset/DataFrame。

来源的每一行有以下格式：

Column	Type
key	binary
value	binary
topic	string
partition	int
offset	long
timestamp	long
timestampType	int

对于批处理和流式查询，必须为Kafka来源设置以下选项。

Option	value	meaning
assign	json string {"topicA":[0,1],"topicB":[2,4]}	要使用特定TopicPartition。对于Kafka来源，只能指定“assign”,"subscribe"或者“subscribePattern”选项中的一个。
subscribe	A comma-separated list of topics	要订阅的主题列表.对于Kafka来源，只能指定“assign”,"subscribe"或者“subscribePattern”选项中的一个。
subscribePattern	Java regex string	用于订阅主题的格式。对于Kafka来源，只能指定“assign”,"subscribe"或者“subscribePattern”选项中的一个。
kafka.bootstrap.servers	A comma-separated list of host:port	Kafka "bootstrap.servers" 配置。

以下配置是可选的：

Option	value	default	query type	meaning
startingOffsets	"earliest", "latest" (streaming only), or json string """ {"topicA":{"0":23,"1":-1},"topicB":{"0":-2}} """	"latest"用于流, "earliest" 用于批量	streaming and batch 流和批量	查询开始时的起始点，可以是最早偏移量的“earliest”，也可以是最近偏移量的“latest”，也可以是指定每个TopicPartition起始偏移量的json字符串。在Json中，-2作为偏移量可以用来指最早的，-1指最新的。注意：对于批量查询，不允许使用最新（隐式或在json中使用-1）。对于流式查询，这仅适用于新查询开始时的情况，并且恢复将始终从查询停止的地方开始。在查询期间新发现的分区将从earliest开始。
endingOffsets	latest or json string {"topicA":{"0":23,"1":-1},"topicB":{"0":-1}}	latest	batch query 批量查询	批量查询结束时的结束点，可以是最新引用的“latest”，也可以是指定每个TopicPartition结束偏移量的json字符串。在json中，-1作为偏移量可以用于引用最新的，-2（最早的）作为偏移量是不允许的。
failOnDataLoss	true or false	true	streaming query 流式查询	当可能丢失数据时是否让查询失败（例如，主题被删除或偏移超出范围）。这可能是一个虚惊。当它不像你期望的那样工作时，你可以禁用它。如果由于丢失数据而无法从提供的偏移量中读取任何数据，批量查询将始终失败。
kafkaConsumer.pollTimeoutMs	long	512	streaming and batch	在executors中轮询来自Kafka的数据的超时时间（以毫秒为单位）
fetchOffset.numRetries	int	3	streaming and batch	在放弃提取Kafka偏移量之前重试的次数。
fetchOffset.retryIntervalMs	long	10	streaming and batch	重试去提取Kafka偏移量之前等待的毫秒数。
maxOffsetsPerTrigger	long	none	streaming and batch	每次触发间隔处理的最大偏移量的速率限制。指定的偏移量总数将按不同卷的topicPartition成比例地分割。

3. Writing Data to Kafka 将数据写入到Kafka

这里，我们描述了向Apache Kafka写入流式查询和批量查询的支持。注意Apache Kafka只支持至少一次写入语义。因此，在向Kafka写入流式查询或批量查询时，可能会复制一些记录；例如，如果Kafka需要重试未被Broker确认的消息，即使该Broker接收并编写了消息记录，也会发生这种情况。由于这些Kafka写入语义，结构化流不能阻止这种复制发生。然而，如果编写查询是成功的，那么你可以假定查询输出至少写入一次。当读取写入的数据删除重复项的可能解决方法可能是引入主要（唯一）key，当读取时这key可以用于执行重复数据删除。

写入到Kafka的Dataframe应该在模式上有以下列：

Column	Type
key (optional)	string or binary
value (required)	string or binary
topic (*optional)	string

* 如果“topic”配置选项不指定，则topic列是必须的。

value列是唯一要求的选项。如果key列没有指定，那么将会自动添加值为null的key列（查看Kafka语义中关于如何处理空值key）。如果topic列存在，那么在将给予的行写入到Kafka时，它的值用作topic，除非设置好“topic”配置选项。例如，“topic”配置选项覆盖topic列。

对于批量和流式查询，必须为Kafka sink设置以下选项：

Option	value	meaning
kafka.bootstrap.servers	A comma-separated list of host:port	Kafka "bootstrap.servers"配置。

以下选项是可选的：

Option	value	default	query type	meaning
topic	string	none	streaming and batch	设置所有行将在Kafka中写入的topic。该选项将覆盖数据中可能存在的任何topic列。

3.1 Creating a Kafka Sink for Streaming Queries 为流式查询创建Kafka Sink

3.2 Writing the output of Batch Queries to Kafka 将批量查询的输出写入到Kafka中

4. Kafka Specific Configurations Kafka特定的配置

Kafka自己的配置可以通过带有Kafka.prefix的DataStreamReader.option进行设置。例如，stream.option("kafka.bootstrap.servers","host":"port")。有关可能的Kafka参数，参阅Kafka消费者配置文档以获取与读取数据相关的参数，以及Kafka生产者配置文件以获取与写入数据相关的参数。

注意以下Kafka参数不能设置，Kafka source或者sink将会抛出错误。

• group.id: Kafka source将会自动为每次查询创建唯一的分组id。
• auto.offset.reset: 将source选项startingOffsets设置为指定从哪里开始。结构化流管理内部消费的偏移量，而不是依赖Kafka消费者来完成。这将确保在topic/partitons动态订阅时不会遗漏任何数据。注意，只有在启动新的流式查询时才会应用startingOffsets，并且恢复操作始终会从查询停止的位置启动。.
• key.deserializer:Keys总是被反序列化为ByteArrayDeserializer的字节数组。使用DataFrame操作显式反序列化keys。
• value.deserializer:Values总是被反序列化为ByteArrayDeserializer的字节数组。使用DataFrame操作显式反序列化values。
• key.serializer: keys总是使用ByteArraySerializer或StringSerializer进行序列化。使用DataFrame操作将keys显示序列化为字符串或字节数组。
• value.serializer: values总是使用ByteArraySerializer或StringSerializer进行序列化使用DataFrame操作将values显示序列化为字符串或字节数组。
• enable.auto.commit: Kafka source不提交任何offset。
• interceptor.classes: Kafka source总是以字节数组的形式读取key和value。使用ConsumerInterceptor是不安全的，因为它可能会打断查询。

5. Deploying 部署

与任何Spark应用程序一样，spark-submit用于启动你的应用程序。spark-sql-kafka-0-10_2.11及其依赖关系可以直接添加到使用--packages的spark-submit中，例如，

更多关于提交带有外部依赖项的应用程序的详细信息参阅Application Submission Guide。