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

424 lines
12 KiB
Markdown
Raw Normal View History

feat：提交所有模块基础搭建完成
2026-02-06 09:58:58 +08:00
# 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 名称 |
**成功示例**：
```json
{
"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"
}
}
```
**失败示例**：
```json
{
"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 | 可管理状态 |
**成功示例**：
```json
{
"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"
}
]
}
```
**失败示例**：
```json
{
"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 格式） |
**成功示例**：
```json
{
"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"
}
]
}
```
**失败示例**：
```json
{
"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：描述元数据
**请求**：
```bash
curl -X GET "http://localhost:8080/salesforce/metadata/describe?apiVersion=59.0"
```
**响应**：
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"metadataObjects": [
{
"xmlName": "CustomObject",
"directoryName": "objects",
"suffix": "object",
"inFolder": false,
"metaFile": false
}
],
"serverVersion": "59.0"
}
}
```
### 示例 2：列出元数据（单个查询）
**请求**：
```bash
curl -X POST "http://localhost:8080/salesforce/metadata/list" \
-H "Content-Type: application/json" \
-d '[{"type": "CustomObject"}]'
```
**响应**：
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"fullName": "Account",
"type": "CustomObject",
"createdByName": "Admin User",
"lastModifiedByName": "Admin User"
}
]
}
```
### 示例 3：列出元数据（多个查询，自动分批）
**请求**：
```bash
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：获取查询历史
**请求**：
```bash
curl -X GET "http://localhost:8080/salesforce/metadata/describe/history?operationType=list&limit=5"
```
**响应**：
```json
{
"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 条
## 相关文档
- [需求文档](../requirements/sub/2026-01-28-003-08-描述和列出元数据.md)
- [设计文档](../design/2026-02-03-003-08-描述和列出元数据-设计.md)
- [决策记录](../decisions/2026-02-03-003-08-ADR-描述和列出元数据技术选型.md)
- [变更日志](../changelog/2026-02-06-003-08-changelog.md)
- [复盘文档](../retros/2026-02-06-003-08-retro.md)
- [会话记录](../sessions/2026-02-03-003-08-session.md)
Reference in New Issue Copy Permalink