服务端 Hook 配置文件

服务端 Hook 配置文件用于定义何时服务端代码需要被执行。必须同服务端代码一起被部署。

在服务端 Hook 配置文件中,你可以指定以下两种时间(Hook)(详情请参阅功能手册篇中的 服务端代码的执行)。

  • 由服务端触发执行行为的 Hook:当指定的触发器(trigger)在你的服务端被触发时,你的服务端代码便会被执行。

  • 预设执行时间的 Hook:你的服务端代码将在指定时间被执行。

    2015年10月14日前在"中国(China)"服务器上创建的应用程序无法使用预设执行时间的 Hook。

所有的配置都将存放在一个 JSON 文件中。请查看如下所示的服务端 Hook 配置文件的示例。此例中,共定义了5个 Hook(用户被创建,应用程序级 Bucket 被创建或删除,UTC 时间的每小时的0分以及每天的2:30分)。

{
  "kiicloud://users": [
    {
      "when": "USER_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "userCreated"
    }
  ],
  "kiicloud://buckets/highScore": [
    {
      "when": "DATA_OBJECT_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "highScoreCreated"
    },
    {
      "when": "DATA_OBJECT_DELETED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "highScoreDeleted"
    }
  ],
  "kiicloud://scheduler": {
    "HourlyCheck": {
      "what": "EXECUTE_SERVER_CODE",
      "cron": "0 * * * *",
      "endpoint": "checkData",
      "parameters": {
        "executionType": "hourly",
        "target": "user"
      }
    },
    "DailyCheck": {
      "what": "EXECUTE_SERVER_CODE",
      "cron": "30 2 * * *",
      "endpoint": "checkData",
      "parameters": {
        "executionType": "daily",
        "target": "all"
      }
    }
  }
}

服务端 Hook 配置文件中所指定的端点(endpoint)将在条件满足时被执行。也可以通过客户端 SDK 手动执行。

由服务端触发执行行为的 Hook

下面的例子阐述了如何定义由服务端触发执行行为的服务端 Hook 配置文件:

{
  "<path>": [
    {
      "when": "<trigger>",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "<endpoint_name>"
    },
    /* more hooks */
  ],
  /* more paths with more hooks */
}

when(当)指定的触发器(trigger)发生于 path 所指定的实体中时,服务端代码(即 endpoint_name 所指定的目标函数名)将被执行。

path 可以指向 Bucket、用户(User)、群组(Group)、Thing 或者装配:

  • Bucket:用于监听指定 Bucket 的触发器(trigger)。

    • path 需要被指定为以下方式之一:
      • kiicloud://buckets/<bucketID> 用于应用程序级的 Bucket。
      • kiicloud://groups/*/buckets/<bucketID> 用于群组级的 Bucket。
      • kiicloud://users/*/buckets/<bucketID> 用于用户级的 Bucket。
      • kiicloud://things/*/buckets/<bucketID> 用于 Thing 级的 Bucket。
    • trigger 可以是下列之一:
      • DATA_OBJECT_CREATED:指定的 Bucket 中有一个新的 Object 被创建了。
      • DATA_OBJECT_DELETED:指定的 Bucket 中有一个 Object 被删除了。
      • DATA_OBJECT_UPDATED:指定的 Bucket 中有一个 Object 被更新了。

    服务端代码可以获取各种 Object 触发器相关的参数。详见 这里

  • 用户:用于监听所有用户的触发器(trigger)。

    • path 需要被指定为 kiicloud://users
    • trigger 可以是下列之一:
      • USER_CREATED:有一个新用户被创建了。
      • USER_EMAIL_VERIFIED:有一个用户的电子邮箱通过了验证。
      • USER_PHONE_VERIFIED:有一个用户的手机号码通过了验证。
      • USER_PASSWORD_RESET_COMPLETED:有一个用户的密码被重置了。
      • USER_PASSWORD_CHANGED:有一个用户的密码被修改了。
      • USER_DELETED:有一个用户被删除了。
      • USER_UPDATED:有一个用户的属性被更新了。

    服务端代码可以获取各种用户触发器相关的参数。详见 这里

    你可以使用 USER_UPDATED 来监听不支持的触发器,比如 禁用用户。例如,你可以在该用户被禁用时更新用户的属性。

  • 群组:用于监听所有群组的触发器(trigger)。

    • path 需要被指定为 kiicloud://groups
    • trigger 可以是下列之一:
      • GROUP_CREATED:有一个新的群组被创建了。
      • GROUP_DELETED:有一个群组被删除了。
      • GROUP_MEMBERS_ADDED:有一个群组新增了成员。
      • GROUP_MEMBERS_REMOVED:有一个群组删除了成员。

    服务端代码可以获取各种群组触发器相关的参数。详见 这里

  • Thing:用于监听所有 Thing 的触发器。

    • path 需要被指定为 kiicloud://things
    • trigger 可以是下列之一:
      • THING_CREATED:有一个新的 Thing 被登记了。
      • THING_ENABLED:有一个新的 Thing 被启用了。
      • THING_DISABLED:有一个新的 Thing 被禁用了。
      • THING_USER_OWNER_ADDED:有一个用户被添加为 Thing 的权属人。
      • THING_GROUP_OWNER_ADDED:有一个群组被添加为 Thing 的权属人。
      • THING_USER_OWNER_REMOVED:有一个用户被取消了 Thing 的权属人身份。
      • THING_GROUP_OWNER_REMOVED:有一个群组被取消了 Thing 的权属人身份。
      • THING_FIELDS_UPDATED:有一个 Thing 的信息被更新了。
      • THING_DELETED:有一个 Thing 被注销了。
      • THING_CONNECTED:有一个 Thing 上线了(即,建立了一个新的 MQTT 连接)。
      • THING_DISCONNECTED:有一个 Thing 下线了(即,一个 MQTT 连接断开了,包括正常断开和意外断开)。

    服务端代码可以获取各种 Thing 触发器相关的参数。详见 这里

  • 装配:用于监听用户设备是否被装配(用于接收推送通知)的触发器(trigger)。

    • path 需要被指定为 kiicloud://installations
    • trigger 可以是下列之一:
      • INSTALLATION_CREATED:有一个设备被装配了(用于接收推送通知)。
      • INSTALLATION_DELETED:有一个设备被删除了(不再接收推送通知)。

    服务端代码可以获取各种装配触发器相关的参数。详见 这里

下面是服务端 Hook 的示例:

{
  "kiicloud://users": [
    {
      "when": "USER_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "main"
    }
  ]
}

此例中,当一个新用户被创建时,端点 main 将被执行(对于 此处的服务端代码示例 来说,会是个不错的 Hook)。

设置 path 属性相同的触发器

如果多个触发器需要使用相同的 path,请按如下方法定义触发器。请注意,如果配置文件中定义了多个拥有相同 path 的触发器,那么仅最后的那个触发器可用。

{
  "kiicloud://buckets/myBucket": [
    {
      "when": "DATA_OBJECT_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "func1"
    },
    {
      "when": "DATA_OBJECT_DELETED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "func2"
    }
  ]
}

在一个触发器中无法设置多个端点。比如,如果在一个由创建用户行为触发的触发器中设置了 func1func2 两个端点,那么将会报错。如果你需要实现这种情况,那么请在服务端代码的一个端点中实现这些逻辑。

预设执行时间的 Hook

下例中阐述了,如何定义预设执行时间的服务端 Hook 配置文件:

{
  "kiicloud://scheduler": {
    "<job_name>": {
      "cron": "<cron_expression>",
      "endpoint": "<endpoint_name>",
      "parameters": {
        "arg1": "xxxx"
      },
      "what": "EXECUTE_SERVER_CODE"
    }
    /* more hooks */
  }
  /* more paths with more hooks */
}

服务端代码(即 endpoint_name 所指定的目标函数名)将会在预定时间 cron_expression 时被执行。你还可以在每个计划中指定 job_name,这样方便在之后检查所定义的 Hook 是否被正确执行。你可以把你想要传递给端点的参数写入 parameters 属性(可选项)。

你可以在 "kiicloud://scheduler" 下设置多个计划。当设置多个计划时,请使用不同的 job_name 来区分它们(如果名称重复,Kii Cloud 将不会给出错误提示)。如果使用不同的名称设置了相同的计划,那么所指定的端点将按照设置的次数被多次执行。

下面的例子说明如何使用 cron expression 定义时间:

所设置的时间为世界标准时间(UTC)。

您还可以使用以下特殊字符:

  • 星号 (*) 表示匹配所有值。
  • 连字符 (-) 指定范围。
  • 斜线 (/) 表示增量。例如,在第一个字段(min)中的 "0/10",意味着"每10分钟"。
  • 逗号 (,) 表示一个可用值列表。例如,在第五个字段(day of week)中的 "MON,WED,FRI" ,意味着"周一、周三、周五"。

示例:

#每小时执行一次
0 * * * *

#每天午夜后1分钟(00:01)执行一次
1 0 * * *

#从周一到周五每天05:00执行一次
0 5 * * MON-FRI

#每2个小时执行一次,午夜、2点、4点、6点、8点 等等
0 0/2 * * *

#每天的下午2点到下午2:55,每5分钟执行一次
11/5 14 * * *

#周六和周日的 11:00 和 16:00 各执行一次
00 11,16 * * SUN,SAT

请注意以下限制:

  • 不可以同时使用 "*" 和 "/" 。

    • 正确:0/5 14 * * *
    • 不正确:*/5 14 * * *
  • expression 中任一字段(minute, hour,...)只能使用范围(例如,4-7)、增量(例如,2/5)或是列表(例如,0,5,10,15)中的一种,不可以混合使用。

    • 正确:0,5,10 21-23 * * MON-FRI
    • 不正确:5-8/2 * * * *
  • 不可以同时使用 day-of-week 和 day-of-month。

    • 不正确:0 0 1 1 SUN

下面是服务端 Hook 的示例:

{
  "DailyMessage_5am": {
    "cron": "0 5 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "5am"
    },
    "what": "EXECUTE_SERVER_CODE"
  },
  "DailyMessage_10pm": {
    "cron": "0 22 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "10pm"
    },
    "what": "EXECUTE_SERVER_CODE"
  }
}

此例中,端点 sendDailyMessage 会在每天上午的 5:00 和下午的 10:00 被执行(UTC 时间)。每次被执行时,会有不同的参数传递给服务端代码(点击 这里 查看该 Hook 对应的服务端代码示例)。