Singer 源

描述

Singer 源让 PlaidCloud 能够使用 Singer tap 从种类繁多的 SaaS 应用、API 和数据库（例如 Stripe、GitHub、Slack 和 BigQuery）中提取数据。每个 tap 是针对一个源的连接器；创建连接时选择 tap，PlaidCloud 会显示该 tap 所需的配置字段。

使用 Singer 源分为两部分：

Singer 源连接保存 tap 的选择及其设置（API 令牌、账户 ID、开始日期等）。
Import Singer Source 工作流步骤会发现 tap 可用的流，让您选择要导入哪些流以及每个流落入何处，并运行提取。

Singer 源连接保存 tap 及其设置；Import Singer Source 步骤发现该 tap 的流，并将您选择的流落入项目表。

开始之前

您需要源系统的凭据（例如 GitHub 个人访问令牌或 Stripe API 密钥），以及要让数据落入的项目和工作流。

创建 Singer 源连接

打开 Tools > Connections。
点击新建连接并选择 Singer 源。
为连接指定名称（例如 GitHub (prod)）。
从下拉列表中选择一个 Tap。下方的表单会重新构建，以显示该 tap 的字段。完整目录以及各源配置文档的链接，请参见 Singer 源。
填写 tap 的配置字段，然后点击创建。

配置字段类型

字段取决于 tap，每个字段都会按 tap 所期望的值来呈现：

文本：单行值（例如账户 ID 或开始日期）。
密码：API 令牌或密钥等机密信息。机密信息是只写的：编辑连接时不会显示，保存时留空则保留已存储的值。
编号：整数或小数（例如端口或页面大小）。
列表：每行一个条目（例如存储库列表或项目 ID 列表）。
JSON：以 JSON 形式输入的结构化值，用于 tap 需要对象或对象数组的情况。例如 CSV tap 的文件定义：
```
[
  { "entity": "orders", "path": "/data/orders.csv", "keys": ["id"] }
]
```
复选框：开/关选项。

必填字段会有标记，表单在保存之前会对其进行验证（包括 JSON 和数字字段的格式是否正确）。

将流导入工作流

打开工作流，转到 Analyze Steps 选项卡。
添加一个步骤，并选择 导入：Singer 源作为类型。编辑器会打开，其中包含源选项卡和流选项卡。
在源选项卡上：
- 选择连接（您的 Singer 源连接）。
- 选择同步模式：整表（每次运行替换）、增量（追加新数据）或更新插入（按键合并）。
- 点击发现流。发现操作在运行器上执行，首次可能需要大约三分钟；状态会显示找到了多少个流。
在流选项卡上，每个已发现的流对应一行。对于要导入的每个流：
- 打开其流面板并勾选导入此流。
- 选择目标表，指定该流的数据落入何处。
- 如果同步模式为 Upsert，请设置该流的关键列，每行一个列名。该字段默认为 tap 声明的主键；可以覆盖它，以按不同的列合并。当模式为 Upsert 时，每个导入的流至少需要一个关键列。
保存该步骤，并将其作为工作流的一部分运行（或单独运行）。

同步模式

整表（每次运行替换） 每次运行都会重新提取整个流并替换目标表。适用于较小或完全刷新的源。
增量（追加新数据） 仅提取自上次运行以来的新行并将其追加，从上一次运行停止的位置继续。它仅适用于 tap 能够增量同步的流，即公开了复制键（例如更新时间戳或递增 ID）的流。如果选择增量而所选的某个流没有复制键，步骤会要求您将该流切换为整表或取消选择。
更新插入（按键合并） 每次运行都会重新提取整个流，然后按该流的关键列合并到目标中：键与现有行匹配的行会就地更新，具有新键的行则会插入。不在本次运行中的现有行会被保留。可用它让表与记录会随时间变化的源保持同步，既不会出现追加所造成的重复，也无需替换所带来的完全重建。目标表在首次运行时创建，因此初次 upsert 会插入每一行。

凭据的处理方式

步骤存储的是对连接的引用，而不是其凭据的副本。每次运行都会在运行时读取连接的当前凭据。因此，轮换令牌或密钥时，只需在连接上更新一次，所有使用它的步骤都会在下次运行时获取新值，无需更新各个步骤。

提取在隔离的作业中运行，该作业仅接收 tap 自身的配置；它无法访问其他连接或 PlaidCloud 的内部服务。