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/partner-api/PartnerBatchController/004-batch-upsert.md
3111404962 9ec6e3ae66 docs: 为 datai-salesforce-partner 模块创建完整的 API 文档 
- 为 6 个 Controller 创建了 28 个接口文档
  * PartnerAdvancedController: 5 个接口
  * PartnerBatchController: 4 个接口
  * PartnerConnectionController: 3 个接口
  * PartnerCrudController: 6 个接口
  * PartnerDescribeController: 6 个接口
  * PartnerQueryController: 4 个接口
- 创建 Partner API 接口文档索引 (index.md) 作为唯一真源
- 每个接口文档包含完整的请求/响应参数、错误码和使用说明
- 文档位置: docs/api-docs/partner-api/
2026-02-02 17:13:00 +08:00

5.6 KiB
Raw Permalink Blame History

API 文档 - 批量 Upsert 记录

元数据

  • 需求编号：001
  • 子需求编号：001-01
  • 接口编号：004
  • 创建时间：2026-02-02
  • 创建人：AI Assistant
  • 状态：已完成

接口概述

批量更新或插入 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理。

基本信息

  • 功能描述：批量更新或插入 Salesforce 记录
  • 请求方式：POST
  • 请求路径：/partner/batch/upsert
  • 权限要求：@PreAuthorize("@ss.hasLogin()")

请求参数

请求体（JSON）

参数名 类型 必填 说明 示例值
objectType String 是 对象类型 Account
externalIdField String 是 外部 ID 字段 ExternalId__c
records Array[Object] 是 记录列表（每条记录必须包含外部 ID 字段） [{"ExternalId__c": "EXT001", "Name": "Test"}]
allOrNone Boolean 否 是否全部成功或全部失败，默认 false false
sleepTime Long 否 批次间休眠时间（毫秒），默认 100 100

请求示例

{
  "objectType": "Account",
  "externalIdField": "ExternalId__c",
  "records": [
    {
      "ExternalId__c": "EXT001",
      "Name": "Test Account 1",
      "Industry": "Technology",
      "Phone": "555-1234"
    },
    {
      "ExternalId__c": "EXT002",
      "Name": "Test Account 2",
      "Industry": "Finance",
      "Phone": "555-5678"
    }
  ],
  "allOrNone": false,
  "sleepTime": 100
}

响应参数

参数名 类型 说明
code Integer 状态码（200 成功，其他失败）
msg String 提示信息
data Object 响应数据
data.success Boolean 是否全部成功
data.successCount Integer 成功数量
data.failureCount Integer 失败数量
data.createdCount Integer 创建数量
data.updatedCount Integer 更新数量
data.totalCount Integer 总数量
data.results Array 结果列表
data.results[].success Boolean 是否成功
data.results[].id String 记录 ID
data.results[].errors Array 错误列表
data.results[].created Boolean 是否创建
data.results[].index Integer 索引
data.errorMessage String 错误消息

成功响应示例（全部创建）

{
  "code": 200,
  "msg": "批量 Upsert 成功",
  "data": {
    "success": true,
    "successCount": 2,
    "failureCount": 0,
    "createdCount": 2,
    "updatedCount": 0,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx0000001Gw2EAA",
        "errors": null,
        "created": true,
        "index": 0
      },
      {
        "success": true,
        "id": "001xx0000001Gw3EAA",
        "errors": null,
        "created": true,
        "index": 1
      }
    ],
    "errorMessage": null
  }
}

成功响应示例（部分更新）

{
  "code": 200,
  "msg": "批量 Upsert 成功",
  "data": {
    "success": true,
    "successCount": 2,
    "failureCount": 0,
    "createdCount": 1,
    "updatedCount": 1,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx0000001Gw2EAA",
        "errors": null,
        "created": true,
        "index": 0
      },
      {
        "success": true,
        "id": "001xx0000001Gw4EAA",
        "errors": null,
        "created": false,
        "index": 1
      }
    ],
    "errorMessage": null
  }
}

部分失败响应示例

{
  "code": 200,
  "msg": "批量 Upsert 部分失败",
  "data": {
    "success": false,
    "successCount": 1,
    "failureCount": 1,
    "createdCount": 1,
    "updatedCount": 0,
    "totalCount": 2,
    "results": [
      {
        "success": true,
        "id": "001xx0000001Gw2EAA",
        "errors": null,
        "created": true,
        "index": 0
      },
      {
        "success": false,
        "id": null,
        "errors": [
          {
            "statusCode": "REQUIRED_FIELD_MISSING",
            "message": "Required fields are missing: [Name]",
            "fields": ["Name"]
          }
        ],
        "created": null,
        "index": 1
      }
    ],
    "errorMessage": null
  }
}

失败响应示例

{
  "code": 500,
  "msg": "批量 Upsert 记录失败",
  "data": {
    "success": false,
    "successCount": 0,
    "failureCount": 0,
    "createdCount": 0,
    "updatedCount": 0,
    "totalCount": 0,
    "results": null,
    "errorMessage": "Invalid external ID field: InvalidField__c"
  }
}

错误码

错误码 说明 处理建议
200 操作成功 -
400 请求参数错误 检查请求参数格式和必填项
401 未登录或登录已过期 请重新登录
500 服务器内部错误 请联系管理员或稍后重试

注意事项

  1. 单次最多 Upsert 1000 条记录
  2. 每批最多 200 条记录，超过会自动分批
  3. 每条记录必须包含外部 ID 字段
  4. 外部 ID 字段必须在 Salesforce 对象中定义为 External ID
  5. 如果外部 ID 已存在，则更新记录；否则创建新记录
  6. allOrNone 为 true 时，任何一条记录失败都会导致整个操作失败
  7. sleepTime 用于控制批次间的间隔，避免 API 限流
  8. created 字段指示记录是创建还是更新

相关文档