订阅 Kafka 主题以获取 JSON

“订阅 Kafka 主题以获取 JSON”输入连接器可用于从 Kafka 主题检索和改编通用 JSON 形式的事件数据记录。 有关 Apache Kafka 入门知识的详细信息，请参阅 Apache Kafka 简介。

用法说明

使用“订阅 Kafka 主题以获取 JSON”输入连接器时，应记住以下事项：

• 使用此输入连接器可以使用 Kafka 主题中的 JSON 数据。 此输入连接器是 Kafka 的用户。
• 此输入连接器将通用 JSON 入站适配器与 Kafka 入站传输配对。
• 适配器将对通用 JSON（而不是要素 JSON 或 GeoJSON）进行解释。
• 通用 JSON 记录无需包含表示几何的数据。
• 适配器将对组织在一个数组中的单个 JSON 记录和 JSON 记录进行处理。
• 适配器支持根据 x、y 和 z 属性值构造点几何的功能。
• 此输入连接器包括学习模式参数，您可以使用此参数允许输入连接器修改其构造的 GeoEvent 定义。 此参数的目的是暂时接受所接收的事件数据将具有变量方案或数据结构。 输入连接器将使用所接收数据记录的样本来了解有关变量数据结构的详细信息，并将先前未发现的新属性字段追加到现有 GeoEvent 定义中。
• 允许动态更改 GeoEvent 定义会对 GeoEvent 服务中的实时分析设计产生负面影响。 最佳做法是，如果入站事件数据中预期存在方案差异，建议您在尽可能短的时间内使用学习模式，以生成支持入站数据所有预期变体的 GeoEvent 定义。 然后，可以关闭学习模式，自动生成的 GeoEvent 定义将进行复制和定制以用于生产部署。
• Kafka 入站传输支持 TLS 1.2 和 SASL 安全协议，其使用 Kafka 集群或 broker 进行身份验证。

参数

以下是“订阅 Kafka 主题以获取 JSON”输入连接器的参数：

参数	描述
名称	用于在 GeoEvent Manager 中引用的输入连接器的描述性名称。
使用自定义 Kafka 属性覆盖	指定是否覆盖默认 GeoEvent Server Kafka 客户端属性。 默认为否。 是 - 将覆盖传输公开的默认 Kafka 客户端属性。 为实现有效 Kafka 配置，必须指定一个注册到 GeoEvent Server 的文件夹，其中需包含具有正确格式的 Kafka .properties 文件。 有关支持的配置和指定 .properties 文件的预期格式的列表，请参阅 Apache Kafka 配置。 否 - 不会覆盖传输公开的默认 Kafka 客户端属性。 必须指定 Kafka 引导服务器和用户群组 ID。
Kafka Bootstrap Servers （条件分析）	用于建立与 hostname:port 集群初始连接的 Kafka 对列表。 Hostname:port 对必须使用逗号分隔，例如broker0.example.com:9092,broker1.example.com:9092,broker2.example.com:9092。 此参数将在使用自定义 Kafka 属性覆盖设置为否时显示。
主题名称	Kafka 主题的名称或 Kafka 主题列表，用于使用感兴趣的数据。 多个主题必须使用分号分隔。 topic1 topic1;topic2;topic3;topic4 注： 在 Kafka 10.8 及更高版本中可以指定多个 ArcGIS GeoEvent Server 主题。
用户数量	指定每个用户群组的用户数量。 默认用户数量为 1。 注： 用户数量受 Kafka 主题的分区数量限制。 有关用户实例的详细信息，请参阅 Apache Kafka 简介。
用户群组 ID （条件分析）	可选字符串，用于唯一标识一组用户的用户群组。 此参数也称为用户群组名称。 如果未指定用户组 ID，GeoEvent Server 会分配一个名为 geoevent-consumer 的静态用户组 ID。 此静态用户组 ID 将在所有未指定用户组 ID 的 Kafka 连接器实例之间共享。 强烈建议您指定自定义用户群组 ID。 有关用户群组的详细信息，请参阅 Apache Kafka 简介。 此参数将在使用自定义 Kafka 属性覆盖设置为否时显示。
Kafka 属性文件的已注册文件夹 （条件分析）	使用 GeoEvent Server 注册的文件夹，其中包含 Kafka .properties 文件。 当使用自定义 Kafka 属性覆盖设置为是时，Kafka .properties 文件将定义自定义 Kafka 属性。 确保使用 GeoEvent Server 注册的文件夹为 Kafka .properties 文件所在位置的完整路径。 此参数将在使用自定义 Kafka 属性覆盖设置为是时显示。
Kafka 属性文件名称 （条件分析）	Kafka .properties 文件的名称，该文件包含用于客户端配置的自定义 Kafka 属性。 指定的文件名称不应包含 .properties 扩展名。 如果自定义 Kafka 属性文件的名称是 sample.properties，则将此参数指定为 sample。 此参数将在使用自定义 Kafka 属性覆盖设置为是时显示。
从头开始	指定是从主题的开始偏移还是从用户的上次偏移开始使用记录。 默认为是。 是 - 从主题开始偏移时开始使用记录。 否 - 从用户的上次偏移开始使用记录。 注： 有关偏移的详细信息，请参阅 Apache Kafka 配置。
JSON 对象名称	JSON 元素的名称，可用作接收的 JSON 数据中子结构的根结点。 当 JSON 对象名称用于按名称指定 JSON 元素时，适配器将搜索对象名称与指定元素名称匹配的子结构。 仅考虑所识别的子结构内的数据。 如果保留为空（默认值），则最上面的 JSON 对象将用作整个 JSON 结构的根。
创建 GeoEvent 定义	指定是否应将新的或现有的 GeoEvent 定义用于入站事件数据。 GeoEvent Server 需要 GeoEvent 定义，以了解入站事件数据属性字段和数据类型。 是 - 将根据收到的第一个事件记录的模式创建新的 GeoEvent 定义。 否 - 不会创建新的 GeoEvent 定义。 选择与入站事件数据的方案匹配的现有 GeoEvent 定义。
GeoEvent 定义名称(新) （条件分析）	分配给新 GeoEvent 定义的名称。 如果已存在具有指定名称的 GeoEvent 定义，则会使用现有的 GeoEvent 定义。 收到的第一个数据记录将用于确定后续数据记录的预期方案，将根据第一个数据记录的方案创建新的 GeoEvent 定义。 此参数在创建 GeoEvent 定义设置为是时显示，设置为否时隐藏。
GeoEvent 定义名称(现有) （条件分析）	在调整接收数据以创建事件数据以供 GeoEvent 服务处理时使用的现有 GeoEvent 定义的名称。 此参数在创建 GeoEvent 定义设置为否时显示，设置为是时隐藏。
从字段构建几何	指定输入连接器是否应使用作为属性接收的坐标值构造点几何。 默认为否。 是 - 来自指定事件属性字段的值将用于构造点几何。 否 - 不会构造点几何。 假定属性字段包含可以解释为几何的值，或者事件记录为非空间记录（不具有几何）。
X 几何字段 （条件分析）	入站事件数据中包含点位置 x 坐标部分（例如水平或经度）的属性字段。 此参数在从字段构建几何设置为是时显示，设置为否时隐藏。
Y 几何字段 （条件分析）	入站事件数据中包含点位置 y 坐标部分（例如垂直或纬度）的属性字段。 此参数在从字段构建几何设置为是时显示，设置为否时隐藏。
Z 几何字段 （条件分析）	入站事件数据中包含点位置 z 坐标部分（例如深度或高度）的字段的名称。 如果留空，则将省略 z 值，并将构建 2D 点几何。 此参数在从字段构建几何设置为是时显示，设置为否时隐藏。
学习模式	指定学习模式为活动还是禁用状态。 学习模式设置为是时，入站适配器会将新字段追加到其已创建和正在维护的 GeoEvent 定义中。 是 - 将启用学习模式。 将使用共享不同方案的事件记录中的新字段更新 GeoEvent 定义。 否 - 不会启用学习模式。 不会修改 GeoEvent 定义。 当您需要允许输入连接器修改它构建的 GeoEvent 定义时，学习模式会很有用。 此参数的目的是暂时接受所接收的事件数据将具有变量方案或数据结构。 输入连接器将使用所接收数据记录的样本来了解有关变量数据结构的详细信息，并将先前未发现的新属性字段追加到现有 GeoEvent 定义中。 允许在运行中更改 GeoEvent 定义会对 GeoEvent 服务中的实时分析设计产生负面影响。 如果入站事件数据中预期存在方案差异，建议您在尽可能短的时间内使用学习模式，以生成支持入站数据所有预期变体的 GeoEvent 定义。 然后，可以关闭学习模式并为生产部署复制和定制自动生成的 GeoEvent 定义。
默认空间参考	当从坐标不是假定的 WGS84 地理坐标系的纬度和经度值的属性字段值构造几何时使用的空间参考的熟知 ID (WKID)，或接收的不包含空间参考的几何字符串。 还可以指定熟知文本 (WKT) 值或包含 WKID 或 WKT 的属性字段的名称。
预期日期格式	该模式用于匹配日期/时间值的预期字符串表示形式，并将它们转换为 Java 日期值。 模式的格式遵循 Java SimpleDateFormat 类约定。 而 GeoEvent Server 更偏好以 ISO 8601 标准表示的日期/时间值，通常被识别为日期值的日期/时间值的多个字符串表示可以转换为 Java 日期值，且无需指定预期日期格式模式。 其中包括： “2019-12-31T23:59:59”- ISO 8601 标准格式 1577836799000 - Java 日期（时间长整型；UTC） “Tue Dec 31 23:59:59 -0000 2019”- 常见的 web 服务字符串格式 “12/31/2019 11:59:59 PM”- 美国使用的通用格式（12 小时制） “12/31/2019 23:59:59”- 美国使用的通用格式（24 小时制） 如果收到的日期/时间值使用并非上述五种之一的约定表示，则必须指定一个预期日期格式模式以便 GeoEvent Server 了解如何调整日期/时间值。
作为 GeoJSON	指定是否将传入的几何解析为 GeoJSON 几何对象而不是要素 JSON。 默认情况下假设当一个几何作为字符串接收时，该值将是要素 JSON，正如几何对象中所述。 是 - 传入的几何将被解析为 GeoJSON 而不是要素 JSON。 否 - 假定几何的所接收字符串表示为要素 JSON。
需要身份验证	指示连接到 Kafka 集群（或 Kafka broker）是否需要身份验证。 默认为否。 是 - Kafka 集群或 broker 需要身份验证。 否 - 连接到 Kafka 集群或 broker 不需要身份验证。
身份验证方式 （条件分析）	指定用于保护 Kafka 集群的安全协议。 可用安全协议包括 TLS 1.2 和 SASL。 TLS 1.2 - Kafka 集群使用的安全协议是 TLS 1.2。 确保将 Kafka 群集的 PKI 文件（x509 证书）导入到 ArcGIS Server 的信任存储中，此信任存储将用于配置 ArcGIS GeoEvent Server。 有关导入证书具体说明的详细信息，请参阅使用现有的 CA 签名证书配置 ArcGIS Server 中的将证书导入 ArcGIS Server 部分。 SASL - Kafka 集群使用的安全协议是 SASL。 仅支持 SASL、SSL 和 Kerberos。 注： 在使用 Kerberos 时，请确保运行 ArcGIS GeoEvent Server 的操作系统用户账户具有 Kerberos 设置和配置中密钥表文件的读取权限。 此参数在需要身份验证设置为是时显示。
凭据文件的已注册文件夹 （条件分析）	使用 GeoEvent Server 注册的文件夹中包含 Kafka 集群的 PKI 文件（x509 证书）。 确保使用 GeoEvent Server 注册的文件夹为 Kafka 集群证书所在位置的完整路径。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 TLS 1.2。
凭据配置文件 （条件分析）	Kafka 集群 PKI 文件的名称（x509 证书）。 必须以 PKCS#12 格式存储此证书及其关联私钥，表示为具有 .p12 或 .pfx 扩展名的文件。 请输入文件名和扩展名。 my_kafka_certificate.pfx my_other_kafka_certificate.p12 注： 此参数仅支持证书文件名称和扩展名。 证书的相对路径不应在此参数中指定。 使用凭据文件的已注册文件夹参数注册证书文件的完整路径。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 TLS 1.2。
Keystore 密码 （条件分析）	Kafka 集群 PKI 文件的密码（x509 证书）。 也称为证书的私钥。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 TLS 1.2。
SASL 身份验证类型 （条件分析）	指定 Kafka 集群支持的 SASL 身份验证机制类型。 可用 SASL 身份验证类型包括 SASL GSSAPI (Kerberos) 和 SASL PLAIN。 SASL/GSSAPI (Kerberos) - Kafka 集群将使用 SASL/GSSAPI Kerberos 身份验证。 SASL/PLAIN - Kafka 集群将使用 SASL/PLAIN 身份验证。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 SASL。
Kerberos 主体 （条件分析）	特定用户的 kerberos 主体，例如 [e-mail]。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 SASL/GSSAPI (Kerberos)。
使用密钥表 （条件分析）	指示是否在 Kerberos 设置中使用密钥表。 默认为是。 是 - 将在 Kerberos 设置中使用密钥表。 否 - 不会在 Kerberos 设置中使用密钥表。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 SASL/GSSAPI (Kerberos)。
存储密钥 （条件分析）	指示是否在 Kerberos 设置中存储密钥。 默认为是。 是 - 密钥将存储在 Kerberos 设置中。 否 - 密钥不会存储在 Kerberos 设置中。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 SASL/GSSAPI (Kerberos)。
用户名 （条件分析）	指定用于使用 Kafka 集群进行身份验证的用户名。 也称为与某些云提供商的连接字符串。 有关正确的语法，请参阅所选云提供商的文档。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 SASL/PLAIN。
密码 （条件分析）	指定用于使用 Kafka 集群进行身份验证的密码。 有关正确的语法，请参阅所选云提供商的文档。 此参数在需要身份验证设置为是时显示。 此参数仅适用于 SASL/PLAIN。

注意事项和限制

使用“订阅 Kafka 主题以获取 JSON”输入连接器时，需要牢记几点注意事项：

• 对用户的管理和优化不足会导致“订阅 Kafka 主题以获取 JSON”输入连接器的某些实例无法检索数据。 用户组中的用户数量受到 Kafka 主题分区数量的限制。 如果用户组中的用户数量超过 Kafka 主题的可用分区数量，则超出的用户将无法使用数据。 为避免发生上述情况，需考虑对用户数量进行优化，使其最好与 Kafka 主题的分区数量保持一致，或者为每个连接器实施不同的用户组。 有关用户和用户组的详细信息，请参阅 Kafka 文档。
• “订阅 Kafka 主题以获取 JSON”输入连接器是 Kafka 的客户端用户。 此输入连接器适用的注意事项与 Kafka 的任何其他客户端用户的注意事项相同。 例如，如果此输入连接器未从 Kafka 主题接收数据，但是 Kafka 的独立客户端用户从中接收数据，则需考虑拥有两个客户端用户所涉及的因素。 这包括但不限于配置的用户组 ID、主题上可用的分区数量以及现有用户的数量。 或者，如果输入连接器快速连续地停止或启动，请从用户角度考虑对 Kafka 产生的影响。 重新平衡 Kafka 主题的分区可能会使输入连接器无法立即作为同一用户组下的用户重新加入。