跳转到主要内容
POST
预览值班表

限制说明

使用说明

  • 不会保存任何数据。请求体字段与 /schedule/create 相同,另需必填的 start/end 窗口。start 和 end 为 10 位 Unix 秒级时间戳;end 必须晚于 start,且相差不超过 45 天。
  • 传入 time_zone 可按值班表将要使用的时区预览;不传时,墙钟时间按 Asia/Shanghai 解读。
  • 只有已保存的值班表才有的字段(id、name、group_id、disabled、status)按请求原样回显,通常为 null。
  • cur_oncall 是此刻正在进行的班次,next_oncall 是之后第一个有人值班的班次;在当前时刻前后 45 天内找不到时为 null,与请求的时间窗口无关。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json

/schedule/create、/schedule/update、/schedule/preview 的请求体。创建时必须提供 schedule_name(或旧字段 name),更新时必须提供 schedule_id,预览时必须提供 start/end。

schedule_id
integer<int64> | null

值班表 ID,更新时必填,可通过 POST /schedule/list 获取。

schedule_name
string | null

值班表名称,最长 40 个字符,账户内唯一。更新时不传则保持原名称。

Maximum string length: 40
name
string | null

旧版名称字段,仅在创建且 schedule_name 为空时使用。更新时忽略。

Maximum string length: 40
description
string | null

值班表描述,最长 500 个字符。更新时不传保持原值,传空字符串则清空。

Maximum string length: 500
team_id
integer<int64> | null

所属团队 ID,可通过 POST /team/list 获取。创建时不传则不归属任何团队(0);更新时不传保持原团队。

time_zone
string

值班表墙钟规则所用的 IANA 时区,如 Asia/Shanghai、UTC;EST 之类的缩写以及 Etc/GMT±N 会被拒绝。创建时设置(不传则按 Asia/Shanghai 计算),之后不可修改——更新时不传或传当前值。预览时用于指定计算时区。

layers
object[]

轮转分层。更新时该列表会替换全部已有分层,不传即删除所有分层。单次请求最多 1000 项,更多请分多次调用。

Maximum array length: 1000
notify
object | null

换班通知配置。更新时不传保持原配置;传入则整体替换。

start
integer<int64>

预览窗口开始时间,10 位 Unix 秒。/schedule/preview 必填;创建和更新时忽略。

end
integer<int64>

预览窗口结束时间,10 位 Unix 秒,晚于 start 且相差不超过 45 天。/schedule/preview 必填;创建和更新时忽略。

disabled
enum<integer> | null

仅创建时生效:0 = 启用(默认),1 = 禁用。更新时忽略,请改用 status。

可用选项:
0,
1,
null
status
enum<integer> | null

0 = 启用,1 = 禁用。更新时不传保持当前状态。创建时优先于 disabled。

可用选项:
0,
1,
null

响应

成功

成功响应结构。2xx 响应中 request_id 标识本次调用(同时出现在 Flashcat-Request-Id 响应头中),data 为接口业务 payload。失败响应使用不同结构,参见 ErrorResponse。

request_id
string
必填

本次请求的唯一 ID,也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

info、list、infos、self、preview 接口返回的值班表。哪些计算字段有值取决于具体接口,见各接口说明。