在 Celigo 中创建、组织…

当需要创建、组织、克隆、跨环境提升或版本化 Celigo 集成（integration），或判断新工作应放入现有集成还是新建集成时使用。

适用场景

解决思路

1. 先发现现有集成：运行 `celigo integrations list` 列出所有集成（含父/子条目），用 `celigo integrations get <id>` 查看单个集成记录，用 `celigo account search "<keyword>"` 按关键词查找相关资源；查看计算字段 `numFlows`、`numError`、`numRegisteredConnections`、`numOfflineConnections`、`lastErrorAt` 找出需要关注的集成。
2. 决定加入现有集成还是新建：默认加入现有集成；仅当管理/监控人员不同（权限边界不同）、工作概念上独立、从 Marketplace 安装模板、或现有集成达到规模上限时才新建。
3. 创建集成：用 `echo '{"name":"Shopify-NetSuite"}' | celigo integrations create` 或 `celigo integrations create < integration.json`；至少提供描述业务用途的 `name`，可选 `description`；Integration App 不从该方式创建，需从 Marketplace 安装。
4. 组织内部资源：自底向上构建（先连接，再 exports/imports，最后 flows/APIs/Tools）；flows/APIs/Tools 属于 owned 资源可被 move（保留 `_id`、历史与错误，仅替换 `_integrationId`，flows 还会清除 `_flowGroupingId`）；connections/lookup caches 属于 registered 资源，通过注册/注销到目标集成实现“移动”；exports/imports/AI agents/guardrails 属于 inherited 资源，需移动其父 flow/API/Tool。
5. 跨环境克隆并重映射连接：克隆会复制集成记录、flows、APIs、Tools、已注册连接、脚本和设置，并加入原集成的 clone family；跨环境克隆是 ILM 的入口；克隆会取消原集成连接上正在进行的作业，需安排在空闲时；在克隆时用连接映射 `{"<oldConnectionId>": "<newConnectionId>"}` 重映射连接，这是唯一能改变绑定的时机。
6. 用 ILM 提升（snapshot、pull、revert）：先对生产集成做 snapshot 保存已知良好状态；在跨环境克隆中开发；将变更 pull 回生产（自动快照包裹合并，冲突会停止 pull 需手动解决）；若 pull 引入回归则 revert 到先前修订；先配置 ignore fields 避免环境特定值（URL、sandbox vs prod ID）在 pull 时穿越；这些操作在 Celigo UI 的 Revisions 标签或公共 API 中执行。
7. 配置每个集成的开关：在集成记录上管理 Notifications（订阅所有 flow 错误、特定 flow 错误或离线连接告警）、Aliases（映射到资源 `_id` 的稳定可移植名称，供脚本按名称引用资源）、Analytics（按集成汇总或按 flow/步骤分组的执行指标）。
8. 删除集成：运行 `celigo integrations delete <id>`；删除是破坏性操作，确认没有正在运行的任务且内部资源不再需要；若需保留资源，先将其移出。
9. 使用 CLI 命令：CRUD 用 `celigo integrations list`、`celigo integrations get <id>`、`celigo integrations create < integration.json`、`celigo integrations update <id> < integration.json`、`celigo integrations delete <id>`；发现用 `celigo account search "<keyword>"`；克隆、ILM、move、注册/注销、通知、别名、分析、跨账户 transfer、Marketplace 安装/升级需在 Celigo UI 或公共 API 中执行。
10. 提交前检查：确认基于访问边界选择加入现有或新建集成；新集成名称描述业务用途而非单一操作；跨环境克隆的连接映射覆盖每个需指向目标环境连接的源 `_connectionId`；ILM 提升的源克隆是 lifecycle-linked（通过 UI 克隆流程创建）而非 standalone；ignore fields 覆盖环境特定值；风险 pull 前对接收方集成做预部署快照；同一资源应改变集成时用 move 而非 clone；克隆或删除前确认没有关键任务在运行。
11. 避免常见错误：standalone 克隆会静默破坏 ILM（快照被拒、pull 报告无变更），需通过 UI 克隆流程重建；连接重映射只能在克隆时进行，事后 update 无法重映射；注册不是绑定，`_connectionId` 才真正绑定连接；克隆会取消进行中的作业；pull 仅在直接相关且 lifecycle-linked 的家族成员间工作；ignore fields 只影响现有资源的字段级更新，不抑制资源创建/删除；move 保留资源而 clone 创建新资源；Integration-App 资源受模板控制不可自由移动；跨账户 transfer 不同于资源 move 和 clone；PUT/update 会擦除省略字段，需先 GET 再修改再更新；子集成需要 Integration App 父级，普通集成用兄弟集成或按 flow 命名区分。
12. 处理常见错误：pull 报告无变更但确有编辑时，源克隆是 standalone，需通过 UI 克隆流程重建；快照报 `clone must be linked to source integration` 时使用 lifecycle-linked 克隆；pull 冲突时在 Celigo UI Revisions 标签手动解决；克隆后 flow 仍指向源环境连接时，用连接映射重新克隆；环境特定值被 pull 覆盖时，将路径加入 ignore fields 后重新 pull；无法移动 flow/API/Tool 时，资源为 Integration-App 所有，使用 Custom-flows 区域或普通集成；集成编辑报 `403 Forbidden` 时使用具有 manage 或 admin 权限的 token；集成 get/update 报 `404 Not Found` 时用 `celigo integrations list` 验证 ID；集成列表缺少预期集成时，使用 admin/owner token 或授予 Custom 访问权限。

适用边界 · 注意事项

• 不适用于非 Celigo 平台的集成管理。
• 不适用于仅需管理单个 flow、API、Tool 或 connection 而不涉及集成容器组织的场景。
• 不适用于 Marketplace 模板安装/升级或跨账户 Integration transfer 的独立操作细节。