Singer 学习十二 指南

版本0.3.0
tap是一个应用程序，需要一个配置文件和可选的状态文件作为输入，并产生有序的流记录， 状态和模式信息作为输出。
一个记录是任何类型的JSON编码的数据。tap 状态消息用于保留一个调用之间的信息。一个模式消息描述stream 中的
数据类型。Tap可以用任何编程语言实现。
tap设计用于从数据库和Web服务API等源生成数据流，以用于数据集成或ETL管道。

概要

 

tap --config CONFIG [--state STATE] [--catalog CATALOG]

CONFIG is a required argument that points to a JSON file containing any

configuration parameters the Tap needs.

​

STATE is an optional argument pointing to a JSON file that the

Tap can use to remember information from the previous invocation,

like, for example, the point where it left off.

​

CATALOG is an optional argument pointing to a JSON file that the

Tap can use to filter which streams should be synced.

输入

配置

配置包含Tap需要的任何参数，以便从源中提取数据。通常，这将包括API或数据源的凭据。配置的格式因Tap而异，
但必须采用JSON编码，配置的根必须是对象。
对于需要在运行期间更改配置的tap，tap应将更改写回提供的配置文件，以便可以在后续运行中使用更改。

state

JSON编码状态用于在Tap的调用之间保持信息。
希望持久状态的Tap应该在处理流时定期将STATE消息写入stdout，并且应该期望--state STATE参数命名的文件具有与它发出
的STATE消息的值相同的格式。
状态的一个常见用例是在最后一次调用中断的流中记录该点。如果在没有--state STATE 参数的情况下调用Tap ，它应该从流的
开头或某个适当的默认位置开始。如果使用--state STATE 参数调用它，它应该在状态文件中读取并从流中的相应位置开始。

catalog

catalog 是一个JSON编码文件，列出了可用的stream及其schema。顶级是一个对象，其中一个名为streams的键指向一个流对象数组。
可以修改每个流对象的元数据，以选择是否应复制流和/或其字段，以及应如何复制数据（FULL TABLE与INCREMENTAL）。

示例调用

从头开始同步，无catalog

 

$ tap --config config.json

 

从存储状态开始与目录同步

$ tap --config config.json --state state.json --catalog catalog.json

输出

Tap以 stdout JSON格式输出结构化消息，每行一条消息。可以发出日志和其他信息以stderr 帮助调试。
流式传输器在成功时以退出代码退出，在失败时退出非零。
正文包含编码为JSON映射的消息，每行一条消息。每条消息都必须包含一个type属性。type 允许任何消息，
并且types被解释为不区分大小写。以下types具有特定含义：

record 消息

RECORD消息包含数据流中的数据。它们必须具有以下属性：
record 必填。包含流数据点的JSON映射
stream 必填。流的字符串名称
time_extracted 可选。在源中观察此记录的时间。这应该是 RFC3339格式的日期时间，如“2017-11-20T16：45：33.000Z”。
单个Tap可以输出具有不同流名称的RECORD消息。单个RECORD条目可能只包含单个流的记录。
例：
注意：每条消息必须在它们自己的行上，但这里的示例使用多行来提高可读性。

 

 {

  "type": "RECORD",

  "stream": "users",

  "time_extracted": "2017-11-20T16:45:33.000Z",

  "record": {

    "id": 0,

    "name": "Chris"

  }

}

 

SCHEMA消息

SCHEMA消息描述流中数据的数据类型。它们必须具有以下属性：

schema 必填。一个JSON模式，用于描述data RECORD 的 属性stream

stream 必填。此架构描述的流的字符串名称

key_properties 必填。一个字符串列表，指示哪些属性构成此流的主键。列表中的每个项目都必须是架构中定义的顶级属性的名称。key_properties必须提供值，但它可能是一个空列表，表示没有主键。

bookmark_properties 可选。一个字符串列表，指示抽头用作书签的属性。列表中的每个项目都必须是架构中定义的顶级属性的名称。

单个Tap可以输出具有不同流名称的SCHEMA消息。如果来自流的RECORD消息之前没有SCHEMA该流的 消息，则假定它是无模式的。

例：

注意：每条消息必须在它们自己的行上，但这里的示例使用多行来提高可读性。

{

  "type": "SCHEMA",

  "stream": "users",

  "schema": {

    "properties": {

      "id": {

        "type": "integer"

      },

      "name": {

        "type": "string"

      },

      "updated_at": {

        "type": "string",

        "format": "date-time"

      }

    }

  },

  "key_properties": ["id"],

  "bookmark_properties": ["updated_at"]

}

 

state 消息

STATE消息包含Tap希望保留的状态。STATE消息具有以下属性：
value 必填。JSON格式的状态值
STATE值的语义不是规范的一部分，应由每个Tap独立确定。
例

 

{"type": "SCHEMA", "stream": "users", "key_properties": ["id"], "schema": {"required": ["id"], "type": "object", "properties": {"id": {"type": "integer"}}}}

{"type": "RECORD", "stream": "users", "record": {"id": 1, "name": "Chris"}}

{"type": "RECORD", "stream": "users", "record": {"id": 2, "name": "Mike"}}

{"type": "SCHEMA", "stream": "locations", "key_properties": ["id"], "schema": {"required": ["id"], "type": "object", "properties": {"id": {"type": "integer"}}}}

{"type": "RECORD", "stream": "locations", "record": {"id": 1, "name": "Philadelphia"}}

{"type": "STATE", "value": {"users": 2, "locations": 1}}

 

版本

Tap的API包含其输入和输出 - 包括其配置，它如何解释状态，以及它产生的数据是如何结构化和解释的。点击应该遵循 语义版本控制，这意味着对其中任何一个的更改应该是新的MAJOR版本，并且向后兼容的更改应该是新的MINOR版本。

参考资料

https://github.com/singer-io/getting-started/blob/master/docs/SPEC.md