SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sf-datacloud-prepare

sf-datacloud-prepare

数据与分析

查看项目

更新于 10-13 20:08

技能介绍

sf-datacloud-prepare：Data Cloud 准备阶段

当用户需要处理接入与数据湖准备工作时使用本技能：数据流、数据湖对象（DLO）、转换、Document AI、非结构化接入，或从连接器设置到实时流的交接。

何时由本技能负责

当工作涉及以下内容时使用 sf-datacloud-prepare：

  • sf data360 data-stream *
  • sf data360 dlo *
  • sf data360 transform *
  • sf data360 docai *
  • 选择数据应如何进入 Data Cloud
  • 在源更新后重新运行或重新扫描接入
  • 在连接器设置完成后准备由 Ingestion API 支撑的数据流

何时转交其他技能

  • 仍在创建／测试源连接 → sf-datacloud-connect
  • 映射到 DMO 或设计 IR／数据图 → sf-datacloud-harmonize
  • 查询已接入数据 → sf-datacloud-retrieve

需要先收集的上下文

询问或推断：目标 org 别名、源连接名称、源对象／数据集／文档源、期望的流类型、DLO 命名预期、用户是要创建、更新、运行还是删除流，以及源是 CRM、数据库连接器、非结构化文件源还是 Ingestion API 馈送。

核心操作规则

  • 运行 Data Cloud 命令前先验证外部插件运行时。
  • 在变更接入资产前运行共享就绪分类器：node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json。
  • 创建新接入资产前优先检查已有数据流与 DLO。
  • 正常使用时用 2>/dev/null 抑制关联插件警告噪声。
  • 将 DLO 命名与字段命名视为 Data Cloud 专有，而非 CRM 原生。
  • 创建流前确认每个数据集应被视为 Profile、Engagement 还是 Other。
  • 处理非结构化源时，区分流级刷新与连接级重跑。
  • 当初始流或非结构化资产创建受平台限制时，有意识地使用 UI 设置。
  • 仅在接入资产明确健康后才交接给 Harmonize。

推荐工作流

  1. 分类准备工作的就绪状态： node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json

  2. 检查已有接入资产： sf data360 data-stream list -o <org> 2>/dev/null sf data360 dlo list -o <org> 2>/dev/null

  3. 创建前确认流类别。建议类别时可参考：Profile 用于人员／实体记录，典型要求是主键；Engagement 用于基于时间的事件或交互，典型要求是主键加事件时间字段；Other 用于参考／配置／支持性数据集，典型要求是主键。当源不明确时，明确询问用户该数据集应被视为 Profile、Engagement 还是 Other。

  4. 有意识地创建或检查数据流： sf data360 data-stream get -o <org> --name <stream> 2>/dev/null sf data360 data-stream create-from-object -o <org> --object Contact --connection SalesforceDotCom_Home 2>/dev/null sf data360 data-stream create -o <org> -f stream.json 2>/dev/null sf data360 data-stream run -o <org> --name <stream> 2>/dev/null

  5. 检查 DLO 形态： sf data360 dlo get -o <org> --name Contact_Home__dll 2>/dev/null

  6. 选择合适的刷新机制。使用与用户目标匹配的较小刷新范围： sf data360 data-stream run -o <org> --name <stream> 2>/dev/null sf data360 connection run-existing -o <org> --name <connection-id> 2>/dev/null

data-stream run 最接近流级刷新或重扫描。connection run-existing 在连接级别运行，对某些连接器工作流有用，但不能可靠替代非结构化源上的流刷新。对于非结构化文档连接器，当目标是重新扫描新增或更改的文件时，优先使用 data-stream run。

  1. 有意识地处理非结构化源。对于 SharePoint 风格文档接入，最小的非结构化 DLO 载荷可以是： { "name": "my_udlo", "label": "My UDLO", "category": "Directory_Table", "dataSource": { "sourceType": "SF_DRIVE", "directoryAndFilesDetails": [ { "dirName": "SPUnstructuredDocument/<CONNECTION_ID>/<SITE_ID>", "fileName": "*" } ], "sourceConfig": { "reservedPrefix": "$dcf_content$" } } }

当用户需要更丰富的端到端管道时，首次非结构化设置使用 UI。UI 路径可以生成额外的文档元数据字段与下游资产，而仅用 CLI 创建 DLO 的流程可能不会自动准备这些内容。

  1. 对发送数据工作流使用本地 Ingestion API 示例。对于向 Data Cloud 推送记录的外部系统：在 sf-datacloud-connect 中创建连接器；用 sf data360 connection schema-upsert 上传 schema；在需要时在 UI 中创建流；用 examples/ingestion-api/ 中的本地示例发送记录： cd examples/ingestion-api cp .env.example .env python3 send-data.py

关键细节：认证是分阶段流程：JWT → Salesforce token → Data Cloud token；接入端点使用租户 URL，而非 Salesforce 实例 URL；202 表示载荷已被接受处理，不代表记录立即可查询；验证失败通常出现在 Problem Records DLO 系列中。

  1. 之后才进入 harmonization。一旦流与 DLO 健康，交接给 sf-datacloud-harmonize。

重要注意事项

  • 由 CRM 支撑的流行为与完全自定义连接器框架接入不同。
  • sf data360 data-stream run 与 sf data360 connection run-existing 不可互换；非结构化重扫描优先使用流级刷新。
  • SFDC 流按平台管理的计划同步；data-stream run 不是 CRM 连接器刷新的通用控制路径。
  • 某些外部数据库连接器可以通过 API 创建，但流创建仍需要 UI 流程或特定 org 的浏览器自动化。不要承诺对每种连接器类型都有纯 CLI 的流创建路径。
  • 初始 SharePoint 风格非结构化设置在 UI 中可能比最小 CLI DLO 创建流程更丰富。
  • 流删除也可能删除关联 DLO，除非删除模式另有说明。
  • DLO 字段命名与 CRM 字段命名不同，包括 __c → _c 的转换。
  • 使用 Data Cloud SQL 查询 DLO 记录数，而不是假设列表输出就足够。
  • CdpDataStreams 表示流模块对当前 org／用户受限；引导用户审查 provisioning／权限，而不是盲目重试。

输出格式

Prepare task: <stream / dlo / transform / docai> Source: <connection + object> Target org: <alias> Artifacts: <stream names / dlo names / json definitions> Verification: <passed / partial / blocked> Next step: <harmonize or retrieve>

参考

  • README.md
  • examples/ingestion-api/README.md
  • ../sf-datacloud/assets/definitions/data-stream.template.json
  • ../sf-datacloud/references/plugin-setup.md
  • ../sf-datacloud/references/feature-readiness.md