ProtobufReader

ProtobufReader Controller Service 从二进制格式读取并解析 Protocol Buffers Message，并创建 Record 对象。该 Controller Service 必须配置与消息编码时使用的相同 '.proto' 文件，以及包含包名的消息类型全限定名（例如 mypackage.MyMessage）。该 Reader 始终从输入数据生成一条记录，表示所提供的 Protocol Buffers Message 类型。关于 Protocol Buffers 的更多信息参见：protobuf.dev

数据类型映射

从传入数据解析记录时，该 Controller Service 会把 Proto Message 字段类型映射到对应的 Lynxus 数据类型。所提供的 Message 字段与编码输入之间的映射始终基于字段标签号。当字段定义为 'repeated' 时，其数据类型是原指定类型的数组。下表展示了转换后 proto 字段类型与 Lynxus 字段类型的对应关系。

标量值类型

复合值类型

Schema 与类型强制转换

从传入数据解析记录时，记录会被拆分为字段。每个字段会按字段名 在配置的 schema 中查找，以确定数据的类型。如果字段不在 schema 中，该字段会以其原始类型存储在 Record 的值列表中。如果字段在 schema 中，接收到的数据类型会与 schema 指定的数据类型比较。如果类型匹配，字段值直接使用。如果 schema 表明字段应为不同类型，该 Controller Service 会尝试把数据强制转换为 schema 指定的类型。如果字段无法强制转换为指定类型，会抛出异常。

尝试把字段值从一种数据类型强制转换为另一种时，适用以下规则：

• 任何数据类型都可以强制转换为 String 类型。
• 任何数值数据类型（Int、Long、Float、Double）都可以强制转换为 其他任何数值数据类型。
• 任何数值都可以强制转换为 Date、Time 或 Timestamp 类型，前提是把 Long 值视为自纪元（1970 年 1 月 1 日 GMT 午夜）以来的毫秒数。
• 如果 String 值的格式匹配配置的 "Date Format"、"Time Format" 或 "Timestamp Format"，它可以强制转换为 Date、Time 或 Timestamp 类型。
• 如果值是合适的类型，String 值可以强制转换为数值。例如，String 值 8 可以强制转换为任何数值类型。但 String 值 8.2 可以强制转换为 Double 或 Float 类型，不能转换为 Integer。
• "true" 或 "false"（不区分大小写）的 String 值可以强制转换为 Boolean 值。
• 非空的 String 值可以强制转换为 Char 类型。如果 String 包含多个字符，使用第一个字符，其余字符被忽略。

尝试把值从一种数据类型强制转换为另一种时，如果上述规则都不适用， 强制转换会失败并抛出异常。

Schema 访问策略

除了从属性值获取 schema 或从 Schema Registry 访问等常见的 Schema 访问策略，ProtobufReader Controller Service 还提供另一种名为 "Generate from Proto file" 的访问策略。使用该策略时，Reader 会从所提供的 '.proto' 文件和 Message 类型生成 Record Schema。当用户不想手动创建 schema 或不需要类型强制转换时，推荐使用该策略。

Protobuf Any 字段类型

Protocol Buffers 提供了称为 Well-Known Types 的更多 Message 类型。这些是额外提供的消息，定义了复杂的结构类型和标量类型的 包装器。Any 类型是这些 Well-Known Types 之一，用于存储任意序列化的 Message 以及描述该序列化 Message 类型的 URL。由于 Message 类型和嵌入的 Message 只有在 Any Message 已填充数据时才可用，ProtobufReader 需要在数据转换时进行该 Message 处理。该 Reader 能够为 Any 字段中嵌入的 Message 生成 schema，并在结果 Record schema 中替换它。

示例

有一个名为 'TestMessage' 的 Message，只有一个 Any 类型的字段。另有一个名为 'NestedMessage' 的 Message，我们想把它作为序列化 Message 添加到 'anyField' 的值中。

message Any {
    string type_url = 1;
    bytes value = 2; 
}

message TestMessage {
    google.protobuf.Any anyField = 3; 
}

message NestedMessage {
    string field_1 = 1;
    string field_2 = 2;     
    string field_3 = 3;
}

``

普通数据转换下，结果如下：

{
  anyField: {
    type_url: "type.googleapis.com/NestedMessage"
    value: [
      84,
      101,
      115,
      116,
      32,
      98,
      121,
      116,
      101,
      115
    ]
  }
}

Protobuf Reader 用处理后的嵌入 Message 替换 Any Message 字段后的结果：

{
  anyField: {
    field_1: "value 1",
    field_2: "value 2",
    field_3: "value 3"
  }
}