kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop_20260203
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-06-003-08-api.md

12 KiB
Raw Permalink Blame History

API 文档 - 描述和列出元数据

元数据

  • 需求编号：003-08
  • 需求名称：描述和列出元数据
  • 创建时间：2026-02-06
  • 创建人：AI Assistant
  • 状态：已完成

API 概述

本文档描述了"描述和列出元数据"功能的 REST API 接口。该功能基于 Salesforce Metadata API，提供了以下核心能力：

  1. 描述元数据（DescribeMetadata）：获取当前 Salesforce Org 支持的所有元数据类型信息
  2. 列出元数据（ListMetadata）：获取指定元数据类型下的具体成员列表，支持分批处理
  3. 查询历史（History Query）：查询元数据操作的执行历史，支持审计和追溯

基础信息

  • 基础路径：/salesforce/metadata
  • Content-Type：application/json
  • 认证方式：基于 Session 的认证（通过 MetadataConnectionFactory 管理）

接口列表

接口 1：描述元数据

功能描述：获取当前 Salesforce Org 支持的所有元数据类型信息，包括元数据对象的类型、目录、子类型等详细信息。

请求方式：GET

请求路径：/salesforce/metadata/describe

请求参数：

参数名 类型 必填 说明
apiVersion Double 否 API 版本号，如 59.0。如果不传，使用 Salesforce 默认版本

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 描述元数据结果（DescribeMetadataResult）

DescribeMetadataResult 结构：

参数名 类型 说明
metadataObjects Array 元数据对象列表（DescribeMetadataObject[]）
metadataObjectsWithMns Array 带命名空间的元数据对象列表（DescribeMetadataObject[]）
namespacePrefix String 命名空间前缀
serverVersion String 服务器版本

DescribeMetadataObject 结构：

参数名 类型 说明
childXmlNames Array 子 XML 名称列表（String[]）
directoryName String 目录名称
inFolder Boolean 是否在文件夹中
metaFile Boolean 是否有元文件
suffix String 文件后缀
xmlName String XML 名称

成功示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "metadataObjects": [
      {
        "childXmlNames": [],
        "directoryName": "objects",
        "inFolder": false,
        "metaFile": false,
        "suffix": "object",
        "xmlName": "CustomObject"
      },
      {
        "childXmlNames": [],
        "directoryName": "classes",
        "inFolder": false,
        "metaFile": true,
        "suffix": "cls",
        "xmlName": "ApexClass"
      }
    ],
    "metadataObjectsWithMns": [],
    "namespacePrefix": null,
    "serverVersion": "59.0"
  }
}

失败示例：

{
  "code": 500,
  "msg": "列出元数据失败: 连接超时",
  "data": null
}

错误码：

  • DESCRIBE_001：获取 Metadata 连接失败
  • DESCRIBE_002：描述元数据失败
  • DESCRIBE_008：未知错误

接口 2：列出元数据

功能描述：获取指定元数据类型（及文件夹）下的具体元数据成员列表。支持批量查询，Service 层会自动分批处理（每次最多 3 个查询）。

请求方式：POST

请求路径：/salesforce/metadata/list

请求参数：

参数名 类型 必填 说明
queries Array 是 查询列表（ListMetadataQuery[]），至少包含一个查询

ListMetadataQuery 结构：

参数名 类型 必填 说明
type String 是 元数据类型，如 "CustomObject", "ApexClass", "ApexTrigger" 等
folder String 否 文件夹名称，用于查询文件夹内的元数据（如文档、报表等）

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Array 列出元数据结果列表（ListMetadataResult[]）

ListMetadataResult 结构：

参数名 类型 说明
fullName String 完整名称
type String 类型
createdById String 创建者 ID
createdByName String 创建者名称
createdDate String 创建日期（ISO 8601 格式）
lastModifiedById String 最后修改者 ID
lastModifiedByName String 最后修改者名称
lastModifiedDate String 最后修改日期（ISO 8601 格式）
manageableState String 可管理状态

成功示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "fullName": "Account",
      "type": "CustomObject",
      "createdById": "005xx000001X9YZAA0",
      "createdByName": "Admin User",
      "createdDate": "2023-01-15T08:30:00.000Z",
      "lastModifiedById": "005xx000001X9YZAA0",
      "lastModifiedByName": "Admin User",
      "lastModifiedDate": "2023-06-20T14:22:00.000Z",
      "manageableState": "unmanaged"
    },
    {
      "fullName": "Contact",
      "type": "CustomObject",
      "createdById": "005xx000001X9YZAA0",
      "createdByName": "Admin User",
      "createdDate": "2023-01-15T08:35:00.000Z",
      "lastModifiedById": "005xx000001X9YZAA0",
      "lastModifiedByName": "Admin User",
      "lastModifiedDate": "2023-06-20T14:25:00.000Z",
      "manageableState": "unmanaged"
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "查询列表不能为空",
  "data": null
}

错误码：

  • DESCRIBE_003：参数校验失败（查询列表为空、元数据类型为空等）
  • DESCRIBE_006：列出元数据失败
  • DESCRIBE_008：未知错误

接口 3：获取元数据查询历史

功能描述：查询元数据描述和列出操作的执行历史，支持按操作类型筛选和限制返回数量。

请求方式：GET

请求路径：/salesforce/metadata/describe/history

请求参数：

参数名 类型 必填 说明
operationType String 是 操作类型，可选值："describe"（描述元数据）、"list"（列出元数据）
limit Integer 否 返回数量限制，默认 10，最大 100

响应参数：

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Array 查询历史列表（DataiMetadataDescribe[]）

DataiMetadataDescribe 结构：

参数名 类型 说明
id Long 记录 ID
operationType String 操作类型（describe/list）
queryContent String 查询内容（JSON 格式）
resultCount Integer 结果数量
status String 状态（Success/Failed）
errorMessage String 错误信息
serverVersion String 服务器版本
namespacePrefix String 命名空间前缀
metadataObjectCount Integer 元数据对象数量
queryTime String 查询时间（ISO 8601 格式）
createTime String 创建时间（ISO 8601 格式）

成功示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "operationType": "describe",
      "queryContent": null,
      "resultCount": null,
      "status": "Success",
      "errorMessage": null,
      "serverVersion": "59.0",
      "namespacePrefix": null,
      "metadataObjectCount": 250,
      "queryTime": "2026-02-06T10:30:00.000+08:00",
      "createTime": "2026-02-06T10:30:00.000+08:00"
    },
    {
      "id": 2,
      "operationType": "list",
      "queryContent": "[{\"type\":\"CustomObject\"}]",
      "resultCount": 50,
      "status": "Success",
      "errorMessage": null,
      "serverVersion": null,
      "namespacePrefix": null,
      "metadataObjectCount": null,
      "queryTime": "2026-02-06T10:35:00.000+08:00",
      "createTime": "2026-02-06T10:35:00.000+08:00"
    }
  ]
}

失败示例：

{
  "code": 500,
  "msg": "无效的操作类型，必须是 describe 或 list",
  "data": null
}

错误码：

  • DESCRIBE_003：参数校验失败（无效的操作类型）
  • DESCRIBE_008：未知错误

错误码列表

错误码 错误信息 说明
DESCRIBE_001 获取 Metadata 连接失败 无法获取 Salesforce Metadata 连接，可能是认证失败或网络问题
DESCRIBE_002 描述元数据失败 调用 Salesforce describeMetadata API 失败
DESCRIBE_003 参数校验失败 请求参数不符合要求（如查询列表为空、元数据类型为空、无效的操作类型等）
DESCRIBE_004 记录查询历史失败 写入数据库失败
DESCRIBE_005 获取查询历史失败 从数据库查询历史记录失败
DESCRIBE_006 列出元数据失败 调用 Salesforce listMetadata API 失败
DESCRIBE_007 记录列出元数据历史失败 写入数据库失败
DESCRIBE_008 未知错误 其他未预期的错误

使用示例

示例 1：描述元数据

请求：

curl -X GET "http://localhost:8080/salesforce/metadata/describe?apiVersion=59.0"

响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "metadataObjects": [
      {
        "xmlName": "CustomObject",
        "directoryName": "objects",
        "suffix": "object",
        "inFolder": false,
        "metaFile": false
      }
    ],
    "serverVersion": "59.0"
  }
}

示例 2：列出元数据（单个查询）

请求：

curl -X POST "http://localhost:8080/salesforce/metadata/list" \
  -H "Content-Type: application/json" \
  -d '[{"type": "CustomObject"}]'

响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "fullName": "Account",
      "type": "CustomObject",
      "createdByName": "Admin User",
      "lastModifiedByName": "Admin User"
    }
  ]
}

示例 3：列出元数据（多个查询，自动分批）

请求：

curl -X POST "http://localhost:8080/salesforce/metadata/list" \
  -H "Content-Type: application/json" \
  -d '[
    {"type": "CustomObject"},
    {"type": "ApexClass"},
    {"type": "ApexTrigger"},
    {"type": "VisualforcePage"}
  ]'

说明：虽然请求包含 4 个查询，但 Service 层会自动分批处理（每次最多 3 个），对调用方透明。

示例 4：获取查询历史

请求：

curl -X GET "http://localhost:8080/salesforce/metadata/describe/history?operationType=list&limit=5"

响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "operationType": "list",
      "queryContent": "[{\"type\":\"CustomObject\"}]",
      "resultCount": 50,
      "status": "Success",
      "queryTime": "2026-02-06T10:30:00.000+08:00"
    }
  ]
}

注意事项

  1. 分批处理：listMetadata 接口支持批量查询，但 Salesforce API 限制每次调用最多包含 3 个查询。Service 层会自动分批处理，对调用方透明。

  2. 查询历史：每次 describeMetadata 和 listMetadata 操作都会自动记录到数据库，包括操作类型、查询内容、结果数量、状态等信息。

  3. 错误处理：所有接口都遵循统一的错误处理规范，返回包含错误码和错误信息的 JSON 响应。

  4. 性能考虑：

    • describeMetadata 操作会返回大量元数据类型信息，建议在应用启动时缓存结果
    • listMetadata 操作涉及外部 API 调用，响应时间取决于查询的复杂度和数据量
    • 查询历史接口默认返回 10 条记录，最大支持 100 条

相关文档