preparing-datacloud

准备 Data Cloud：Data Cloud 准备阶段

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

此技能负责的任务

当工作涉及以下内容时，使用 preparing-datacloud：

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

以下情况应委派给其他技能：

• 仍在创建或测试源连接 → 连接 Data Cloud
• 映射到 DMO 或设计 IR/数据图 → 协调 Data Cloud
• 查询已摄取的数据 → 检索 Data Cloud 数据

---

首先收集必要的上下文

询问或推断：

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

---

核心操作规则

• 运行 Data Cloud 命令前，验证外部插件运行时。
• 修改摄取资源前，运行共享就绪状态分类器：node ../orchestrating-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 ../orchestrating-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。

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. 在 connecting-datacloud 中创建连接器
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 状态正常后，转交给 harmonizing-datacloud。

---

高优先级注意事项

• CRM 支持的流行为与完全自定义的连接器框架摄取并不相同。
• sf data360 data-stream run 和 sf data360 connection run-existing 不能互换；对于非结构化数据的重新扫描，优先使用流级别的刷新。
• SFDC 流按平台管理的计划同步；data-stream run 并不是刷新 CRM 连接器的通用控制路径。
• 某些外部数据库连接器可以通过 API 创建，但创建流仍需要 UI 流程或特定组织的浏览器自动化。不要承诺所有连接器类型都能通过纯命令行创建流。
• 在最简 CLI DLO 创建流程中，SharePoint 类非结构化数据的初始设置在 UI 中可能更完善。
• 删除流也可能删除关联的 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>

---

参考资料

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