请求方式	PUT
请求地址	`https://api.coze.cn/v1/databases/:database_id/records`
权限	`Database.updateRecord` 确保调用该接口使用的访问令牌开通了`Database.updateRecord`权限，详细信息参考鉴权方式。
接口说明	更新扣子数据库中符合条件的记录。

请求参数

参数	取值	说明
Authorization	Bearer $Access_Token	用于验证客户端身份的访问令牌。你可以在扣子平台中生成访问令牌，详细信息，参考准备工作。
Content-Type	application/json	解释请求正文的方式。

Path

参数	类型	是否必选	示例	说明
database_id	String	必选	761070127115408****	用于指定更新操作的数据库 ID。

Body

参数	类型	是否必选	示例	说明
update_fields	Array of OpenUpdateField	必选	[{“field_name”: “user_id”, “value”: “amy”},{“field_name”: “level”,“value”: “2”}]	字段更新规则，定义待更新的字段名和更新后的目标值。
filter	Object of OpenComplexCondition	必选	{“logic”:“and”,“conditions”:[{“left”:“user_id”,“operation”:“equal”,“right”:“alice”},{“left”:“level”,“operation”:“equal”,“right”:“1”}]}	更新范围筛选条件，指定需更新的数据行。必须提供以避免误更新全表数据。支持通过逻辑运算符 `and` 或 `or`组合多个条件。每个条件包含字段名、操作符和比较值。
is_async	Boolean	可选	false	是否以异步方式执行更新操作。 `true`：异步更新，接口将立即返回，更新操作在后台执行。 `false`（默认值）：同步更新，接口将在更新操作完成后返回。
connector_id	String	可选	10000011	渠道 ID。扣子编程的渠道 ID 包括： 1024（默认值）：API 渠道。 999：Chat SDK。 10000122：扣子商店。 10000113：微信客服。 10000120：微信服务号。 10000121：微信订阅号。 10000126：抖音小程序。 10000127：微信小程序。 10000011：飞书。 998：WebSDK。自定义渠道 ID。自定义渠道 ID 的获取方式如下：在扣子编程左下角单击头像，在账号设置 > 发布渠道 > 企业自定义渠道管理页面查看渠道 ID。

OpenUpdateField

参数	类型	是否必选	示例	说明
field_name	String	可选	inactive	需要更新的字段名。
value	String	可选	status	更新后的字段值，所有类型均以字符串形式传入。

OpenComplexCondition

参数	类型	是否必选	示例	说明
logic	String	可选	and	指定多个更新条件之间的逻辑关系。取值如下： `and`：所有条件必须同时满足。 `or`：满足任意一个条件即可。
conditions	Array of OpenCondition	可选	[{“left”:“user_id”,“operation”:“equal”,“right”:“alice”},{“left”:“level”,“operation”:“equal”,“right”:“1”}]	指定更新条件的列表，每个条件包含左值（字段名）、操作符和右值（比较目标值）。

参数

类型

是否必选

示例

说明

logic

String

可选

and

指定多个更新条件之间的逻辑关系。取值如下：

and：所有条件必须同时满足。
or：满足任意一个条件即可。

conditions

Array of OpenCondition

可选

[{“left”:“user_id”,“operation”:“equal”,“right”:“alice”},{“left”:“level”,“operation”:“equal”,“right”:“1”}]

指定更新条件的列表，每个条件包含左值（字段名）、操作符和右值（比较目标值）。

OpenCondition

参数	类型	是否必选	示例	说明
left	String	可选	status	指定更新条件的左值，即需要进行比较的字段名。
operation	String	可选	equal	指定更新条件中的操作符，取值如下： `equal`：等于 `not_equal`：不等于 `greater_than`：大于 `less_than`：小于 `greater_equal`：大于等于 `less_equal`：小于等于 `in`：包含在 `not_in`：不包含在 `is_null`：为空 `is_not_null`：不为空 `like`：模糊匹配 `not_like`：模糊不匹配
right	String	可选	alice	指定更新条件中的比较目标值，即与 `left` 字段指定的字段进行比较的值。当 `operation` 为 `is_null` 或 `is_not_null`时，无需填写此字段。

参数

类型

是否必选

示例

说明

left

String

可选

status

指定更新条件的左值，即需要进行比较的字段名。

operation

String

可选

equal

指定更新条件中的操作符，取值如下：

equal：等于
not_equal：不等于
greater_than：大于
less_than：小于
greater_equal：大于等于
less_equal：小于等于
in：包含在
not_in：不包含在
is_null：为空
is_not_null：不为空
like：模糊匹配
not_like：模糊不匹配

right

String

可选

alice

指定更新条件中的比较目标值，即与 left 字段指定的字段进行比较的值。当 operation 为 is_null 或 is_not_null时，无需填写此字段。

返回参数

参数	类型	示例	说明
data	Object of UpdateData	{“affected_rows”:15}	返回更新的数据行数。
code	Long	0	调用状态码。 0 表示调用成功。其他值表示调用失败。你可以通过 msg 字段判断详细的错误原因。
msg	String	“”	状态信息。API 调用失败时可通过此字段查看详细错误信息。状态码为 0 时，msg 默认为空。
detail	Object of ResponseDetail	{“logid”:“20241210152726467C48D89D6DB2****”}	包含请求的详细信息的对象，主要用于记录请求的日志 ID 以便于排查问题。

UpdateData

参数	类型	示例	说明
task_id	String	7525340985****	异步更新时返回的任务 ID。可通过查询异步执行结果接口，查看异步更新执行结果。
affected_rows	Integer	15	同步更新时返回成功更新的行数。

ResponseDetail

参数	类型	示例	说明
logid	String	20241210152726467C48D89D6DB2****	本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此`logid`及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。

示例

请求示例

curl --location --request PUT 'https://api.coze.cn/v1/databases/761284025805235****/records' \
--header 'Authorization: Bearer pat_O****' \
--header 'Content-Type: application/json' \
--data-raw '{
  "update_fields": [
    {
      "field_name": "user_id",
      "value": "amy"
    },
    {
      "field_name": "level",
      "value": "2"
    }
  ],
  "filter": {
    "logic": "and",
    "conditions": [
      {
        "left": "user_id",
        "operation": "equal",
        "right": "alice"
      },
      {
        "left": "level",
        "operation": "equal",
        "right": "1"
      }
    ]
  },
  "is_async": true
}'

返回示例

{
    "code": 0,
    "data": {
        "task_id": "7525340985****"
    },
    "msg": "",
    "detail": {
        "logid": "20241210152726467C48D89D6DB2****"
    }
}