kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
39d1595e0b
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-02-005-api.md

19 KiB
Raw Blame History

API 文档 - 描述功能

元数据

  • 需求编号：001-05
  • 创建时间：2026-02-02
  • 创建人：AI Assistant
  • 版本号：v1.0.0
  • 关联需求：描述功能

API 概述

描述功能 API 提供了对 Salesforce 对象元数据的查询能力，包括获取所有可用对象列表、获取对象详细定义、获取对象布局信息、获取标签页信息、获取快速操作信息等。这些 API 可以帮助开发人员了解 Salesforce 对象的结构和属性，为数据操作和界面开发提供支持。

接口列表

1. 描述所有可用对象

接口说明

获取 Salesforce 组织中所有用户有权限访问的对象列表。

  • 接口名称：DescribeGlobal
  • 请求方式：GET
  • 请求路径：/partner/describe/global
  • 权限要求：@PreAuthorize("@ss.hasLogin()")

请求参数

无

响应参数

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据
data.encoding String 编码格式
data.maxBatchSize Integer 最大批处理大小
data.sobjects Array 对象列表
data.sobjects[].activateable Boolean 是否可激活
data.sobjects[].createable Boolean 是否可创建
data.sobjects[].custom Boolean 是否自定义对象
data.sobjects[].customSetting Boolean 是否自定义设置
data.sobjects[].deletable Boolean 是否可删除
data.sobjects[].deprecatedAndHidden Boolean 是否已弃用并隐藏
data.sobjects[].feedEnabled Boolean 是否启用 Feed
data.sobjects[].hasSubtypes Boolean 是否有子类型
data.sobjects[].isSubtype Boolean 是否为子类型
data.sobjects[].keyPrefix String 键前缀
data.sobjects[].label String 对象标签
data.sobjects[].labelPlural String 对象复数标签
data.sobjects[].layoutable Boolean 是否有布局
data.sobjects[].mergeable Boolean 是否可合并
data.sobjects[].mruEnabled Boolean 是否启用 MRU
data.sobjects[].name String 对象名称
data.sobjects[].queryable Boolean 是否可查询
data.sobjects[].replicateable Boolean 是否可复制
data.sobjects[].retrieveable Boolean 是否可检索
data.sobjects[].searchable Boolean 是否可搜索
data.sobjects[].triggerable Boolean 是否可触发
data.sobjects[].undeletable Boolean 是否可恢复
data.sobjects[].updateable Boolean 是否可更新
data.sobjects[].urls Object 对象 URL 集合

成功示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "encoding": "UTF-8",
    "maxBatchSize": 200,
    "sobjects": [
      {
        "activateable": false,
        "createable": true,
        "custom": false,
        "customSetting": false,
        "deletable": true,
        "deprecatedAndHidden": false,
        "feedEnabled": true,
        "hasSubtypes": false,
        "isSubtype": false,
        "keyPrefix": "001",
        "label": "客户",
        "labelPlural": "客户",
        "layoutable": true,
        "mergeable": true,
        "mruEnabled": true,
        "name": "Account",
        "queryable": true,
        "replicateable": true,
        "retrieveable": true,
        "searchable": true,
        "triggerable": true,
        "undeletable": true,
        "updateable": true,
        "urls": {
          "rowTemplate": "/services/data/v65.0/sobjects/Account/{ID}",
          "describe": "/services/data/v65.0/sobjects/Account/describe",
          "sobject": "/services/data/v65.0/sobjects/Account"
        }
      }
    ]
  }
}

失败示例

{
  "code": 500,
  "msg": "获取对象列表失败：连接超时"
}

2. 描述特定对象

接口说明

获取指定 Salesforce 对象的详细元数据信息，包括字段定义、子对象、记录类型等。

  • 接口名称：DescribeSObject
  • 请求方式：POST
  • 请求路径：/partner/describe/sobject
  • 权限要求：@PreAuthorize("@ss.hasLogin()")

请求参数

参数名 类型 必填 说明
objectType String 是 对象类型（如 Account、Contact 等）

请求示例

{
  "objectType": "Account"
}

响应参数

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据
data.activateable Boolean 是否可激活
data.childRelationships Array 子对象关系列表
data.createable Boolean 是否可创建
data.custom Boolean 是否自定义对象
data.deletable Boolean 是否可删除
data.deprecatedAndHidden Boolean 是否已弃用并隐藏
data.feedEnabled Boolean 是否启用 Feed
data.fields Array 字段定义列表
data.fields[].autoNumber Boolean 是否自动编号
data.fields[].byteLength Integer 字节长度
data.fields[].calculated Boolean 是否计算字段
data.fields[].caseSensitive Boolean 是否区分大小写
data.fields[].createable Boolean 是否可创建
data.fields[].custom Boolean 是否自定义字段
data.fields[].defaultedOnCreate Boolean 创建时是否有默认值
data.fields[].deprecatedAndHidden Boolean 是否已弃用并隐藏
data.fields[].digits Integer 数字位数
data.fields[].externalId Boolean 是否为外部 ID
data.fields[].filterable Boolean 是否可过滤
data.fields[].groupable Boolean 是否可分组
data.fields[].idLookup Boolean 是否可用于 ID 查找
data.fields[].label String 字段标签
data.fields[].length Integer 字段长度
data.fields[].name String 字段名称
data.fields[].nameField Boolean 是否为名称字段
data.fields[].nillable Boolean 是否可为空
data.fields[].picklistValues Array 选项值列表（Picklist 字段）
data.fields[].precision Integer 精度
data.fields[].referenceTo Array 引用对象列表（关系字段）
data.fields[].relationshipName String 关系名称
data.fields[].required Boolean 是否必填
data.fields[].scale Integer 小数位数
data.fields[].soapType String SOAP 类型
data.fields[].sortable Boolean 是否可排序
data.fields[].type String 字段类型
data.fields[].unique Boolean 是否唯一
data.fields[].updateable Boolean 是否可更新
data.keyPrefix String 键前缀
data.label String 对象标签
data.labelPlural String 对象复数标签
data.layoutable Boolean 是否有布局
data.mergeable Boolean 是否可合并
data.mruEnabled Boolean 是否启用 MRU
data.name String 对象名称
data.queryable Boolean 是否可查询
data.recordTypeInfos Array 记录类型信息列表
data.replicateable Boolean 是否可复制
data.retrieveable Boolean 是否可检索
data.searchable Boolean 是否可搜索
data.triggerable Boolean 是否可触发
data.undeletable Boolean 是否可恢复
data.updateable Boolean 是否可更新
data.urls Object 对象 URL 集合

成功示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "activateable": false,
    "childRelationships": [...],
    "createable": true,
    "custom": false,
    "deletable": true,
    "deprecatedAndHidden": false,
    "feedEnabled": true,
    "fields": [
      {
        "autoNumber": false,
        "byteLength": 18,
        "calculated": false,
        "caseSensitive": false,
        "createable": false,
        "custom": false,
        "defaultedOnCreate": false,
        "deprecatedAndHidden": false,
        "digits": 0,
        "externalId": false,
        "filterable": true,
        "groupable": true,
        "idLookup": true,
        "label": "客户 ID",
        "length": 18,
        "name": "Id",
        "nameField": false,
        "nillable": false,
        "precision": 0,
        "required": true,
        "scale": 0,
        "soapType": "tns:ID",
        "sortable": true,
        "type": "id",
        "unique": false,
        "updateable": false
      }
    ],
    "keyPrefix": "001",
    "label": "客户",
    "labelPlural": "客户",
    "layoutable": true,
    "mergeable": true,
    "mruEnabled": true,
    "name": "Account",
    "queryable": true,
    "recordTypeInfos": [...],
    "replicateable": true,
    "retrieveable": true,
    "searchable": true,
    "triggerable": true,
    "undeletable": true,
    "updateable": true,
    "urls": {...}
  }
}

失败示例

{
  "code": 500,
  "msg": "描述对象失败：对象类型 'InvalidObject' 不存在"
}

3. 描述多个对象

接口说明

批量获取多个 Salesforce 对象的元数据信息，最多支持 100 个对象。

  • 接口名称：DescribeSObjects
  • 请求方式：POST
  • 请求路径：/partner/describe/sobjects
  • 权限要求：@PreAuthorize("@ss.hasLogin()")

请求参数

参数名 类型 必填 说明
objectTypes Array 是 对象类型列表，最多 100 个
objectTypes[] String 是 对象类型（如 Account、Contact 等）

请求示例

{
  "objectTypes": ["Account", "Contact", "Opportunity"]
}

响应参数

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Array 对象描述结果列表
data[] Object 单个对象的描述结果（同 DescribeSObject 的 data）

成功示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "name": "Account",
      "label": "客户",
      "fields": [...]
    },
    {
      "name": "Contact",
      "label": "联系人",
      "fields": [...]
    },
    {
      "name": "Opportunity",
      "label": "业务机会",
      "fields": [...]
    }
  ]
}

失败示例

{
  "code": 500,
  "msg": "批量描述对象失败：对象类型列表不能为空"
}

4. 描述对象布局

接口说明

获取指定 Salesforce 对象的页面布局信息，包括字段布局、按钮布局、相关列表等。

  • 接口名称：DescribeLayout
  • 请求方式：POST
  • 请求路径：/partner/describe/layout
  • 权限要求：@PreAuthorize("@ss.hasLogin()")

请求参数

参数名 类型 必填 说明
objectType String 是 对象类型（如 Account、Contact 等）
recordTypeId String 否 记录类型 ID，不传则返回默认布局

请求示例

{
  "objectType": "Account",
  "recordTypeId": "012000000000000AAA"
}

响应参数

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据
data.id String 布局 ID
data.buttonLayoutSection Object 按钮布局部分
data.detailLayoutSections Array 详情布局部分列表
data.editLayoutSections Array 编辑布局部分列表
data.quickActionList Object 快速操作列表
data.relatedLists Array 相关列表
data.relatedLists[].columns Array 列定义
data.relatedLists[].custom Boolean 是否自定义
data.relatedLists[].field String 字段名称
data.relatedLists[].label String 标签
data.relatedLists[].limitRows Integer 行数限制
data.relatedLists[].name String 名称
data.relatedLists[].sobject String 关联对象
data.relatedLists[].sort Array 排序定义

成功示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "00h000000000000",
    "buttonLayoutSection": {...},
    "detailLayoutSections": [...],
    "editLayoutSections": [...],
    "quickActionList": {...},
    "relatedLists": [
      {
        "columns": [...],
        "custom": false,
        "field": "AccountId",
        "label": "联系人",
        "limitRows": 5,
        "name": "Contacts",
        "sobject": "Contact",
        "sort": [...]
      }
    ]
  }
}

失败示例

{
  "code": 500,
  "msg": "描述布局失败：对象类型 'InvalidObject' 不存在"
}

5. 描述标签页

接口说明

获取 Salesforce 组织中所有用户可见的标签页列表。

  • 接口名称：DescribeTabs
  • 请求方式：GET
  • 请求路径：/partner/describe/tabs
  • 权限要求：@PreAuthorize("@ss.hasLogin()")

请求参数

无

响应参数

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Array 标签页列表
data[].colors Array 颜色定义列表
data[].custom Boolean 是否自定义
data[].iconUrl String 图标 URL
data[].icons Array 图标定义列表
data[].label String 标签
data[].miniIconUrl String 小图标 URL
data[].name String 名称
data[].sobjectName String 关联对象名称
data[].url String URL

成功示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "colors": [
        {
          "color": "0070D1",
          "context": "primary",
          "theme": "theme4"
        }
      ],
      "custom": false,
      "iconUrl": "https://example.com/img/icon/accounts32.png",
      "icons": [...],
      "label": "客户",
      "miniIconUrl": "https://example.com/img/icon/accounts16.png",
      "name": "standard-Account",
      "sobjectName": "Account",
      "url": "/001/o"
    }
  ]
}

失败示例

{
  "code": 500,
  "msg": "获取标签页失败：连接超时"
}

6. 描述快速操作

接口说明

获取指定 Salesforce 对象的快速操作定义信息，包括字段列表、布局信息等。

  • 接口名称：DescribeQuickActions
  • 请求方式：POST
  • 请求路径：/partner/describe/quick-actions
  • 权限要求：@PreAuthorize("@ss.hasLogin()")

请求参数

参数名 类型 必填 说明
actionNames Array 是 快速操作名称列表
actionNames[] String 是 快速操作名称（如 Account.NewContact 等）

请求示例

{
  "actionNames": ["Account.NewContact", "Account.NewOpportunity"]
}

响应参数

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Array 快速操作定义列表
data[].actionEnumOrId String 操作枚举或 ID
data[].canvasEnabled Boolean 是否启用 Canvas
data[].colors Array 颜色定义列表
data[].contextSobjectType String 上下文对象类型
data[].defaultValues Object 默认值
data[].flowDevName String 流程开发名称
data[].flowRecordIdVar String 流程记录 ID 变量
data[].height Integer 高度
data[].iconUrl String 图标 URL
data[].icons Array 图标定义列表
data[].label String 标签
data[].layout Object 布局定义
data[].layout.layoutItems Array 布局项列表
data[].lightningComponentBundleId String Lightning 组件包 ID
data[].lightningComponentBundleName String Lightning 组件包名称
data[].lightningComponentQualifiedName String Lightning 组件限定名称
data[].miniIconUrl String 小图标 URL
data[].name String 名称
data[].showQuickActionLcHeader Boolean 是否显示快速操作 LC 头部
data[].showQuickActionVfHeader Boolean 是否显示快速操作 VF 头部
data[].targetParentField String 目标父字段
data[].targetRecordTypeId String 目标记录类型 ID
data[].targetSobjectType String 目标对象类型
data[].type String 类型
data[].visualforcePageName String Visualforce 页面名称
data[].visualforcePageUrl String Visualforce 页面 URL
data[].width Integer 宽度

成功示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "actionEnumOrId": "Account.NewContact",
      "canvasEnabled": false,
      "colors": [...],
      "contextSobjectType": "Account",
      "defaultValues": {...},
      "height": 0,
      "iconUrl": "https://example.com/img/icon/newcontact32.png",
      "icons": [...],
      "label": "新建联系人",
      "layout": {
        "layoutItems": [...]
      },
      "miniIconUrl": "https://example.com/img/icon/newcontact16.png",
      "name": "NewContact",
      "showQuickActionLcHeader": false,
      "showQuickActionVfHeader": false,
      "targetParentField": "AccountId",
      "targetSobjectType": "Contact",
      "type": "Create",
      "width": 0
    }
  ]
}

失败示例

{
  "code": 500,
  "msg": "描述快速操作失败：快速操作名称列表不能为空"
}

错误码

错误码 说明 处理建议
200 操作成功 无需处理
400 请求参数错误 检查请求参数是否符合要求
401 未授权 检查用户是否已登录
403 无权限 检查用户是否有权限访问该资源
404 资源不存在 检查对象类型、记录类型 ID 等是否正确
500 服务器内部错误 查看错误消息，检查 Salesforce 连接是否正常
503 服务不可用 Salesforce 服务暂时不可用，稍后重试

通用错误响应格式

{
  "code": 500,
  "msg": "错误描述信息",
  "data": null
}

注意事项

1. DescribeGlobal 限制

  • 返回所有用户有权限访问的对象
  • 不包含系统内部对象
  • 结果按对象名称字母顺序排序

2. DescribeSObject 限制

  • 只返回用户有权限查看的字段
  • 包含字段的详细元数据信息
  • 支持递归获取子对象信息

3. DescribeSObjects 限制

  • 最多支持 100 个对象同时描述
  • 批量 API 提高效率
  • 部分失败时返回成功和失败的结果

4. DescribeLayout 限制

  • 需要指定对象类型
  • 可选指定记录类型
  • 返回所有布局类型（编辑、详情等）

5. DescribeTabs 限制

  • 返回所有用户可见的标签页
  • 包含自定义标签页
  • 按显示顺序排序

6. DescribeQuickActions 限制

  • 支持按对象类型过滤
  • 返回快速操作的完整定义
  • 包含字段和布局信息

相关文档

版本历史

版本号 日期 变更内容 作者
v1.0.0 2026-02-02 初始版本，实现六个核心描述功能 API AI Assistant