利用通道与其它程序互通 - KMS 中国官方主页

原始需求
- 专业程序员希望自己的程序（以下称为主程序）能够与 kmscript 互通。
- 原有软件系统（以下称为主程序）希望与 kmscript 互通。
- 希望按自己的意愿产生一个基于变量的统计报表。
- 希望借用 HTTP 输入输出与其它 KMScript 同步变量。
互通实例
1. kmscript 运行特定的 kmsz，步骤如下
  1. kmsz 进行变量检查方法检查指定变量是否匹配（如 $A=1），成功则继续运行；失败则跳转到步骤3
  2. kmsz 进行若干主要操作，完成后产生特定变量（调用保存变量或图像定位等有结果的方法），以便给主程序读取，在成功处理跳转回步骤1
  3. kmsz 进行1分钟或更长时间的等待，在成功处理跳转回步骤1
2. 主程序利用通道的 set 方法设置特定值以传递变量给 kmsz 使之继续运行
  1. 可以在 kmsz 根据变量值进行特定跳转，例如$A=1 跳到模块1 $A=2跳到模块2... 这些模块结束后跳回步骤1继续循环
3. 主程序利用通道的 wake 方法唤醒 kmsz 正在进行的等待
4. kmsz 醒来后判断变量为特定值（见其步骤3）并进行主要操作后产生了结果变量
5. 主程序利用通道的 get 方法获取该结果变量
通道方法
1. 方法为 kmscript 内置，以 HTTP 协议的 GET 或 POST 调用的方法，端口号等同 kmscript 侦听的端口
2. 方法API路径始终只有一个，为 http://IP:端口/module/kms/Channel，例如 http://127.0.0.1:8181/module/kms/Channel
  1. 参数可以以GET或POST提交，编码为 UTF-8
  2. 参数始终有一个 _fn 表明当前的通道方法并连接其它参数，例如 http://127.0.0.1:8181/module/kms/Channel?_fn=get&name=$A
  3. 此机制允许任意可访问的网络设备发起此请求，而不仅限于本机
3. kmscript 必须已启用超级管理员帐号
4. 方法列表如下
  1. set 设置变量（如同保存变量）
    1. 参数如下
      1. pwd 超级管理员密码
      2. save_key 设置的变量名
      3. value 设置的变量值
    2. 返回值，一个 JSONObject，成功 code 始终为0，否则为负数表示失败
    3. 实例
      1. HTTP GET
        GET /module/kms/Channel?_fn=set&pwd=123456&save_key=$A&value=123
        Host: 127.0.0.1
        Connection: keep-alive
      2. HTTP Response
        Content-Type: application/json; charset=UTF-8
        Content-Length: 10
        Connection: keep-alive
        {"code":0}
    4. 例如 curl 或 C# 的 HttpWebRequest或 Java 的 HttpURLConnection
      curl "http://127.0.0.1:8181/module/kms/Channel?_fn=set&pwd=123456&save_key=$A&value=123"
      {"code":0}
  2. get 获取 kmscript 变量值
    1. 参数如下
      1. load_key 变量名
    2. 返回值，一个 JSONObject，成功 code 始终为0，否则为负数表示失败
      1. 如果变量不存在或空值，仍然返回 0，但没有 data 内容
    3. 实例
      1. HTTP GET
        GET /module/kms/Channel?_fn=get&load_key=$A
        Host: 127.0.0.1
        Connection: keep-alive
      2. HTTP Response
        Content-Type: application/json; charset=UTF-8
        Content-Length: 23
        Connection: keep-alive
        {"code":0,"data":"123"}
      3. 注1：返回的 data 值为 123 是字符串，但当其被用于数值计算后可能变为数字型，即
        {"code":0,"data":123}
  3. wake 提前结束当前 kmsz 的等待方法，如果 kmsz 当前步骤不是等待则忽略
    1. 参数无
    2. 返回值，一个 JSONObject，成功 code 始终为0，否则为负数表示失败
    3. 实例
      1. HTTP GET
        GET /module/kms/Channel?_fn=wake
        Host: 127.0.0.1
        Connection: keep-alive
      2. HTTP Response
        Content-Type: application/json; charset=UTF-8
        Content-Length: 10
        Connection: keep-alive
        {"code":0}
HTTPS 改造
1. 互通方法均为 HTTP 服务，已拥有证书的单位可能希望 HTTPS 连接，可借用 Nginx、Apache等服务器提供转发。
2. KMScript 不会提供 HTTPS 服务，因为根证书发行者并不受 KMScript 控制，在 KMScript 眼中它们并不安全。
  1. 举例来讲，根证书商A可以为该域名产生一个同样可信的新证书，拦截修改并转发请求，整个操作过程在均是合规的，除非客户端强制校验证书链为固定的一个。
其它说明
1. kmsz 在等待主程序给信号时应当设置一个很长的值，例如1分钟以确保不会反复进行变量检查浪费处理器资源。
  1. 主程序可以在设置相应变量后利用通道的 wake 方法提前结束这个等待
    1. 通道的 wake 会提前结束等待方法如同其等待时间已到，但其它方法的内部等待不受影响例如模拟键盘输入的每次按键之间的等待
2. 通道方法无需维持 Cookie
3. 通道方法可以维持 keep-alive保持长连接以执行多个指令（避免短连接每次都需要tcp的握手过程），其超时值如同 release/libjp.json中 jws 配置节的读取超时值（ServerReadTimeOutMS），默认为8000毫秒（可修改到更长比如 60000 毫秒）
  1. 短时间内不需要调用 kmscript 函数则可以断开下次重新连接
  2. 短时间内需要调用 kmscript 函数，且间隔时间会超过 kmscript 超时值，应以小于超时值的周期性调用 get 方法保持连接（可以 get 一个不存在的变量以减少运算）
4. kmsz 里存在云函数方法或其它需要锁机制的按照 kmscript 其约定进行，即运行 kmsz 前应当配置好钥匙
  1. 主程序可以在 kmscript 启动前直接修改 w3sc.conf 文件中的钥匙值，具体参见 w3sc.json 文件定制
  2. 主程序可以不必实现自己的钥匙机制而依赖 kmscript 的锁和钥匙机制，在启动时主程序要求用户输入一个 kmscript 钥匙，并修改到 w3sc.conf 文件即可
    1. 如果钥匙无效，则带锁 kmsz 运行失败
5. kmsz 可以调用并保存一个图片文件，从而主程序可以取得 kmscript 图像源中区域图片文件
  1. 可以利用例如颜色分离取得的坐标、尺寸变量作为裁剪参数调用保存图片
  2. 多个通道连接（多个TCP 连接）彼此互通，始终共享相同的工作区、变量
6. 主程序可以利用 kmscript 的从机监控提供状态给用户而自己潜默运行
7. 主程序可以利用 kmscript 的端口映射使主程序也能提供公网连接

骨骼配置：ui，值：li_tag