setting-up-a-custom-rest-source

设置自定义 REST 数据源

自定义数据源通过 JSON 清单将任意 HTTP REST API 导入可查询的数据仓库表中——无需为每个数据源编写 Python。清单是一个 RESTAPIConfig：其结构与 PostHog 内置 REST 连接器（Intercom、Attio、Sentry 等）使用的相同，因此通用 REST 引擎会为你处理身份验证、分页、JSONPath 记录提取和增量游标。你需要编写正确的清单，并在创建数据源前用实时数据验证它。

此功能处于 beta 阶段。限制：每份清单最多包含 50 个资源，每个项目最多创建 5 个自定义数据源。

何时使用此技能

• 用户想要导入一个没有内置连接器的 API——例如内部服务、小众 SaaS 或公共 API——并且能提供文档 URL 或描述其端点。
• 用户明确要求“自定义 REST 数据源”“自定义数据源清单”或“根据文档构建连接器”。

自定义数据源是后备方案——只有没有合适的原生连接器时才应使用。PostHog 提供了数百个原生连接器，数量远超此处能列出的范围，因此绝不要假定某个 API 没有内置连接器——大多数知名 SaaS 应用和数据库都有。猜错会导致你为其编写手动清单，重复实现经过充分验证的连接器。以下的步骤 0 会要求你在起草任何内容前检查注册表；如果存在匹配的原生连接器，请改用 setting-up-a-data-warehouse-source。

语法

起草前请阅读 references/manifest-reference.md——其中完整介绍了 RESTAPIConfig 字段（身份验证类型、六种分页器、增量游标、父子扇出），并为每种情况提供了完整示例。请根据该语法起草清单；不要猜测字段名称。

基本结构：

{
  "client": {
    "base_url": "https://api.example.com/v1",
    "auth": { "type": "bearer" }
  },
  "resources": [
    {
      "name": "users",
      "primary_key": "id",
      "endpoint": {
        "path": "/users",
        "data_selector": "data",
        "paginator": { "type": "json_response", "next_url_path": "next" },
        "incremental": { "cursor_path": "updated_at", "start_param": "since" }
      }
    }
  ]
}

绝不要将密钥直接写入清单。 manifest_json 仅保存非机密结构。凭据通过单独的载荷键传递，该键由清单中的 client.auth.type 决定：bearer 使用 auth_token，api_key 使用 auth_api_key，http_basic 使用 auth_password，oauth2 使用 auth_oauth2_client_secret（仅刷新令牌授权类型还需提供 auth_oauth2_refresh_token）。引擎会在运行时注入凭据，PostHog 会从所有响应中将其隐去。验证时会拒绝直接写入令牌。

可用工具

工具	用途
external-data-sources-wizard	列出 PostHog 支持的所有原生来源类型。起草清单前，先运行此工具（步骤 0），检查目标 API 是否已有内置连接器。
external-data-sources-db-schema	验证清单和凭据，并列出其公开的资源（表），以及检测到的主键和增量游标。这是验证并列出资源的步骤。
external-data-sources-preview-resource	读取某个资源的一小部分实时行数据——在创建任何内容之前，根据真实数据验证 data_selector / primary_key / cursor_path。
data-warehouse-source-setup	创建来源。一次调用即可启用清单中的所有资源，并使用同步默认设置。
external-data-sources-create	高级创建方式——允许用户通过 schemas 数组手动选择要同步的资源。
external-data-schemas-list	创建后，查看各表的同步状态。

工作流

步骤 0 — 先检查是否有原生连接器

起草任何内容之前，调用 external-data-sources-wizard 列出原生来源类型，并通过匹配服务名称检查目标 API 是否在其中。对于没有原生连接器的 API，才使用 Custom 来源作为后备方案；不要假设知名 API 不受支持而跳过此检查——大多数 API 都受支持。

如果匹配到原生连接器，请停止并告知用户：内置方案更简单且经过实战验证（它会为用户处理身份验证、分页、架构和增量同步），并将用户交接给 setting-up-a-data-warehouse-source。只有在用户没有匹配的原生连接器，或明确想使用自定义 REST 方案（即使已有原生连接器）的情况下，才继续使用此技能。

步骤 1 — 收集 API 信息

获取文档 URL（访问并阅读其中的身份验证方案、列表端点、响应封装格式以及分页方式），或获取对端点的自然语言描述。对于要导入的每个资源，你需要了解：

• 路径（相对于通用 base_url）和方法（GET，或用于查询式读取端点的 POST）；
• 身份验证方案（Bearer 令牌 / 请求头或查询参数中的 API 密钥 / HTTP 基本身份验证 / 使用客户自有客户端的 OAuth2——client_credentials 或预先获取的刷新令牌；不支持交互式 authorization_code 流程）；
• 记录路径——JSON 响应中记录数组所在的位置（例如 data、results、items）；
• API 的分页方式（下一页 URL、链接头、游标、偏移量、页码或单页）；
• 主键字段；以及
• 可选的增量游标字段（类似 updated_at 的字段），这样重新同步时只会获取新增或变更的行。

向用户索要凭据值，但要告知用户，你只会将其放入 auth_* 负载键中，绝不会放入清单。

步骤 2 — 起草清单

根据 references/manifest-reference.md 编写 RESTAPIConfig。让 auth 块与认证方案匹配，选择与文档一致的分页器，将 data_selector 设为记录路径；如果 API 提供类似 updated_at 的游标和匹配的查询参数，则添加 incremental 块。对于必须按父级逐一获取行的端点（例如 /forms/{form_id}/responses），使用父级/子级 resolve 参数 — 请参阅扇出示例。嵌套层级保持为一级。

步骤 3 — 验证并列出资源

调用 external-data-sources-db-schema，并传入 { source_type: "Custom", manifest_json: "<stringified manifest>", auth_token: "<credential>" }。凭证键并非字面上的 auth_* — 请使用与认证类型对应的键： auth_token（bearer）、auth_api_key（api_key）、auth_password（http_basic），或 auth_oauth2_client_secret（+ auth_oauth2_refresh_token，用于 refresh-token 授权）。该调用会验证清单结构、 扇出图和凭证（有限的实时探测）， 然后为每项资源返回一个表条目，其中包含 detected_primary_keys 和 incremental_fields。如果返回 400， message 会以通俗易懂的英语说明问题（例如 resources[0].endpoint.path: must not be empty）— 修正清单后重试。 重复此步骤，直到验证通过。

步骤 4 — 测试读取每项资源

对于每项资源，调用 external-data-sources-preview-resource，并传入 { source_type: "Custom", payload: { manifest_json, auth_token }, resource_name: "<name>", limit: 10 }（auth_token 键因认证类型而异，与 步骤 3 相同）。该调用最多返回 limit 条真实记录以及推断出的 columns。请检查以下内容：

• data_selector 是否正确 — rows 应是预期的记录，而不是包装对象。如果 rows 看起来像 [{ "data": [...] }]，说明你指向了封装层，而非数组；请修正 data_selector。
• primary_key 是否存在于记录中且唯一。
• 记录中是否存在增量 cursor_path 字段，且其值看起来像可排序的时间戳或 ID。

实时请求失败（主机无法访问、认证被拒绝）时，会返回 error，且 rows 为空 — 请修正凭证或 URL 后重试。重复步骤 2–4，直到样本看起来正确。

步骤 5 — 创建数据源

调用 data-warehouse-source-setup，并传入 { source_type: "Custom", payload: { manifest_json, auth_token }, prefix: "<short_name>" }（auth_token 键因认证类型而异，与步骤 3 相同）。该调用会启用清单中的所有资源，并采用合理的同步默认设置（清单声明了游标时使用增量同步，否则执行完整刷新），同时创建数据源。如果用户只需要部分资源， 则改用 external-data-sources-create 并传入 schemas 数组（schemas 的格式请参阅 setting-up-a-data-warehouse-source）。选择简短的小写 prefix — 在 HogQL 中，表名会变为 {prefix}_{resource_name}。

创建后，调用 external-data-schemas-list 向用户展示初始同步状态，并告知他们如何查询： SELECT * FROM {prefix}_{resource_name} LIMIT 10。

重要说明

• 创建前务必先预览。 db-schema 可验证清单能否解析以及凭据是否有效；预览则可根据真实数据行验证字段映射（data_selector / primary_key / cursor_path）。跳过预览是创建出同步不到任何数据行或数据行格式错误的数据源的最常见原因。
• 密钥仅放在 auth_* 中。 切勿将令牌／密钥／密码直接写入 manifest_json，否则会被拒绝，而且清单不包含机密信息（会原样传回客户端）。
• 只允许一层扇出。 子资源可以依赖顶层父资源；父资源本身不能是子资源。
• 仅支持 GET 和 POST。 引擎会读取上游数据；不允许使用 PUT／PATCH／DELETE，以防清单修改源 API。
• 谨慎选择游标。 优先选择 updated_at 一类的字段，而不是 created_at（这样可以捕获编辑）；如果游标不是日期时间类型（例如整数 ID），请设置 cursor_type，确保按正确类型进行比较。
• **OAuth2 密钥会在首次调用 db-schema / preview / create 时存入服务器管理的凭据存储中；轮换后的一次性刷新令牌也会持久化到服务器端。因此，在同一次设置过程中，请在这些调用之间保持整个 client.auth 块完全一致，并且每次都重新提交相同的密钥。设置过程中更改任何认证块字段都会丢弃已存储的轮换令牌；随后，如果提供方会轮换一次性刷新令牌，就会拒绝下一次令牌生成，直到用户获取新的令牌。切勿自行设置 auth_oauth2_integration_id（该字段由服务器管理）；若要重新连接令牌失效的数据源，请使用重新输入的 auth_oauth2_client_secret / auth_oauth2_refresh_token 更新该数据源。认证块字段请参阅清单参考中的 OAuth2 部分。