kris/datai

Fork 0

Kris 0591aceb52 【feat】初始化所有模块，提交partner模块初始实现

2026-02-02 16:12:25 +08:00

16 KiB

Raw Blame History

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	错误信息	"批量创建记录失败: ..."

请求示例

{
  "objectType": "Account",
  "records": [
    {
      "Name": "Test Account 1",
      "BillingCity": "San Francisco"
    },
    {
      "Name": "Test Account 2",
      "BillingCity": "New York"
    }
  ],
  "allOrNone": false,
  "sleepTime": 100
}

响应示例

成功示例：

{
  "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
      }
    ]
  }
}

部分失败示例：

{
  "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

请求示例

{
  "objectType": "Account",
  "records": [
    {
      "id": "001xx000003GWFjAAO",
      "Name": "Updated Account 1",
      "BillingCity": "Los Angeles"
    },
    {
      "id": "001xx000003GWFkAAP",
      "Name": "Updated Account 2",
      "BillingCity": "Chicago"
    }
  ],
  "allOrNone": false,
  "sleepTime": 100
}

响应示例

成功示例：

{
  "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	是	记录 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

请求示例

{
  "objectType": "Account",
  "ids": [
    "001xx000003GWFjAAO",
    "001xx000003GWFkAAP"
  ],
  "allOrNone": false,
  "sleepTime": 100
}

响应示例

成功示例：

{
  "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

请求示例

{
  "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
}

响应示例

成功示例：

{
  "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 字段判断记录是创建还是更新

16 KiB Raw Blame History Unescape Escape

API 文档 - 批量操作

元数据

API 概述

核心特性

基础信息

接口列表

1. 批量创建记录

接口说明

请求信息

请求参数

响应参数

请求示例

响应示例

2. 批量更新记录

接口说明

请求信息

请求参数

响应参数

请求示例

响应示例

3. 批量删除记录

接口说明

请求信息

请求参数

响应参数

请求示例

响应示例

4. 批量 Upsert 记录

接口说明

请求信息

请求参数

响应参数

请求示例

响应示例

错误码

系统错误码

业务错误码

Salesforce API 错误码

限制与约束

数量限制

性能限制

权限要求

最佳实践

1. 分批处理

2. 错误处理

3. 性能优化

4. Upsert 使用

相关文档

16 KiB

Raw Blame History