在 Celigo 集成中用查找缓存做 ID 映射…

当需要在 Celigo 流程中预加载参考数据以实现跨系统 ID 映射、去重、状态跟踪或静态参考表时，配置内存键值查找缓存。

适用场景

解决思路

1. 先确定用例：需要缓存什么数据？是交叉引用 ID、静态参考表、去重键还是处理状态？这决定数据结构、加载策略和生命周期。
2. 创建新缓存前先搜索账户中已有的缓存：运行 `celigo lookup-caches list`，以及 `celigo account search "lookup cache"` 和 `celigo account search "<与用例相关的关键词>"`。
3. 先创建缓存元数据（数据单独加载）：`echo '{"name":"Product SKU to NetSuite ID","description":"..."}' | celigo lookup-caches create`；如需集成范围与模板包含则加 `_integrationId` 和 `includeDataInTemplatesAndCloning:true`。
4. 用 `put-data` 命令 upsert 键值条目，CLI 会按数量（1000 条）和大小（5 MB）自动分批：`echo '{"data":[{"key":"SKU-001","value":"{\"nsId\":\"12345\"}"}]}' | celigo lookup-caches put-data <cacheId>`；大数据集可从脚本或文件管道输入 `{ "data": [...] }` JSON。
5. 验证数据：`celigo lookup-caches get-data <cacheId>` 取第一页（最多 1000 条）；用 `echo '{"keys":["SKU-001"]}' | celigo lookup-caches get-data <cacheId>` 取指定键；用 `echo '{"startsWith":"SKU-"}' | celigo lookup-caches get-data <cacheId>` 按前缀查询；用 `celigo lookup-caches get <cacheId>` 查看缓存大小。
6. 在导入或导出资源的 `lookups[]` 数组中添加引用该缓存 ID 的条目，然后在字段映射或 Handlebars 表达式中使用该 lookup 名称；关键字段包括 `name`、`_lookupCacheId`、`extract`（如 `$.details.price`）、`default`、`allowFailures`；在 Handlebars 中用 `{{lookup 'lookupName' record.fieldName}}` 引用。
7. 规划数据刷新策略（缓存不会自动刷新）：手动方式适合静态参考表；流程驱动方式用带 postSubmit 或 preSavePage 钩子的计划流程调用缓存数据 API 刷新；清空重载方式适合数据集较小可快速重载的场景。
8. 区分 purge 与 delete：purge 清空数据（`celigo lookup-caches purge-data <id>`）但缓存资源和所有引用其 `_lookupCacheId` 的 lookup 保持有效；delete 删除资源本身（`celigo lookup-caches delete <id>`）会使所有引用失效，仅用于彻底弃用缓存，删除前先检查引用。
9. 注意加载是按 key 的 upsert：重新加载刷新后的数据集会覆盖匹配的键并新增键，但不会删除新加载中缺失的键；真正的“整表替换”是 purge + reload，而非单纯重载。
10. 避免把多匹配 lookup 的首个结果写入更新：缓存读取每个键只返回一个值，用真正唯一的键（外部 ID、主键）解析是安全的；但可能返回多个匹配的 lookup（如按姓名、邮箱、电话等模糊键的实时查询）把 `data[0]` 喂给更新会在每个重复项上写入任意错误记录。防护方式二选一：配置解析 lookup 在多匹配时失败或跳过记录，或在写入前检查结果数量等于一（写入步骤的输入过滤器，或用 postResponseMap 钩子丢弃/报错返回多于一条的记录）。
11. 处理常见错误：数据 upsert 报 422 说明超过 5 MB 批次限制或单条过大，减小批次；数据操作报 404 说明缓存 ID 不存在或已删除，用 `celigo lookup-caches get <id>` 验证；流程中 lookup 返回 null 说明键不存在，检查缓存已填充且键格式完全匹配（区分大小写）；返回整个对象而非字段说明缺少 `extract` 路径，添加 `extract: "$.fieldName"`；报 403 说明账户没有 Lookup Cache 许可，联系 Celigo 启用；缓存接近 50 MB 说明单缓存数据过多，清理陈旧条目、按类别拆分多个缓存或归档旧数据。
12. 注意陷阱：PUT 会抹掉未提供的字段，始终先 GET 再修改再 PUT，`set` 命令会处理这一点；数据 upsert 用 POST 而非 PUT；值必须是字符串，复杂对象需 JSON 字符串化，消费方 lookup 的 `extract` 路径作用于解析后的 JSON；每个缓存 50 MB、每环境总计 1 GB，接近上限的缓存（如生产中约 49 MB 的 NetSuite Item 缓存）下次 upsert 有触顶风险，监控响应中的 `size` 和 `sizeInMB`；`get-data` 每次最多返回 1000 个键，超过时用 `startsWith` 前缀查询或指定键查询；没有自动 TTL 或过期，数据会一直保留到显式删除或清空，陈旧数据是常见 bug 来源；`includeDataInTemplatesAndCloning` 默认为 false，若缓存数据是集成配置的一部分（静态参考表、运费覆盖）需设为 true，否则克隆或从模板安装时数据会丢失；沙箱和生产缓存相互独立，`sandbox: true` 的缓存仅沙箱流程可访问，反之亦然；删除缓存是软删除，缓存保留 30 天后才永久移除，在此期间无法用相同 `_id` 重新创建同名缓存。

适用边界 · 注意事项

• 需要每次查询都反映源系统最新状态的场景，应使用实时/动态 lookup（每条记录发起 HTTP 请求、SOQL、NetSuite 搜索或 SQL），而非预加载的查找缓存。
• 只有少量稳定且极少变化的键值对时，应使用步骤内联的静态 `map` 对象，无需缓存也无需外部调用。
• 账户没有 Lookup Cache 许可时无法使用（会报 403），需先联系 Celigo 启用该功能。