kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-01-30-003-api.md

552 lines
16 KiB
Markdown
Raw Permalink Normal View History

【feat】 初始化所有模块，提交partner模块初始实现
2026-02-02 16:12:25 +08:00
# API 文档 - 批量操作
## 元数据
- 需求编号：001-03
- 创建时间：2026-01-30
- 创建人：AI Assistant
- 版本号：v1.0.0
- 模块：datai-salesforce-partner
## API 概述
批量操作 API 提供对 Salesforce 记录进行批量操作的能力，支持批量创建、批量更新、批量删除、批量 Upsert 四个核心操作。
### 核心特性
- 支持最多 1000 条记录
- 自动分批处理（每批最多 200 条）
- 支持部分失败情况
- 提供详细的成功/失败统计
- 支持 AllOrNoneHeader 控制
- 使用 DisableFeedTrackingHeader 提高性能
- 批次间休眠时间可配置
### 基础信息
- **Base URL**：`/partner/batch`
- **认证方式**：JWT Token（通过 Authorization Header 传递）
- **权限要求**：需要登录权限（`@PreAuthorize("@ss.hasLogin()")`）
- **Content-Type**：`application/json`
## 接口列表
### 1. 批量创建记录
#### 接口说明
批量创建 Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。
#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/create`
- **权限要求**：`@ss.hasLogin()`
#### 请求参数
**Body 参数**：
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| records | List<Map<String, Object>> | 是 | 记录列表，最多 1000 条 | [{"Name": "Test Account"}] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |
#### 响应参数
**成功响应**（HTTP 200）：
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量创建成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |
**失败响应**（HTTP 200，业务失败）：
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量创建部分失败" |
| data | Object | 响应数据（包含失败详情） | - |
**错误响应**（HTTP 500）：
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 500 |
| msg | String | 错误信息 | "批量创建记录失败: ..." |
#### 请求示例
```json
{
"objectType": "Account",
"records": [
{
"Name": "Test Account 1",
"BillingCity": "San Francisco"
},
{
"Name": "Test Account 2",
"BillingCity": "New York"
}
],
"allOrNone": false,
"sleepTime": 100
}
```
#### 响应示例
**成功示例**：
```json
{
"code": 200,
"msg": "批量创建成功",
"data": {
"success": true,
"successCount": 2,
"failureCount": 0,
"totalCount": 2,
"results": [
{
"success": true,
"id": "001xx000003GWFjAAO",
"errors": [],
"index": 0
},
{
"success": true,
"id": "001xx000003GWFkAAP",
"errors": [],
"index": 1
}
]
}
}
```
**部分失败示例**：
```json
{
"code": 200,
"msg": "批量创建部分失败",
"data": {
"success": false,
"successCount": 1,
"failureCount": 1,
"totalCount": 2,
"results": [
{
"success": true,
"id": "001xx000003GWFjAAO",
"errors": [],
"index": 0
},
{
"success": false,
"id": null,
"errors": [
{
"statusCode": "REQUIRED_FIELD_MISSING",
"message": "Required fields are missing: [Name]",
"fields": ["Name"]
}
],
"index": 1
}
]
}
}
```
---
### 2. 批量更新记录
#### 接口说明
批量更新 Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。每条记录必须包含 `id` 字段。
#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/update`
- **权限要求**：`@ss.hasLogin()`
#### 请求参数
**Body 参数**：
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| records | List<Map<String, Object>> | 是 | 记录列表，每条记录必须包含 id，最多 1000 条 | [{"id": "001xx...", "Name": "Updated"}] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |
#### 响应参数
**成功响应**（HTTP 200）：
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量更新成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |
#### 请求示例
```json
{
"objectType": "Account",
"records": [
{
"id": "001xx000003GWFjAAO",
"Name": "Updated Account 1",
"BillingCity": "Los Angeles"
},
{
"id": "001xx000003GWFkAAP",
"Name": "Updated Account 2",
"BillingCity": "Chicago"
}
],
"allOrNone": false,
"sleepTime": 100
}
```
#### 响应示例
**成功示例**：
```json
{
"code": 200,
"msg": "批量更新成功",
"data": {
"success": true,
"successCount": 2,
"failureCount": 0,
"totalCount": 2,
"results": [
{
"success": true,
"id": "001xx000003GWFjAAO",
"errors": [],
"index": 0
},
{
"success": true,
"id": "001xx000003GWFkAAP",
"errors": [],
"index": 1
}
]
}
}
```
---
### 3. 批量删除记录
#### 接口说明
批量删除 Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。
#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/delete`
- **权限要求**：`@ss.hasLogin()`
#### 请求参数
**Body 参数**：
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| ids | List<String> | 是 | 记录 ID 列表，最多 1000 条 | ["001xx...", "001xx..."] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |
#### 响应参数
**成功响应**（HTTP 200）：
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量删除成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |
#### 请求示例
```json
{
"objectType": "Account",
"ids": [
"001xx000003GWFjAAO",
"001xx000003GWFkAAP"
],
"allOrNone": false,
"sleepTime": 100
}
```
#### 响应示例
**成功示例**：
```json
{
"code": 200,
"msg": "批量删除成功",
"data": {
"success": true,
"successCount": 2,
"failureCount": 0,
"totalCount": 2,
"results": [
{
"success": true,
"id": "001xx000003GWFjAAO",
"errors": [],
"index": 0
},
{
"success": true,
"id": "001xx000003GWFkAAP",
"errors": [],
"index": 1
}
]
}
}
```
---
### 4. 批量 Upsert 记录
#### 接口说明
批量 Upsert（更新或插入）Salesforce 记录，支持最多 1000 条记录，自动分批处理（每批最多 200 条）。根据指定的外部 ID 字段，如果记录存在则更新，不存在则创建。
#### 请求信息
- **请求方式**：POST
- **请求路径**：`/partner/batch/upsert`
- **权限要求**：`@ss.hasLogin()`
#### 请求参数
**Body 参数**：
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| objectType | String | 是 | 对象类型 | "Account" |
| externalIdField | String | 是 | 外部 ID 字段 | "ExternalId__c" |
| records | List<Map<String, Object>> | 是 | 记录列表，每条记录必须包含外部 ID 字段，最多 1000 条 | [{"ExternalId__c": "EXT001", "Name": "Test"}] |
| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false |
| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 |
#### 响应参数
**成功响应**（HTTP 200）：
| 参数名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| code | Integer | 状态码 | 200 |
| msg | String | 提示信息 | "批量 Upsert 成功" |
| data | Object | 响应数据 | - |
| data.success | Boolean | 是否全部成功 | true |
| data.successCount | Integer | 成功数量 | 100 |
| data.failureCount | Integer | 失败数量 | 0 |
| data.createdCount | Integer | 创建数量 | 50 |
| data.updatedCount | Integer | 更新数量 | 50 |
| data.totalCount | Integer | 总数量 | 100 |
| data.results | List | 结果列表 | - |
| data.results[].success | Boolean | 单项是否成功 | true |
| data.results[].id | String | 记录 ID | "001xx000003GWFjAAO" |
| data.results[].created | Boolean | 是否创建（true 创建，false 更新） | true |
| data.results[].errors | List | 错误列表 | [] |
| data.results[].index | Integer | 索引 | 0 |
#### 请求示例
```json
{
"objectType": "Account",
"externalIdField": "ExternalId__c",
"records": [
{
"ExternalId__c": "EXT001",
"Name": "Upsert Account 1",
"BillingCity": "Seattle"
},
{
"ExternalId__c": "EXT002",
"Name": "Upsert Account 2",
"BillingCity": "Boston"
}
],
"allOrNone": false,
"sleepTime": 100
}
```
#### 响应示例
**成功示例**：
```json
{
"code": 200,
"msg": "批量 Upsert 成功",
"data": {
"success": true,
"successCount": 2,
"failureCount": 0,
"createdCount": 1,
"updatedCount": 1,
"totalCount": 2,
"results": [
{
"success": true,
"id": "001xx000003GWFjAAO",
"created": true,
"errors": [],
"index": 0
},
{
"success": true,
"id": "001xx000003GWFkAAP",
"created": false,
"errors": [],
"index": 1
}
]
}
}
```
---
## 错误码
### 系统错误码
| 错误码 | 错误消息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| 200 | 操作成功 | 请求处理成功 | - |
| 500 | 操作失败 | 服务器内部错误 | 检查服务器日志，联系管理员 |
| 401 | 未授权 | 用户未登录或 Token 无效 | 重新登录获取 Token |
| 403 | 禁止访问 | 用户没有权限执行该操作 | 检查用户权限配置 |
### 业务错误码
| 错误码 | 错误消息 | 说明 | 解决方案 |
|--------|----------|------|----------|
| INVALID_OBJECT_TYPE | 无效的对象类型 | 对象类型不存在或无权限访问 | 检查对象类型名称是否正确 |
| INVALID_RECORD_ID | 无效的记录 ID | 记录 ID 格式不正确或记录不存在 | 检查记录 ID 是否正确 |
| INVALID_FIELD_NAME | 无效的字段名称 | 字段名称不存在或无权限访问 | 检查字段名称是否正确 |
| INVALID_FIELD_VALUE | 无效的字段值 | 字段值不符合要求 | 检查字段值是否符合要求 |
| MISSING_REQUIRED_FIELD | 缺少必填字段 | 缺少必填字段的值 | 补充必填字段的值 |
| MISSING_RECORD_ID | 缺少记录 ID | Update 操作必须提供记录 ID | 在记录中添加 id 字段 |
| MISSING_EXTERNAL_ID | 缺少外部 ID | Upsert 操作必须提供外部 ID 字段 | 在记录中添加外部 ID 字段 |
| DUPLICATE_VALUE | 重复值 | 字段值已存在，违反唯一性约束 | 检查字段值是否重复 |
| RECORD_LOCKED | 记录已锁定 | 记录被其他用户锁定 | 等待其他用户释放锁定 |
| INSUFFICIENT_PERMISSIONS | 权限不足 | 当前用户没有执行该操作的权限 | 检查用户权限配置 |
| ENTITY_IS_DELETED | 记录已删除 | 记录已被删除 | 检查记录是否存在 |
| BATCH_SIZE_EXCEEDED | 批量大小超出限制 | 单次批量操作最多支持 1000 条记录 | 减少记录数量 |
| OPERATION_FAILED | 操作失败 | 操作执行失败 | 检查错误详情 |
### Salesforce API 错误码
| 错误码 | 说明 |
|--------|------|
| REQUIRED_FIELD_MISSING | 缺少必填字段 |
| INVALID_FIELD | 无效字段 |
| INVALID_ID_FIELD | 无效 ID 字段 |
| INVALID_CROSS_REFERENCE_KEY | 无效交叉引用键 |
| DUPLICATE_VALUE | 重复值 |
| ENTITY_IS_LOCKED | 实体已锁定 |
| INSUFFICIENT_ACCESS_OR_READONLY | 权限不足或只读 |
| INVALID_OPERATION | 无效操作 |
| STORAGE_LIMIT_EXCEEDED | 存储限制超出 |
| SYSTEM_UNAVAILABLE | 系统不可用 |
## 限制与约束
### 数量限制
- 单次请求最多支持 1000 条记录
- 每批最多 200 条记录
- 超出限制将返回 BATCH_SIZE_EXCEEDED 错误
### 性能限制
- 批次间默认休眠 100ms
- 可根据实际情况调整休眠时间
- 建议使用 DisableFeedTrackingHeader 提高性能
### 权限要求
- 需要登录权限（`@ss.hasLogin()`）
- 需要有相应对象的读写权限
- 需要有相应字段的访问权限
## 最佳实践
### 1. 分批处理
对于大规模数据操作，建议使用自动分批处理功能：
- 单次请求最多 1000 条记录
- 系统会自动分批处理（每批 200 条）
- 建议设置适当的批次间休眠时间，避免 API 限流
### 2. 错误处理
- 建议设置 `allOrNone` 为 `false`，允许部分失败
- 检查返回结果中的 `success` 字段，判断是否全部成功
- 对于失败的记录，可以查看 `results` 中的错误详情
### 3. 性能优化
- 使用 `DisableFeedTrackingHeader` 提高性能（已默认启用）
- 设置适当的 `sleepTime`，避免 API 限流
- 避免在高峰期进行大规模批量操作
### 4. Upsert 使用
- 确保外部 ID 字段在对象中已定义
- 确保每条记录都包含外部 ID 字段的值
- 可以使用 `created` 字段判断记录是创建还是更新
## 相关文档
- [需求文档](../requirements/sub/2026-01-28-001-03-批量操作.md) - 批量操作需求文档
- [设计文档](../design/2026-01-30-003-批量操作-设计.md) - 批量操作设计文档
- [决策记录](../decisions/2026-01-30-003-ADR-批量操作技术选型.md) - 批量操作技术选型决策记录
- [变更日志](../changelog/2026-01-30-003-changelog.md) - 批量操作变更日志
- [复盘文档](../retros/2026-01-30-003-retro.md) - 批量操作复盘文档
- [会话记录](../sessions/2026-01-28-001-session.md) - 会话记录
Reference in New Issue Copy Permalink