data360-connect

data360-connect：Data Cloud 连接阶段

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

此技能负责的任务

以下工作请使用 data360-connect：

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

以下工作请委派给其他技能：

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

---

首先收集所需上下文

询问或推断：

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

---

核心操作规则

• 首先验证插件运行时；请参阅 ../data360-orchestrate/references/plugin-setup.md。
• 修改连接前，先运行共享就绪状态分类器：node ../data360-orchestrate/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 ../data360-orchestrate/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>

---

参考资料

• 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
• ../data360-orchestrate/references/plugin-setup.md
• ../data360-orchestrate/references/feature-readiness.md