getting-datacloud-schema

getting-datacloud-schema 技能

概述

此技能使用 SSOT REST API 从 Salesforce Data Cloud 获取数据湖对象（DLO）和数据模型对象（DMO）的架构信息。它可以列出组织中的所有 DLO 或 DMO，也可以获取特定 DLO 或 DMO 的详细架构。

适用场景

• 用户希望查看 Data Cloud 组织中的所有 DLO 或 DMO
• 用户需要特定 DLO 或 DMO 的字段架构
• 用户正在探索 Data Cloud 数据结构
• 用户需要了解 DLO 或 DMO 的字段类型和元数据

前提条件

• 已安装 SF CLI 并通过身份验证连接到目标组织
• 组织已启用 Data Cloud
• 用户拥有适当的 Data Cloud 权限

技能执行

参数

1. org_alias（必填）：SF CLI 组织别名（例如，'afvibe'、'myorg'）
2. dlo_name（可选）：特定 DLO 的开发者名称（例如，'Employee__dll'）
3. dmo_name（可选）：特定 DMO 的开发者名称（例如，'Individual__dlm'）

步骤 1：查找已连接的组织

首先，运行 sf org list，查找已连接的组织，并提取后续所有调用要使用的别名：

sf org list

示例输出：

┌────┬───────┬──────────────────────────┬────────────────────┬───────────┐
│    │ Alias │ Username                 │ Org Id             │ Status    │
├────┼───────┼──────────────────────────┼────────────────────┼───────────┤
│ 🍁 │ myorg │ [email protected] │ 00DKZ00000b80NT2AY │ Connected │
└────┴───────┴──────────────────────────┴────────────────────┴───────────┘

从输出中提取 Alias 值（例如，myorg），并将其用作后续所有调用中的 <org_alias>。使用 --all 查看已过期和已删除的临时组织。

步骤 2：验证 SF CLI 身份验证

进行 API 调用前，请验证组织是否已连接：

sf org display --target-org <org_alias> --json

如果尚未连接，请告知用户运行：

sf org login web --alias <org_alias>

步骤 3a：执行 DLO 架构脚本

Python 脚本已随此技能打包。它们位于与此 SKILL.md 文件相同目录下的 scripts/ 子目录中。请使用该目录的绝对路径——不要使用 ./scripts/，因为它会相对于当前工作目录解析，而非技能目录。

列出所有 DLO：

python3 <skill_dir>/scripts/get_dlo_schema.py <org_alias>

获取特定 DLO 的架构：

python3 <skill_dir>/scripts/get_dlo_schema.py <org_alias> <dlo_name>

步骤 3b：执行 DMO 架构脚本

列出所有 DMO：

python3 <skill_dir>/scripts/get_dmo_schema.py <org_alias>

获取特定 DMO 的架构：

python3 <skill_dir>/scripts/get_dmo_schema.py <org_alias> <dmo_name>

步骤 4：呈现结果

解析结果并以用户易于理解的格式呈现：

对于 DLO 列表：

• 显示 DLO 名称、标签、类别和 ID
• 标明总数
• 突出显示包含数据的 DLO（totalRecords > 0）

对于 DLO 架构：

• 显示基本信息（名称、标签、类别、状态）
• 列出所有字段，包括：
  • 字段名称
  • 数据类型
  • 主键标识
  • 是否可为空
• 突出显示自定义字段（排除 DataSource__c、cdp_sys_* 等系统字段）
• 如果有记录数，则显示记录数

对于 DMO 列表：

• 显示 DMO 名称、标签、类别和 ID
• 标明总数

对于 DMO 架构：

• 显示基本信息（名称、标签、类别、说明）
• 列出所有字段，包括：
  • 字段名称
  • 数据类型
  • 主键标识
  • 是否可为空
• 如果有数据空间信息，则显示该信息

步骤 5：提供后续操作建议

显示结果后，建议相关的后续操作：

• 从 DLO 查询数据
• 创建计算洞察
• 构建细分
• 设置数据流
• 创建 DMO 映射

使用的 API 端点

列出所有 DLO

GET /services/data/v64.0/ssot/data-lake-objects

响应结构：

{
  "dataLakeObjects": [
    {
      "name": "Employee__dll",
      "label": "Employee",
      "category": "Profile",
      "id": "1dlXXXXXXXXXXXXXXX",
      "status": "ACTIVE",
      "totalRecords": 12,
      "fields": [...]
    }
  ],
  "totalSize": 5
}

获取 DLO 架构

GET /services/data/v64.0/ssot/data-lake-objects/{dlo_name}

响应结构（与列表响应中的单个对象相同，但采用分页格式包装）。

列出所有 DMO

GET /services/data/v64.0/ssot/data-model-objects

响应结构：

{
  "dataModelObjects": [
    {
      "name": "Individual__dlm",
      "label": "Individual",
      "category": "Profile",
      "id": "0dmXXXXXXXXXXXXXXX",
      "fields": [...]
    }
  ],
  "totalSize": 10
}

获取 DMO 架构

GET /services/data/v64.0/ssot/data-model-objects/{dmo_name}

响应结构（与列表响应中的单个对象相同，但采用分页格式包装）。

错误处理

常见问题：

1. 组织未连接

   • 消息："Org not connected"
   • 解决方案：请用户通过 SF CLI 完成身份验证

2. 未找到 DLO

   • 消息："DLO 'XYZ__dll' not found"
   • 解决方案：先列出所有 DLO 以确认名称

3. 未找到 DMO

   • 消息："DMO 'XYZ__dlm' not found"
   • 解决方案：先列出所有 DMO 以确认名称

4. 权限问题

   • 消息：HTTP 403 错误
   • 解决方案：确认用户拥有 Data Cloud 权限

5. API 版本不匹配

   • 当前版本：v64.0
   • 解决方案：可更新脚本以使用较新的 API 版本

示例用法

示例 1：列出所有 DLO

User: "Show me all DLOs in afvibe org"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dlo_schema.py afvibe
4. Display formatted list of DLOs

示例 2：获取指定 DLO 的架构

User: "Get the schema for Employee__dll in afvibe"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dlo_schema.py afvibe Employee__dll
4. Display field schema with types and metadata

示例 3：探索 DLO，然后获取架构

User: "What DLOs exist in myorg and show me the schema for the Employee one"

Response:
1. Run sf org list to discover connected org alias
2. List all DLOs in myorg
3. Identify Employee__dll
4. Get detailed schema for Employee__dll
5. Present both results

示例 4：列出所有 DMO

User: "Show me all DMOs in afvibe org"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dmo_schema.py afvibe
4. Display formatted list of DMOs

示例 5：获取指定 DMO 的架构

User: "Get the schema for Individual__dlm in afvibe"

Response:
1. Run sf org list to discover connected org alias
2. Authenticate to afvibe
3. Run: python3 <skill_dir>/scripts/get_dmo_schema.py afvibe Individual__dlm
4. Display field schema with types and metadata

示例 6：探索 DMO，然后获取架构

User: "What DMOs exist in myorg and show me the schema for the Individual one"

Response:
1. Run sf org list to discover connected org alias
2. List all DMOs in myorg
3. Identify Individual__dlm
4. Get detailed schema for Individual__dlm
5. Present both results

输出格式

DLO 列表输出

Found 5 DLOs in org 'afvibe':

1. DataCustomCodeLogs__dll
   Label: DataCustomCodeLogs
   Category: Engagement
   Records: 233

2. Employee__dll
   Label: Employee
   Category: Profile
   Records: 12

[...]

DLO 架构输出

DLO: Employee__dll
Label: Employee
Category: Profile
Status: ACTIVE
Records: 12

Custom Fields:
  • id__c (Text) - Primary Key
  • name__c (Text)
  • position__c (Text)
  • manager_id__c (Number)

System Fields:
  • DataSource__c (Text)
  • InternalOrganization__c (Text)
  • cdp_sys_SourceVersion__c (Text)

Next steps:
- Query data: SELECT * FROM Employee__dll LIMIT 10
- Create segment based on position field
- Set up data stream for real-time updates

DMO 列表输出

Found 10 DMOs in org 'afvibe':

1. Individual__dlm
   Label: Individual
   Category: Profile

2. ContactPointEmail__dlm
   Label: Contact Point Email
   Category: Profile

[...]

DMO 架构输出

DMO: Individual__dlm
Label: Individual
Category: Profile
Description: Represents an individual person

Fields:
  • Id__c (Text) - Primary Key
  • FirstName__c (Text)
  • LastName__c (Text)
  • BirthDate__c (DateTime)

Next steps:
- Query data: SELECT * FROM Individual__dlm LIMIT 10
- View DLO mappings to this DMO
- Create calculated insights

注意事项

• DLO 名称始终以 __dll 后缀结尾
• DMO 名称始终以 __dlm 后缀结尾
• 字段名称始终以 __c 后缀结尾
• 系统字段（DataSource__c、KQ_、cdp_sys_）会自动添加
• DLO 和 DMO 查询必须包含主键字段
• API 支持对大型结果集进行分页（limit/offset）

相关技能

• datakit_workflow：用于 DMO 映射操作
• datakit_validation：用于验证 datakit 配置
• 创建 DMO 映射前，请先使用此技能了解源 DLO 结构