API使用指南 - Liutos/cuckoo GitHub Wiki

名词介绍

在cuckoo中有如下的几种对象：

  • 场景。表示当前的外部环境是怎样的，它们存储在t_context表中；
  • 提醒。表示一个在系统右上角弹出通知的时机，它们存储在t_remind表中；
  • 提醒记录。表示在右上角弹出通知的历史事件，它们存储在t_remind_log表中；
  • 重复模式。表示下一次提醒的时机的计算规则，它们存储在t_repeat表中；
  • 任务。表示待提醒的内容，它们存储在t_task表中。

场景

搜索

GET /context?name=${name}&sort=${sort}
  • 可选的参数name表示要搜索的场景的名称（精确匹配）；
  • 可选的参数sort表示期望的结果排序方式，默认为create_at:desc，即按照数据库表中的create_at字段递减排列；

以JSON格式返回场景对象的数组。

获取当前场景名

GET /context/current

以下列格式返回当前场景的名称

{
  "context": "场景名"
}

新建

POST /context
Content-Type: application/json

{
  "name": "场景名"
}

创建成功后返回201状态码。

提醒

查看特定提醒

GET /remind/:id
  • URL参数id为待查看的提醒的ID

以JSON格式返回提醒的对象。

更新提醒

PATCH /remind/:id
Content-Type: application/json

{
  "duration": 0, // 弹出提醒的展示时间
  "restricted_hours": [], // 一个长度为24的由0、1组成的数组，表示要在0~23的哪一个小时允许弹出提醒
  "timestamp": 0, // 下一次触发提醒的时刻，为秒级精度的UNIX时间戳
  "repeat_type": "重复模式的名称"
}

更新成功后返回204状态码。

新建

POST /remind
// 参数与上面更新提醒的接口相同

创建成功后返回201状态码、JSON格式的提醒对象数据。

提醒记录

搜索

GET /remind/log?limit=${limit}&sort=${sort}&task_id=${task_id}
  • 可选参数limit为一个数字，表示要获取的提醒记录数量，默认为10；
  • 可选参数sort为一个字符串，表示搜索结果的排序方式，默认为create_at:desc，即按照创建时间递减排列；
  • 可选参数task_id为一个数字，表示只查看与该ID的任务有关的提醒的记录。

以JSON格式返回提醒记录对象的数组。

任务

删除

DELETE /task/:id

将ID为:id的任务从数据库中删除

搜索

GET /task?brief=${brief}&context_id=${}&detail=${}&sort=${}&state=${}
  • 可选参数brief表示要求搜索结果的brief字段中含有该参数指定的字符串；
  • 可选参数context_id表示要求搜索结果的context_id字段等于该参数的值；
  • 可选参数detail与brief效果类似，但作用于detail字段；
  • 可选参数sort用于控制排序，参见前文；
  • 可选参数state与context_id效果类似，但作用于state字段。

以JSON格式返回任务对象的数组。

查看接下来的提醒

GET /task/following?contextId=${}
  • 可选参数contextId表示要求搜索结果中的任务必须能够在该指定场景下被触发提醒。

以JSON格式返回任务对象的数组。

查看任务

GET /task/:id

查看特定的任务对象。

更新任务

PATCH /task/:id
Content-Type: application/json

{
  "brief": "",
  "context_id": 0,
  "detail": "",
  "device": "", // 若该值为"mobilePhone"，则弹出桌面提醒前还会发送通知给微信帐号
  "icon": "", // 弹出提醒时的图标
  "icon_file": "", // 在Alfred Workflow中展示的图片路径
  "remind_id": 0, // 相应的提醒的ID
  "state": ""
}

更新成功后返回204状态码。

同步任务

POST /task/sync

在任务的存储和延时队列间进行同步：

  1. 如果在队列中的一个任务已经不是active的状态了，就将其从队列中删去；
  2. 如果在存储中有active状态的任务没有在队列中，就补充进去；
  3. 如果在存储中的active状态的任务与队列中的触发时间不一致，则修正队列中的值。

同步完后返回204状态码。

创建任务

POST /task
// 参数与上面的“更新任务”接口一致

创建成功后返回状态码201，以及JSON各式的任务对象。