kafka04-消费者

1、python中KafkaConsumer类

1、KafkaConsume类

class kafka.KafkaConsumer(*topics, **configs)

• 使用Kafka集群的记录。
• 消费者将透明地处理Kafka集群中服务器的故障，并在topic分区创建或在broker之间迁移时进行调整。它还与已分配的kafka Group Coordinator节点交互，以允许多个消费者对topic的消费进行负载均衡(要求 kafka >= 0.9.0.0)。
• 消费者不是线程安全的，不应跨线程共享。

下面介绍KafkaConsumer类的位置参数：

topics(str)

• 要订阅的可选主题列表。如果没有设置，在消费记录之前调用subscribe()或assign()。

下面介绍KafkaConsumer类的关键字参数：

1、bootstrap_servers

• 'host[:port]'字符串(或'host[:port]'字符串列表)，例如bootstrap_servers='host[:port]'（或['host1[:port]','host2[:port]','host3[:port]']）
• 消费者应该联系它来启动初始集群元数据。这不必是完整的节点列表。它只需要至少有一个代理来响应元数据 API 请求。默认端口为 9092。
• 如果未指定服务器，则默认为localhost:9092。

2、client_id(str)

• 此客户端的名称。该字符串在每个请求中传递给服务器，可用于识别与此客户机对应的特定服务器端日志条目。也提交给GroupCoordinator，用于记录有关消费者组管理的日志。
• 默认值：'kafka-python-{version}'

3、group_id(str or None)

• 要加入动态分区分配（如果启用）并用于获取和提交偏移量的消费者组的名称。如果为None，则禁用自动分区分配(通过组协调器)和偏移提交。
• 默认值：None

4、key_deserializer (callable)

• 任何采用原始消息键并返回反序列化键的可调用对象。

5、value_deserializer(callable)

• 任何采用原始消息值并返回反序列化值的可调用对象。

6、fetch_min_bytes(int)

• 服务器（消费者服务端）应为获取请求返回的最小数据量，否则最多等待fetch_max_wait_ms以积累更多数据。
• 默认值：1。

7、fetch_max_wait_ms(int)

• 如果没有足够的数据来立即满足fetch_min_bytes给出的要求，则服务器在响应获取请求之前将阻塞的最长时间（以毫秒为单位）。
• 默认值：500。

8、fetch_max_bytes(int)

• 服务器应该为获取请求返回的最大数据量。这不是一个绝对最大值，如果fetch的第一个非空分区中的第一个消息大于这个值，仍然会返回该消息，以确保消费者可以进行操作。
• 注意：消费者对多个代理并行执行取回操作，因此内存使用将取决于包含主题分区的代理的数量。支持的 Kafka 版本 >= 0.10.1.0。
• 默认值：52428800 (50 MB)。

9、max_partition_fetch_bytes(int)

• 服务器将返回的每个分区的最大数据量。用于请求的最大总内存 = #partitions * max_partition_fetch_bytes。这个大小必须至少与服务器允许的最大消息大小一样大，否则生产者发送的消息可能大于消费者可以获取的消息。如果发生这种情况，消费者可能会在尝试获取某个分区上的大消息时陷入困境。
• 默认值：1048576。

10、request_timeout_ms(int)

• 客户端请求超时，以毫秒为单位。
• 默认值：305000。

11、retry_backoff_ms(int)

• 重试错误时退避的毫秒数。
• 默认值：100。

12、reconnect_backoff_ms(int)

• 尝试重新连接到给定主机之前等待的时间(以毫秒为单位)。
• 默认值：50。

13、reconnect_backoff_max_ms(int)

• 当重新连接到重复连接失败的代理时，后退/等待的最大时间(以毫秒为单位)。
  • 如果提供，每个主机的回退将在每次连续连接失败时呈指数级增加，直到这个最大值。一旦达到最大值，重新连接尝试将以这个固定速率周期性地继续。
  • 为了避免连接风暴，将对回退应用0.2的随机因素，从而产生一个介于计算值以下20%和以上20%之间的随机范围。
• 默认值：1000。

14、max_in_flight_requests_per_connection(int)

• 请求通过管道传输到kafka代理，最多达到每个代理连接的最大请求数。
• 默认值：5。

15、auto_offset_reset(str)

• 用于在OffsetOutOfRange错误上重置偏移量的策略：“earliest”将移至最旧的可用消息，“latest”将移至最新的消息。任何其他值都会引发异常。
• 默认值：'latest'。

16、enable_auto_commit(bool)

• 如果是True，消费者的偏移量将在后台定期提交。
• 默认值：True。

17、auto_commit_interval_ms(int)

• 如果enable_auto_commit为True，则自动偏移提交之间的毫秒数。
• 默认值：5000。

18、default_offset_commit_callback(callable)

• 作为callback(offsets, response)响应将是一个Exception或一个OffsetCommitResponse结构体。这个回调可以用于在提交请求完成时触发自定义操作。

19、check_crcs(bool)

• 自动检查消耗记录的CRC32。这确保不会发生消息的在线或磁盘损坏。这种检查会增加一些开销，因此在寻求极端性能的情况下可能会禁用它。
• 默认值：True

20、metadata_max_age_ms(int)

• 在这段时间(以毫秒为单位)之后，即使没有任何leader分区发生变化，也会强制刷新元数据，以主动发现任何新的代理或分区。
• 默认值:300000

21、partition_assignment_strategy(list)

• 使用组管理时用于在消费者实例之间分配分区所有权的对象列表。
• 默认值：[RangePartitionAssignor, RoundRobinPartitionAssignor]

22、max_poll_records(int)

• 一次调用poll()返回的最大记录数。
• 默认值:500

23、max_poll_interval_ms(int)

• 使用消费者组管理时，poll()调用之间的最大延迟。这就为消费者在获取更多记录之前可以空闲的时间设置了一个上限。如果在此超时到期之前未调用poll()，则认为消费者失败，组将重新平衡，以便将分区重新分配给另一个成员。
• 默认300000

24、session_timeout_ms(int)

• 当使用Kafka的组管理工具时，用于检测失败的超时时间。消费者定期向broker发送心跳以表明其活跃状态。如果在此会话超时到期之前代理没有接收到心跳，则代理将从组中删除该消费者并发起重新平衡。
• 注意，该值必须在group.min.session.timeout.ms和group.max.session.timeout.ms在代理配置中配置的允许范围内。
• 默认值:10000

25、heartbeat_interval_ms(int)

• 使用Kafka的组管理功能时，消费者协调器的心跳之间的预期时间（以毫秒为单位）。心跳用于确保消费者的会话保持活跃，并在新消费者加入或离开群组时促进重新平衡。该值必须小于session_timeout_ms，但一般不大于该值的1/3。它还可以调整得更低，以控制正常重新平衡的预期时间。
• 默认值:3000

26、receive_buffer_bytes(int)

• 读取数据时TCP接收缓冲区(SO_RCVBUF)的大小。默认值：None(依赖于系统默认值)。java客户机默认为32768。

27、send_buffer_bytes(int)

• 发送数据时使用的TCP发送缓冲区(SO_SNDBUF)的大小。默认值：None(依赖于系统默认值)。java客户机默认为131072。

28、socket_options(list)

• socket.setsockopt的元组参数列表，适用于代理连接套接字。
• 默认值：[(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)]

29、consumer_timeout_ms (int)

• 在引发StopIteration(即结束迭代器)之前，消息迭代期间要阻塞的毫秒数。
• 默认块永远 [float('inf')]。

30、security_protocol(str)

• 用于与代理通信的协议。有效值为：PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。
• 默认值：PLAINTEXT。

31、ssl_context(ssl.SSLContext)

• 用于包装套接字连接的预配置SSLContext。如果提供，所有其他ssl_*配置将被忽略。
• 默认值：None。

32、ssl_check_hostname(bool)

• 配置ssl握手是否应验证证书与代理主机名匹配的标志。
• 默认值：True。

33、ssl_cafile(str)

• 可选文件名，在证书验证中使用的ca文件。
• 默认值：None。

34、ssl_certfile(str)

• 可选文件名，包含客户端证书的pem格式文件，以及建立证书真实性所需的任何ca证书。
• 默认值：None。

35、ssl_keyfile(str)

• 可选文件名，包含客户端私钥的文件。
• 默认值：None。

36、ssl_password(str)

• 可选密码，加载证书链时使用。
• 默认值：None。

37、ssl_crlfile(str)

• 可选文件名，包含用于检查证书过期的CRL。缺省情况下，不进行CRL检查。在提供文件时，仅根据这个CRL检查叶证书。只能使用Python 3.4+或2.7.9+检查CRL。
• 默认值：None。

38、ssl_ciphers(str)

• 可以选择为SSL连接设置可用的密码。它应该是OpenSSL密码列表格式的字符串。如果不能选择密码(因为编译时选项或其他配置禁止使用所有指定的密码)，则会引发ssl.SSLError。见ssl.SSLContext.set_ciphers

39、api_version(tuple)

• 指定要使用的Kafka API版本。如果设置为None，客户端将尝试通过探测各种api来推断代理版本。不同的版本支持不同的功能。
• 默认值：None。

(0, 9)启用具有自动功能的完整组协调功能              #分区分配和重新平衡
(0, 8, 2)使用手动启用kafka-storage偏移提交        #仅分区分配，
(0, 8, 1) 手动启用 zookeeper-storage 偏移提交    #仅分区分配
(0, 8, 0)启用基本功能但需要手动                   #分区分配和偏移管理。

40、api_version_auto_timeout_ms(int)

• 在检查代理API版本时从构造函数抛出超时异常的毫秒数。仅当api_version设置为None时应用。

41、connections_max_idle_ms

• 在此配置指定的毫秒数之后关闭空闲连接。代理在connections.max.idle之后关闭空闲连接。这样可以避免在客户端碰到意想不到的套接字断开连接错误。
• 默认值：540000

42、metric_reporters(list)

• 用作指标报告者的类列表。实现AbstractMetricsReporter接口允许插入将被通知新指标创建的类。
• 默认：[]

43、metrics_num_samples(int)

• 为计算指标而维护的样本数。
• 默认值：2

44、metrics_sample_window_ms(int)

• 用于计算指标的样本的最大时间（以毫秒为单位）。
• 默认值：30000

45、selector(selectors.BaseSelector)

• 提供用于I/O多路复用的特定选择器实现。
• 默认值： selectors.DefaultSelector

46、exclude_internal_topics(bool)

• 是否应该向消费者公开来自内部主题（例如偏移量）的记录。如果设置为True，从内部主题接收记录的唯一方法是订阅它。需要 0.10+
• 默认值：True

47、sasl_mechanism(str)

• 为SASL_PLAINTEXT或SASL_SSL配置security_protocol时的身份验证机制。有效值为：PLAIN、GSSAPI、OAUTHBEARER、SCRAM-SHA-256、SCRAM-SHA-512。

48、sasl_plain_username(str)

• sasl PLAIN和SCRAM身份验证的用户名。如果sasl_mechanism是PLAIN或SCRAM机制之一，则为必需。

49、sasl_plain_password(str)

• sasl PLAIN和SCRAM身份验证的密码。如果sasl_mechanism是PLAIN或SCRAM机制之一，则为必需。

50、sasl_kerberos_service_name(str)

• 要包含在GSSAPI sasl机制握手中的服务名称。
• 默认值：‘kafka’

51、sasl_kerberos_domain_name(str)

• 在GSSAPI sasl机制握手中使用的kerberos域名。
• 默认值：引导服务器之一

52、sasl_oauth_token_provider(AbstractTokenProvider)

• OAuthBearer令牌提供程序实例。（参见 kafka.oauth.abstract）。
• 默认值：None

2、KafkaConsume类的方法

1、assign(partitions)

• 为消费者手动分配一个TopicPartitions列表。
• 此接口不支持增量分配，将替换以前的分配(如果有的话)。
• 通过此方法手动分配主题不使用消费者的组管理功能。因此，当组成员或集群和主题元数据发生变化时，不会触发重新平衡操作。
• 注意，不可能同时使用assign()的手动分区分配和subscribe()的组分配。

• partitions(list of TopicPartition)为这个实例赋值。

2、assignment()

• 获取当前分配给该消费者的TopicPartitions（主题分区）集合。
• 如果使用assign()直接分配分区，那么这将简单地返回先前分配的相同分区。如果使用subscribe()订阅主题，那么这将给出当前分配给使用者的主题分区集(如果还没有分配，或者分区正在重新分配，则可能为None)。

3、beginning_offsets(partitions)

• 获取给定分区的第一个偏移量。
• 此方法不会改变分区的当前使用者位置。
• 如果分区不存在，此方法可能会无限期阻塞。

• partitions(list)：要获取偏移量的TopicPartition实例列表。

4、bootstrap_connected()

• 如果引导程序已连接，则返回True。

5、close(autocommit=True)

• 关闭消费者，无限期地等待任何需要的清理。

• autocommit(bool)：如果为该消费者配置了自动提交，则此可选标志将导致该消费者在关闭之前尝试提交任何挂起的已使用偏移量。
• 默认值：True

6、commit(offsets=None)

• 提交偏移量到kafka，阻塞直到成功或错误。
• 它仅向Kafka提交偏移量。使用此API提交的偏移量将在每次重新平衡后的第一次获取和启动时使用。因此，如果你需要在Kafka以外的任何地方存储偏移量，则不应使用此API。为了避免在消费者重启时重新处理最后读取的消息，提交的偏移量应该是你的应用程序应该消费的下一个消息，即:last_offset + 1。
• 阻塞，直到提交成功或遇到不可恢复的错误(在这种情况下，它被抛出给调用者)。
• 目前只支持kafka-topic偏移存储(不支持zookeeper)。

• offsets(dict, optional)：使用配置的group_id提交的字典（{TopicPartition: OffsetAndMetadata} ）。默认为所有订阅分区当前使用的偏移量。

7、commit_async(offsets=None, callback=None)

• 异步提交偏移量给kafka，可以选择触发回调。
• 它仅向Kafka提交偏移量。使用此API提交的偏移量将在每次重新平衡后的第一次获取和启动时使用。因此，如果你需要在Kafka以外的任何地方存储偏移量，这个API不应该被使用。为了避免在消费者重启时重新处理最后读取的消息，提交的偏移量应该是你的应用程序应该消费的下一个消息，即:last_offset + 1。
• 这是一个异步调用，不会阻塞。遇到的任何错误要么被传递给回调函数(如果提供的话)，要么被丢弃。

• offsets(dict, optional)：使用配置的group_id提交的字典（{TopicPartition: OffsetAndMetadata} ）。默认为所有订阅分区当前使用的偏移量。
• callback(callable, optional)：作为callback(offsets, response)调用，响应为Exception或OffsetCommitResponse结构。此回调可用于在提交请求完成时触发自定义操作。

8、committed(partition, metadata=False)

• 获取给定分区的最后提交偏移量。
• 在发生故障时，这个偏移量将被用作消费者的位置。
• 如果有问题的分区没有分配给这个消费者，或者消费者还没有初始化其提交偏移量的缓存，这个调用可能会阻塞执行远程调用。

• partition(TopicPartition)：分区。
• metadata(bool, optional)：如果为True，则返回OffsetAndMetadata结构，而不是offset int。默认值：False。

• 返回值：最后提交的偏移量(int或OffsetAndMetadata)，如果之前没有提交，则为None。

9、end_offsets(partitions)

• 获取给定分区的最后偏移量。一个分区的最后偏移量就是即将到来的消息的偏移量，即最后一个可用消息的偏移量 + 1。
• 此方法不会改变分区的当前使用者位置。
• 如果分区不存在，此方法可能会无限期阻塞。

• partitions(list)：要获取偏移量的TopicPartition实例列表。

10、highwater(partition)

• 最后一次已知的highwater偏移量。
• highwater偏移量是将分配给产生的下一条消息的偏移量。通过与报告的位置进行比较，可能对计算滞后是有用的。注意，position和highwater都指向下一个偏移量，即highwater偏移量比最新的可用消息大1。
• highwater偏移量会在FetchResponse消息中返回，所以如果这个分区还没有发送fetchrequest，那么highwater偏移量将不可用。

• partition(TopicPartition)：要检查的分区
• 返回值：偏移（如果可用）

11、metrics(raw=False)

• 获取消费者性能指标。
• 注意：这是一个不稳定的方法。在未来的版本中，它可能会在没有任何警告的情况下发生变化。
• 这是从Java消费者中移植的，详细信息请参见:https://kafka.apache.org/documentation/#consumer_monitoring

12、offsets_for_times(timestamps)

• 根据时间戳查找给定分区的偏移量。每个分区返回的偏移量是时间戳大于或等于对应分区中给定时间戳的最早的偏移量。
• 这是一个阻塞调用。不必为消费者分配分区。
• 如果某个分区中的消息格式版本在0.10.0之前，即消息没有时间戳，则该分区将返回None。如果分区中没有消息，也将返回None。
• 如果分区不存在，此方法可能会无限期阻塞。

• timestamps(dict)：从分区映射到要查找的时间戳。单位应该是自纪元开始的毫秒数(午夜1970年1月1日(UTC))。字典{TopicPartition: int}

12、partitions_for_topic(topic)

• 此方法首先检查本地元数据缓存，以获取有关主题的信息。
• 如果没有找到主题(因为主题不存在、用户没有权限查看主题、或者元数据缓存没有填充)，那么它将向集群发出元数据更新调用。

• topic(str)：要检查的主题。

13、pause(*partitions)

• 暂停从请求的分区中获取数据。
• 以后调用poll()将不会从这些分区返回任何记录，直到使用resume()恢复它们 。
• 注意:此方法不会影响分区订阅。特别是，当使用自动分配时，它不会导致组重新平衡。

• *partitions(TopicPartition)：要暂停的分区

14、paused()

• 使用pause()获取以前暂停的分区。

15、poll(timeout_ms=0, max_records=None, update_offsets=True)

• 从指定的主题/分区获取数据。
• 通过主题分区批量获取和返回记录。在每次轮询中，消费者将尝试使用上次消费的偏移量作为起始偏移量并依次获取。最后消耗的偏移量可以通过seek()手动设置，也可以自动设置为订阅的分区列表的最后提交偏移量。
• 与迭代器接口不兼容--只能使用其中一个，不能同时使用两个。

• timeout_ms(int, optional)：如果缓冲区中没有数据，则轮询中等待的毫秒数。如果为0，则立即返回缓冲区中当前可用的任何记录，否则返回空。不能是负的。默认值:0
• max_records(int, optional)：一次调用poll()返回的最大记录数。默认值:从max_poll_records继承值。

16、position(partition)

• 获取将要获取的下一条记录的偏移量

• partition(TopicPartition)：要检查的分区

17、resume(*partitions)

• 从指定的（暂停的）分区恢复获取。

• *partitions(TopicPartition)：要恢复的分区。

18、seek(partition, offset)

• 手动指定TopicPartition的获取偏移量。
• 覆盖消费者将在下一次poll()中使用的获取偏移量。如果对同一个分区多次调用此API，则将在下一次poll()中使用最新的偏移量。
• 注意:如果在消费过程中任意使用这个API来重置获取偏移量，您可能会丢失数据。

• partition(TopicPartition)：用于查找操作的分区
• offset(int)：分区中的消息偏移量

19、seek_to_beginning(*partitions)

• 为分区寻找最旧的可用偏移量。

• *partitions：可以选择提供特定的TopicPartitions，否则默认为所有分配的分区。

20、seek_to_end(*partitions)

• 查找分区的最新可用偏移量。

• *partitions：可以选择提供特定的TopicPartitions，否则默认为所有分配的分区。

21、subscribe(topics=(), pattern=None, listener=None)

• 订阅主题列表或主题正则表达式模式。
• 分区将通过组协调器动态分配。主题订阅不是增量的：此列表将替换当前的赋值(如果有)。
• 此方法与assign()不兼容。

• topics(list)：订阅的主题列表。
• pattern(str)：模式来匹配可用的主题。必须提供主题或模式，但不能两者都提供。
• listener(ConsumerRebalanceListener)：可选地包括监听器回调，它将在每次重新平衡操作之前和之后被调用。
  • 作为组管理的一部分，消费者将跟踪属于特定组的消费者列表，并在以下事件之一触发时触发重新平衡操作：
    • 任何订阅主题的分区数发生变化
    • 创建或删除主题
    • 消费者组的现有成员死亡
    • 一个新成员被添加到消费者组
  • 当这些事件中的任何一个被触发时，提供的侦听器将首先被调用以指示消费者的分配已被撤销，然后在收到新分配时再次调用。请注意，此侦听器将立即覆盖在先前的subscribe调用中设置的任何侦听器。但是，可以保证通过此接口撤销/分配的分区来自在此调用中订阅的主题。

22、subscription()

• 获取当前主题订阅。

23、topics()

• 获取用户有权查看的所有主题。这将始终向集群发出远程调用以获取最新的信息。

24、unsubscribe()

• 取消订阅所有主题并清除所有分配的分区。

2、消费者客户端

1

#                                                                                                                     #