data360-prepare

data360-prepare：Data Cloud 准备阶段

当用户需要数据摄取和数据湖准备工作时，使用此技能：数据流、Data Lake Objects（DLO）、转换、Document AI、非结构化数据摄取，或从连接器设置移交到实时数据流。

此技能负责的任务

当工作涉及以下内容时，使用 data360-prepare：

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

以下情况应交由其他技能处理：

• 仍在创建或测试源连接 → data360-connect
• 映射到 DMO 或设计 IR/数据图 → data360-harmonize
• 查询已摄取的数据 → data360-query

---

首先收集必要的上下文

询问或推断：

• 目标组织别名
• 源连接名称
• 源对象 / 数据集 / 文档源
• 所需的数据流类型
• DLO 命名预期
• 用户是要创建、更新、运行还是删除数据流
• 源是 CRM、数据库连接器、非结构化文件源，还是 Ingestion API 数据流

---

核心操作规则

• 运行 Data Cloud 命令前，先验证外部插件运行时。
• 修改数据摄取资产前，先运行共享就绪情况分类器：node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase prepare --json。
• 创建新的数据摄取资产前，优先检查现有数据流和 DLO。
• 日常使用时，通过 2>/dev/null 抑制关联插件的警告噪声。
• 将 DLO 和字段命名视为 Data Cloud 专用，而非 CRM 原生。
• 创建数据流前，确认每个数据集应归类为 Profile、Engagement 还是 Other。
• 处理非结构化数据源时，区分数据流级刷新与连接级重新运行。
• 首次创建数据流或非结构化资产受平台限制时，有针对性地使用 UI 设置。
• 仅在数据摄取资产状态明确正常后，才移交给 Harmonize。

---

建议的工作流

1. 对准备工作进行就绪情况分类

node ../data360-orchestrate/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。

7. 谨慎处理非结构化数据源

对于 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 创建流程可能不会自动配置这些内容。

8. 使用本地 Ingestion API 示例处理数据发送工作流

对于向 Data Cloud 推送记录的外部系统：

1. 在 data360-connect 中创建连接器
2. 使用 sf data360 connection schema-upsert 上传架构
3. 如有需要，在 UI 中创建数据流
4. 使用 examples/ingestion-api/ 中的本地示例发送记录

cd examples/ingestion-api
cp .env.example .env
python3 send-data.py

关键细节：

• 身份验证采用分阶段流程：JWT → Salesforce 令牌 → Data Cloud 令牌
• Ingestion 端点使用租户 URL，而不是 Salesforce 实例 URL
• 202 表示已接受载荷进行处理，并不表示记录可以立即查询
• 验证失败通常会显示在 Problem Records DLO 系列中

9. 然后再进入协调阶段

数据流和 DLO 状态正常后，移交给 data360-harmonize。

---

高优先级注意事项

• CRM 支持的数据流行为与完全自定义的连接器框架数据摄取不同。
• sf data360 data-stream run 和 sf data360 connection run-existing 不能互换；对于非结构化数据重新扫描，优先使用数据流级别的刷新。
• SFDC 数据流按平台管理的计划进行同步；data-stream run 并非刷新 CRM 连接器的通用控制路径。
• 一些外部数据库连接器可以通过 API 创建，但创建数据流仍需要 UI 流程或针对组织的浏览器自动化。不要承诺所有连接器类型都能通过纯 CLI 创建数据流。
• 对于初始的 SharePoint 风格非结构化数据设置，UI 中提供的功能可能比精简的 CLI DLO 创建流程更丰富。
• 删除数据流也可能删除关联的 DLO，具体取决于删除模式。
• DLO 字段名称与 CRM 字段名称不同，包括 __c → _c 的转换。
• 使用 Data Cloud SQL 查询 DLO 记录数，不要假设列表输出足以满足需求。
• CdpDataStreams 表示当前组织或用户尚未启用数据流模块；应引导用户检查功能开通和权限，而不是盲目重试。

---

输出格式

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>

---

参考

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