创建批量写入任务

目的

用来创建批量写入任务。

请求 URL

https://www.zohoapis.com.cn/crm/bulk/v2/write

请求方法

POST

范围

scope=ZohoCRM.bulk.CREATE
(或)
ZohoCRM.bulk.ALL
(和)
scope=ZohoCRM.settings.modules.ALL

可能的模块名称可能的操作类型
线索，客户，联系人，商机，市场活动，服务支持，解决方案，产品，供货商，价格表和自定义模块ALL - 完全访问记录
CREATE - 创建批量写入任务

请求 JSON

属性数据类型必填描述
character_encoding字符串否表示上传文件的字符集。它通常是自动检测的。但是如果指定了，那么它将被用来读取文件。
operation字符串是表示要在批量写入任务上执行的操作类型。
值是
  • insert - 在CRM中创建CSV记录作为新记录
  • update - 更新CRM中的现有记录(此操作不允许创建新记录)。
  • upsert - 更新CRM中的现有记录并创建新记录(如果它还不存在)
callback 显示属性JSON 对象否一个允许HTTP POST方法的有效URL。批量写入任务的详细信息在任务成功完成或任务失败时发布到此URL。示例 - "callback" : { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }

callback Properties

属性数据类型必填描述
url字符串(URL)是一个有效的URL，它应该允许HTTP POST方法。批量写入任务的详细信息在任务成功完成或任务失败时发布到此URL。
method字符串是指定回调url的HTTP方法。只支持HTTP POST方法。允许的值是post。
resource显示属性JSON Array否一个JSON对象数组，其中包含要导入的模块API名称、它们的字段映射以及从上传 API中获得的相应文件ID。

resource Properties

属性数据类型必填描述
type字符串是表示要导入的模块类型。这个值是data。
module字符串是为批量写入任务选择的模块API名称。
file_id字符串是表示从文件上传API中获取的file_id。
ignore_empty布尔型否True - 忽略列中的空值，只更新没有空值的记录的字段
False 或 empty - 系统使用给定文件列中的空值更新CRM中的记录。
默认值为false。
find_by字符串Yes(用于更新和更新插入)
No(for insert)		指定记录的唯一字段或ID的API名称。系统使用此字段的值查找CRM中的现有记录。当您为insert操作指定此参数时，系统将跳过文件中的现有记录。.
field_mappings
显示属性		JSON 数组否当系统处理CSV文件时，第一行被视为头行。每个头名称都被视为字段API名称，列中的数据被填充到由API名称表示的相应字段中。此参数帮助您跳过自动映射并定义自己的字段映射。

field_mappings Properties

属性数据类型必填描述
api_name字符串是要导入的Zoho模块对象中显示的字段API名称。请参考字段元数据API 获取模块中可用字段的列表。无效字段API名称引发错误。
index数字否要映射到CRM字段的字段列索引。当您指定一个不存在的索引值时，系统会抛出一个错误。
default_valueJSON 对象否如果某些记录在列中没有值，并且希望用默认值替换它，请使用此键。示例： {"value": "Trade Show"}

响应结构

属性数据类型描述
status字符串指定API调用的状态。示例 - "status": "success"。
message字符串指定任务的预定义注释。在任何错误发生的情况下有用。
details 显示属性JSON 对象有关“details”JSON对象的信息，请参考下表。

details Properties

属性数据类型描述
id字符串指定批量写入任务的唯一标识符。示例 - "id": "1000010760002"。
created_byJSON 对象指定发起批量写入任务的用户ID和名称。示例 - "created_by": { "id": "1000000031045", "name": "Patricia Boyle" },

可能的错误

HTTP 状态错误码消息原因
400MANDATORY_FIELDS_NOT_MAPPEDAll mandatory fields are not mapped模块中的所有必填字段都没有映射
400MANDATORY_NOT_FOUNDMandatory key is not available请求主体中没有指定必填密钥或值。
示例："message": "Required key find_by is not available"。
400INVALID_FIELDinvalid mapping. invalid api_name {{api_name}}字段API名称无效
400INVALID_FORMATinvalid mapping. invalid format Invalid format for sysref - {field_api_name}日期输入格式错误
400INVALID_FILE_IDinvalid file_id {{file_id}}指定的文件ID无效
400HEADER_LIMIT_EXCEEDEDImport file does not exceed 200 columns映射的字段数已超过200的最大限制
400COLUMN_INDEX_NOT_FOUNDInvalid column index mapped. Index is invalid for sysref {field_api_name}.索引被映射为负值
400MODULE_NOT_AVAILABLERequested module {module_api_name} is not available指定的模块名称无效
Curl

示例请求

在这个请求中，@inputData.json包含了示例输入数据。


				curl "https://www.zohoapis.com.cn/crm/bulk/v2/write"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@inputData.json"

批量插入的示例输入


				{
  "operation": "insert",
  "callback": {
    "url": "http://requestbin.fullcontact.com/1fcimk51",
    "method": "post"
  },
  "resource": [
    {
      "type": "data",
      "module": "Contacts",
      "file_id": "111111000000541958",
      "field_mappings": [
        {
          "api_name": "Phone",
          "index": 1
        },
        {
          "api_name": "Email",
          "index": 2
        },
        {
          "api_name": "Last_Name",
          "default_value": {
            "value": "DefaultValue"
          }
        }
      ]
    }
  ]
}

批量更新的示例输入


				{
  "operation": "update",
  "resource": [
    {
      "type": "data",
      "module": "Contacts",
      "file_id": "111111000000541958",
      "field_mappings": [
        {
          "api_name": "Last_Name",
          "index": 1
        },
        {
          "api_name": "Id",
          "index": 1
        }
      ],
      "findBy": "Id"
    }
  ],
  "callBack": {
    "url": "http://requestbin.fullcontact.com/1bvgfh61",
    "method": "post"
  }
}

示例响应


				{
  "status": "success",
  "code": "SUCCESS",
  "message": "success",
  "details": {
    "id": "111111000000541958",
    "created_by": {
      "id": "111111000000035795",
      "name": "Patricia Boyle "
    }
  }
}