在 Celigo 中配置 Export…

在 Celigo 集成中创建或编辑 Export（数据源）时，按目标系统选择正确的 adaptorType 并配置增量、文件解析、查找与异步轮询。

适用场景

解决思路

1. 先识别要从哪个目标系统拉取数据，这决定 adaptorType、连接类型和配置形态。
2. 构建前先查已有模式：用 `celigo account search "<keyword>"` 搜索账户内相关资源，用 `celigo account dependencies export <id>` 查看某 export 使用的连接及引用它的 flow，用 `celigo account lint` 找出未被任何 flow 引用的孤立 export，用 `celigo exports list | grep -i "<application-name>"` 查找相似 export，用 `celigo templates marketplace` 搜索预建集成模板，用 `celigo templates preview <id> --model Export` 和 `celigo templates preview <id> --summary` 预览模板配置；账户索引超过 4 小时会自动刷新，可用 `celigo account snapshot` 强制刷新。
3. 写任何 HTTP 配置前先检查预建连接器：用 `celigo http-connectors list | grep -i "<application-name>"` 搜索 550+ HTTP 连接器，用 `celigo http-connectors get <id> --full` 查看端点、资源和认证配置，用 `celigo http-connectors catalog <id> --resource-type export --published-only` 和 `celigo http-connectors endpoint-detail <id> --resource-type export --resource-id <rid> --endpoint-id <epid>` 深入查看 export 端点；用 `celigo tp-connectors list` 搜索 EDI/AS2/VAN 贸易伙伴连接器。若存在 HTTP 连接器，则从连接器创建连接（`http._httpConnectorId`），并从连接器端点元数据中取 `relativeURI`、方法、分页和响应路径，而不是从公开 API 文档重建；export 上的 `http._httpConnectorEndpointId`、`http._httpConnectorVersionId`、`http._httpConnectorResourceId` 为只读，由平台设置。若存在贸易伙伴连接器，通过 `ftp._tpConnectorId`（FTP export）或 `as2._tpConnectorId`（AS2 export）引用，并可能需设置 `_ediProfileId` 做 EDI 文档校验。
4. 对 NetSuite、Salesforce、RDBMS 连接，用 `celigo metadata types <connectionId>` 查询可用记录类型/sObject/表（NetSuite 还会返回 saved search 及其 ID），用 `celigo metadata fields <connectionId> <entityType>` 查询字段 ID、名称、类型（NetSuite 含子表字段，Salesforce 含关系名，RDBMS 含列名和类型）。
5. 判断类别：是 listener（源系统实时推送）、file transfer（拉取并解析/传输文件）还是 record-based export（按计划轮询 API 或查询数据库）。
6. 按 Adaptor Decision Matrix 选择正确的 adaptorType：REST/GraphQL 用 `HTTPExport`；HTTP 文件（Google Drive、Box、Dropbox、Azure Blob）用 `HTTPExport` 加 `http.type: "file"`；NetSuite 用 `NetSuiteExport`；Salesforce 用 `SalesforceExport`；SQL 用 `RDBMSExport`；MongoDB 用 `MongodbExport`；JDBC 用 `JDBCExport`；DynamoDB 用 `DynamodbExport`；FTP/SFTP 文件用 `FTPExport`；S3 文件用 `S3Export`；Webhook/推送事件用 `WebhookExport`；AS2 EDI 用 `AS2Export`；手动上传用 `SimpleExport`；本地文件系统用 `FileSystemExport`；预建 stack 连接器用 `WrapperExport`。选择顺序：优先原生适配器，其次预建 HTTP 连接器，最后才手写 HTTP。`adaptorType` 区分大小写（`HTTPExport` 而非 `httpExport`）。
7. 构建 export JSON：始终读 `request.yml`（所有 export 的基础字段），加上适配器专属 schema（如 `http.yml`），若基于文件再加 `file.yml`，若增量再加 `delta.yml` 或使用 Handlebars URI 模式 `{{{lastExportDateTime}}}`，若克隆再加 `clone-request.yml` 和 `clone-response.yml`。
8. 每个 export 至少需要：`name`、`adaptorType`、`_connectionId`（`WebhookExport` 和 `SimpleExport` 除外）、适配器配置块（`http{}`、`netsuite{}`、`ftp{}`、`salesforce{}`、`rdbms{}` 等）。
9. 选择同步类型：增量（`type: "delta"`）只拉取上次成功运行后创建或修改的记录，非 HTTP 适配器用 `delta.dateField` 设置时间戳字段，HTTP export 则在 `relativeURI` 或 body 中嵌入 `{{{lastExportDateTime}}}`；一次性（`type: "once"`）通过 `once.booleanField` 跟踪标志让每条记录只处理一次（每次运行选 `false` 的记录，成功后置 `true`）；全量（既非 delta 也非 once）每次运行重拉整个数据集。请求含糊时先确认同步类型。
10. 选择 listener/webhook 还是计划 export：源支持推送且需低延迟时用 listener（`WebhookExport` 或 NetSuite/Salesforce 的 `type: "distributed"`）；源无推送机制或可接受非高峰批处理时用计划 export。NetSuite 和 Salesforce 可两者混用：listener 处理低延迟反应，计划 export 作为回填、日终对账和 webhook 中断后追赶的安全网。
11. 选择 lookup export 还是独立计划 export：若需求是「对每个 X 查找 Y」，用 lookup export（`isLookup: true`），它按上游记录逐条在流水线中运行；若需求是「每小时拉取所有 Y」，用计划 export 作为起点。
12. 配置 one-to-many 扇出：设 `oneToMany: true` 并将 `pathToMany` 指向子数组路径，每个数组元素触发一次独立 lookup；扇出后数组元素本身即记录，模板用 `{{record.variantId}}` 引用元素自身字段（不是 `{{variantId}}`，也不是 `{{record.lineItems.variantId}}`）。构建时预览报「`<field>` not defined in the model」是预期行为，不要因此「修复」正确的 `{{record.X}}` 引用。响应映射会自动按元素合并：编写普通顶层 `fields` 响应映射即可将每个结果合并到对应扇出元素。两个反模式：不要用 `lists` 条目定位该数组（会在每个元素内嵌套新数组），不要在 `postResponseMap` 中做逐元素合并（它看到的是父记录页而非逐元素结果）。
13. 配置 lookup 的响应映射：在 flow 的 `pageProcessors[]` 条目上配置，但在构建 lookup export 时规划。响应含 `data` 数组和 `errors` 数组。预期单结果（如按 ID 取一个订单）时用 `data[0].fieldName`；预期多结果时用 `extract: "data"` 映射整个数组（下游按普通 JSON 数组读取，或用 one-to-many 扇出），或用 `lists` 条目配合 `data[*].fieldName` 提取构建重塑数组。不要把 `data[*].fieldName` 放在顶层 `fields[].extract`——通配符会被静默忽略且不会合并任何内容。响应映射使用 Transformation 1.0 语法（extract/generate 对），而非新的表达式转换。
14. 理解 export 执行流水线顺序：1) API 请求/查询/文件读取；2) 响应解析（`resourcePath` 从响应体或文件中提取记录数组，如 HTTP 的 `http.response.resourcePath`、JSON 文件的 `file.json.resourcePath`、XML 的 XPath）；3) 转换（可选，`transform` 在提取后重塑单条记录，Transformation 2.0）；4) 输出过滤器（可选，丢弃不匹配过滤表达式的记录）；5) preSavePage hook（可选，对整页记录做 JavaScript 处理）。区分：`resourcePath` 告诉 export 在响应中哪里找记录，transform 重塑提取后每条记录的样子；「从 X 提取记录」或「把每个 X 当作独立记录」几乎总是改 `resourcePath` 而非 transform；需要展平嵌套对象、重命名字段或重构单条记录时才用 transform。
15. 区分源端 transform 与目标端 mapping：源 export 上的 transform 在记录进入 flow 时重塑（展平嵌套响应、对齐多源到统一形态）；下游 import 上的 mapping 在记录离开 flow 前往目标时重塑。不要为「匹配目标」而加 transform——那是目标 import mapping 的职责。
16. 对异步 API（submit、poll、fetch）通过 `http._asyncHelperId` 附加 async helper，它属于 export 而非独立管理，包含三部分：1) 状态 export（必需）——每次轮询运行询问「完成了吗」，配置响应中要读取的状态路径、区分大小写的 in-progress/done/done-without-data/error 值列表（取自 API 文档）、初始等待和轮询等待间隔（分钟）；2) 结果 export（可选，通常存在）——状态报告完成后拉取最终负载；3) 初始提交处理——在首次确认中找 job ticket 的位置，「same as status」表示确认本身形如状态响应，否则用资源路径（非 JSON 确认如 Amazon XML 还需转换规则）。约束：状态和结果 export 必须是普通同步 export（async helper 不能嵌套另一个），且配置了 async 的步骤不能自带 transform、输出过滤器或 preSavePage hook——把这些处理放到专用结果 export 上。写异步目标时同样模式对称应用于 import（`_asyncHelperId`）。仅在 API 确实强制 fire-and-check-back 形态时才用 async helper。
17. 使用 CLI 命令：CRUD 用 `celigo exports list`、`celigo exports get <id>`、`celigo exports create < export.json`、`celigo exports update <id> < export.json`、`celigo exports set <id> key=value [key2=value2 ...]`、`celigo exports delete <id>`；测试运行用 `celigo exports invoke [id] [--all]`；克隆和连接管理用 `echo '{"connectionMap":{"oldConnId":"newConnId"}}' | celigo exports clone <id>` 和 `celigo exports replace-connection <id> <newConnectionId>`；调试用 `celigo exports enable-debug <id> [--duration <minutes>]` 和 `celigo exports disable-debug <id>`。
18. 提交前核对清单：`adaptorType` 大小写精确匹配矩阵；HTTP export 已检查预建连接器；`_connectionId` 有效且指向正确类型的在线连接（`WebhookExport`/`SimpleExport` 不需要）；适配器配置块与 adaptorType 匹配；`resourcePath` 或查询正确（错误路径会静默返回 0 条记录）；HTTP export 配置了 `http.paging`；增量已配置（`delta.dateField` 或 URI 中的 `{{{lastExportDateTime}}}`）；文件解析匹配格式（`file.type` 为 csv/json/xml/xlsx/edi）；`mockOutput` 格式为 `{ "page_of_records": [{ "record": {...} }] }` 而非普通数组；无 `rest:` 块（会创建遗留 RESTExport，新 export 只用 `http:`）；输出过滤器语法有效；若 `isLookup: true` 已为 flow 的 `pageProcessors[]` 规划响应映射。
19. 避免常见陷阱：PUT 会抹掉省略字段，先 GET 再改再 PUT（`set` 命令会处理）；包含 `rest:` 块会创建遗留 RESTExport；`resourcePath` 错误会静默返回 0 条记录；`mockOutput` 格式必须是 `{ "page_of_records": [{ "record": {...} }] }`；HTTP 增量 export 用 Handlebars（`relativeURI` 中的 `{{{lastExportDateTime}}}`）而非 `delta.dateField`；NetSuite saved search 需要 `netsuite.restlet.searchId`（用 `celigo metadata types <connectionId>` 找）；文件 export 需要 `file{}` 块，否则返回原始字节而非解析记录；Webhook export 没有 `_connectionId`，设置会导致校验错误；distributed export 需要 export 上 `type: "distributed"` 且连接上 `distributed: true`；`type: "once"` 需要专用可写跟踪标志，`once.booleanField` 必须可被 export 的连接写入且无其他进程更新同一字段；async-helper export 不能自带 transform、输出过滤器或 preSavePage hook，状态和结果 export 必须是普通同步 export。
20. 按错误表排查：`404 Not Found` 检查 `relativeURI`/`resourcePath` 和路径参数；`401 Unauthorized` 用 `celigo connections ping <connId>` 并重新授权 OAuth；`0 records exported` 检查 `resourcePath`、放宽 delta 窗口、去掉输出过滤器测试；preSavePage 中 `Cannot read property of undefined` 加空值检查 `if (record.field)`；`mockOutput is invalid` 改用对象格式；`Invalid adaptorType` 用矩阵中的精确大小写；`Connection is offline` 修凭证后重新 ping；`429` 降低连接上的 `concurrencyLevel` 并加重试；大 export `Timeout` 加分页、缩小日期范围或增大超时；`File parsing error` 核对 `file.type`、`file.csv.columnDelimiter` 和编码。

适用边界 · 注意事项

• 不要对已有原生适配器的应用（NetSuite、Salesforce、数据库、FTP/S3）手写 `HTTPExport` 打其 REST API——优先用原生适配器。
• 不要在存在预建 HTTP 连接器或贸易伙伴连接器时从公开 API 文档手写 HTTP 配置——先搜索连接器目录。
• 不要给同步 API 添加 async helper——那只是额外轮询加状态和结果 export 的维护开销。