创建自由任务新版SDK

更新于 2023-05-12

接口调用量说明钉钉标准版接口累计可调用次数为1万次/月，当前接口会消耗调用次数。若该调用量无法满足需求，你可升级钉钉专业版(Open API调用量50万次/月)或钉钉专属版(Open API调用量500万次/月)扩容调用次数。

调用本接口，创建一个钉钉自由任务（非加入项目的任务）。

什么是自由任务

自由任务是在项目应用中创建，但是不关联任何项目的任务。

接口功能介绍

例如，在员工小钉的项目中，我的任务列表如下图所示，没有需要执行的任务。

调用本接口，给员工小钉创建一个名为测试任务的任务。接口调用成功后，员工小钉在我的任务列表查看到的信息如下图所示，有一个名为测试任务的任务。

权限

要调用此API，需要以下权限之一。

应用类型	是否支持	权限	API Explorer调试
企业内部应用	支持	项目应用任务写权限	API Explorer
第三方企业应用	支持	项目应用任务写权限	API Explorer
第三方个人应用	暂不支持	项目应用任务写权限	暂不支持

请求方法

Header参数

名称	类型	是否必填	描述
x-acs-dingtalk-access-token	String	是	调用该接口的访问凭证。企业内部应用，调用获取企业内部应用的accessToken接口获取。第三方企业应用，调用获取第三方应用授权企业的accessToken接口获取。

名称

类型

是否必填

描述

x-acs-dingtalk-access-token

String

是

调用该接口的访问凭证。

企业内部应用，调用获取企业内部应用的accessToken接口获取。
第三方企业应用，调用获取第三方应用授权企业的accessToken接口获取。

Path参数

名称	类型	是否必填	描述
userId	String	是	操作者userId。

Body参数

名称	类型	是否必填	描述
content	String	是	任务标题。
note	String	否	任务备注。
priority	Integer	是	自由任务优先级，如下图所示。用户是否有自定义更新优先级，获取该参数方法不同。用户未更新优先级。该参数默认为以下值：较低，默认值：10 普通：0 紧急：1 非常紧急：2 用户自定义优先级，如下图所示，新增一般紧急并调整优先级顺序等，需要通过调用接口获取该参数值。企业内部应用，调用查询优先级列表接口获取priorityId值。第三方企业应用，调用查询优先级列表接口获取priorityId值。说明优先级数值越大，优先级越高。自定义优先级需要开通企业版或者旗舰版项目，开通请参考开通企业版或旗舰版。
involveMembers	Array of String	否	参与者userId列表，建议参与者总人数不超过20个。
executorId	String	否	执行者userId。
dueDate	String	否	任务截止日期，格式：YYYY-MM-DDTHH:mm:ssZ（ISO 8601/RFC 3339）。说明转换成北京时间，需要在参数时间基础上加8小时。例如参数值为2022-06-20T00:00:00Z，表示的北京时间为2022-06-20 08:00:00。
createTime	String	否	任务创建日期，格式：YYYY-MM-DDTHH:mm:ssZ（ISO 8601/RFC 3339）。说明转换成北京时间，需要在参数时间基础上加8小时。例如参数值为2022-06-20T00:00:00Z，表示的北京时间为2022-06-20 08:00:00。
visible	String	是	任务可见性。 involves：仅参与者可见 members：所有人可见
disableNotification	Boolean	否	是否禁止通知。 true：禁止，不显示通知。 false：不禁止，显示通知。
disableActivity	Boolean	否	是否禁止动态。 true：禁止，不显示该任务动态信息。 false：不禁止，显示该任务动态信息。

返回参数

名称	类型	描述
result	Object	返回结果。
dueDate	String	任务截止日期，格式：YYYY-MM-DDTHH:mm:ssZ（ISO 8601/RFC 3339）。说明转换成北京时间，需要在参数时间基础上加8小时。例如参数值为2022-06-20T00:00:00Z，表示的北京时间为2022-06-20 08:00:00。
executor	Object	执行者。
avatarUrl	String	执行者头像地址。
name	String	执行者姓名。
userId	String	执行者userId。
id	String	任务id。说明暂无其他接口可获取任务id值，请妥善保存任务id。
visible	String	任务可见性。 involves：仅参与者可见 members：所有人可见
created	String	创建时间，格式：YYYY-MM-DDTHH:mm:ssZ（ISO 8601/RFC 3339）。说明转换成北京时间，需要在参数时间基础上加8小时。例如参数值为2022-06-20T00:00:00Z，表示的北京时间为2022-06-20 08:00:00。
priority	Integer	自由任务优先级。使用项目默认的优先级，如下图所示。优先级默认为以下。 -10：较低，默认值。 0：普通 1：紧急 2：非常紧急用户自定义优先级，如下图所示，新增一般紧急并调整优先级顺序等。该参数值以接口实际调用结果为准。优先级越高，数值越大。
involvers	Array	参与者信息列表。
avatarUrl	String	参与者头像地址。
name	String	参与者名字。
id	String	参与者userId。
updated	String	更新时间，格式：YYYY-MM-DDTHH:mm:ssZ（ISO 8601/RFC 3339）。说明转换成北京时间，需要在参数时间基础上加8小时。例如参数值为2022-06-20T00:00:00Z，表示的北京时间为2022-06-20 08:00:00。
note	String	任务备注。
hasReminder	Boolean	任务是否有提醒。 true：有提醒 false：无提醒
creatorId	String	创建者userId。
content	String	任务标题。
attachmentsCount	Integer	附件数量。
isDeleted	Boolean	是否删除。 ture：已删除 false：未删除
ancestorIds	Array of String	该任务父任务的id。
creator	Object	创建者对象。
avatarUrl	String	创建者头像地址。
name	String	创建者姓名。
userId	String	创建者userId。
executorId	String	执行者userId。
involveMembers	Array of String	参与者userId列表。
isDone	String	是否完成。 true：已完成 false：未完成

示例

请求示例

HTTP

Java

Python

PHP

Node.js

返回示例

错误码

HttpCode	错误码	错误信息	说明
400	user.not.exist	user not exist	用户在当前企业中不存在
400	org.not.exist	org not exist	当前企业在Teambition中不存在
500	server.error	system error	系统内部服务错误

这篇文档是否有帮助？

本页内容