sf-datacloud-connect

sf-datacloud-connect：Data Cloud 连接阶段

当用户需要源连接相关工作时，请使用此技能：连接器发现、连接元数据、连接测试、源对象浏览、连接器架构检查，或外部数据源的连接器专用设置负载。

此技能负责的任务

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

• sf data360 connection *
• 检查连接器目录
• 创建、更新、测试或删除连接
• 浏览源对象、字段、数据库或架构
• 识别已在使用的连接器类型
• 为 Snowflake、SharePoint Unstructured 或 Ingestion API 数据源准备连接器定义

以下情况请委托给其他技能：

• 创建数据流或 DLO → sf-datacloud-prepare
• 创建 DMO、映射、IR 规则集或数据图 → sf-datacloud-harmonize
• 编写 Data Cloud SQL 或搜索索引工作流 → sf-datacloud-retrieve

---

首先收集必要的上下文

询问或推断：

• 目标组织别名
• 连接器类型或源系统
• 用户只想检查，还是要执行实际变更
• 如果已有连接，请提供连接名称或 ID
• 凭据是否已在 CLI 外部配置
• 用户是否也希望在连接设置完成后立即创建数据流
• 源是数据库、非结构化文档源，还是 Ingestion API 数据流

---

核心操作规则

• 首先验证插件运行时；请参阅 ../sf-datacloud/references/plugin-setup.md。
• 在修改连接前运行共享就绪状态分类器：node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json。
• 优先进行只读发现，再创建连接。
• 常规使用时，通过 2>/dev/null 抑制关联插件警告。
• 请记住，connection list 需要 --connector-type。
• 使用名称解析非 Salesforce 连接时，调用 connection test 请传入 --connector-type。
• 如果组织情况不熟悉，请先从数据流中发现现有连接器类型。
• 使用经过整理的示例负载，再编写连接器专用凭据或参数。
• 对于整理示例之外的连接器类型，请先通过 REST 检查一个已知可用的 UI 创建连接，再构建 JSON。
• 不要仅因连接创建成功，就承诺所有连接器类型都支持通过 API 创建数据流。

---

推荐工作流

1. 对连接工作进行就绪状态分类

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json

2. 发现连接器类型

sf data360 connection connector-list -o <org> 2>/dev/null
sf data360 data-stream list -o <org> 2>/dev/null

3. 按类型检查连接

sf data360 connection list -o <org> --connector-type SalesforceDotCom 2>/dev/null
sf data360 connection list -o <org> --connector-type REDSHIFT 2>/dev/null
sf data360 connection list -o <org> --connector-type SNOWFLAKE 2>/dev/null

4. 检查特定连接或已上传的架构

sf data360 connection get -o <org> --name <connection> 2>/dev/null
sf data360 connection objects -o <org> --name <connection> 2>/dev/null
sf data360 connection fields -o <org> --name <connection> 2>/dev/null
sf data360 connection schema-get -o <org> --name <connection-id> 2>/dev/null

5. 仅在完成发现后测试或创建

sf data360 connection test -o <org> --name <connection> --connector-type <type> 2>/dev/null
sf data360 connection create -o <org> -f connection.json 2>/dev/null

6. 对外部连接器，先使用经过整理的示例负载

从此阶段提供的示例开始，不要从头编写负载：

• examples/connections/heroku-postgres.json
• examples/connections/redshift.json
• examples/connections/sharepoint-unstructured.json
• examples/connections/snowflake-connection.json
• examples/connections/ingest-api-connection.json
• examples/connections/ingest-api-schema.json

典型的 Ingestion API 设置流程：

sf data360 connection create -o <org> -f examples/connections/ingest-api-connection.json 2>/dev/null
sf data360 connection schema-upsert -o <org> --name <connector-id> -f examples/connections/ingest-api-schema.json 2>/dev/null
sf data360 connection schema-get -o <org> --name <connector-id> 2>/dev/null

7. 发现未知连接器类型的负载字段

在 UI 中创建一个连接，然后直接检查：

sf api request rest "/services/data/v66.0/ssot/connections/<id>" -o <org>

---

高优先级注意事项

• connection list 没有真正的全局“列出全部”模式；请按连接器类型查询。
• 连接器目录名称与连接的连接器类型不一定使用相同的标签。
• 如果来源不是默认的 Salesforce 连接器，connection test 可能需要 --connector-type 来解析名称。
• 连接列表为空通常表示“已启用，但尚未配置”，而不是“功能已禁用”。
• Heroku Postgres、Redshift、Snowflake、SharePoint Unstructured 和 Ingestion API 使用的凭据和参数格式各不相同；请复用整理好的示例，不要自行猜测。
• SharePoint Unstructured 在 credentials 数组中使用 clientId、clientSecret 和 tokenEndpoint，不需要 parameters 数组。
• Snowflake 使用密钥对身份验证，通常可以通过 API 创建，但后续的数据流创建仍可能只能在 UI 中完成。
• Ingestion API 连接器设置只有在 connection schema-upsert 上传对象架构后才算完成。
• 某些外部连接器的凭据设置仍依赖 UI 端配置或外部系统权限。

---

输出格式

Connect task: <inspect / create / test / update>
Connector type: <SalesforceDotCom / REDSHIFT / SNOWFLAKE / SPUnstructuredDocument / IngestApi / ...>
Target org: <alias>
Commands: <key commands run>
Verification: <passed / partial / blocked>
Next step: <prepare phase or connector follow-up>

---

参考资料

• README.md
• examples/connections/heroku-postgres.json
• examples/connections/redshift.json
• examples/connections/sharepoint-unstructured.json
• examples/connections/snowflake-connection.json
• examples/connections/ingest-api-connection.json
• examples/connections/ingest-api-schema.json
• ../sf-datacloud/references/plugin-setup.md
• ../sf-datacloud/references/feature-readiness.md
• ../sf-datacloud/UPSTREAM.md