PUSH通知

本章节仅为HarmonyOS Agent通信协议定义的Push通知，而非华为Push推送服务。

Agent Server发送Push给Agent Client请求消息：

curl 'https://hag.cloud.huawei.com/open-ability-agent/v1/agent-webhook' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'x-hag-trace-id: {{客户端使用随机数生成。}}' \ 
-H 'X-Access-Key: {{从小艺开放平台获取的触发器事件WebHook分配的appKey}}' \
-H 'X-Sign: {{从小艺开放平台获取的触发器事件WebHook分配的secretKey生成的签名，参数签名=Base64（HMAC-SHA256（secretKey， ts））。 其中secretKey 为开发者在小艺开放平台上配置的接入密钥（secretKey）}}' \
-H 'X-Ts: {{时间戳，用于加密和缓存穿透。 格式为：当前计算机时间和GMT时间（格林威治时间）1970年1月1号0时0分0秒所差的毫秒数。 例如：2018/1/1 08:00:00.000 的时间戳为"1514764800000"}}' \
-d '{
    "jsonrpc": "2.0",
    "id": "{{与agent-server通信的全局唯一消息序列号，给agent-server答复请求结果时需取出返回}}",
    "result": {
        "id": "{{使用请求中的该字段返回，一次流式交互中（从发起本次请求到本次请求完成处理之间）保持不变}}",
        "apiId": "{{创建api时生成的API ID，CP请求时带上}}", 
        "pushId": "{{请求时使用平台系统变量push_id，代表通过webhook推送通知时使用的唯一ID。}}",
        "agentLoginSessionId":"{{账号授权时三方Agent服务器提供的用户授权身份ID。}}", 
        "pushText": "{{Push通知的展示内容，按Push服务规格提供}}",
        "kind": "{{事件类型，值为task}}",
        "artifacts": [
            {
                "artifactId": "{{本条Artifact的唯一ID，用于CP请求消息的去重}}",
                "parts": [
                    {
                        "kind": "text",
                        "text": "{{agent-server处理的响应，如果是markdown流式输出也在此处存放}}"
                    },
                    {
                        "kind": "data",
                        "data": "{{结构化数据，以JSONObject形式存放，承载用户结果过程数据及A2A的扩展字段}}"
                    }
                ]
            }
        ],
    "status": {
            "state": "{{任务状态，取值为[completed|canceled|failed]其中之一}}"
        }
    },
    "error": {
        "code": "{{JSONRPCError错误码，整型类型}}",
        "message": "{{JSONRPCError错误描述}}"
    }
}'

上述X-Sign的计算方法如下：

1）防重放

出于防重放攻击的需要，服务端应该校验报文中的ts和当前实际时间相差在一个范围内。

例如：校验服务器侧时间戳与请求报文中的时间戳差值的绝对值（ABS），小于15分钟。

2）签名算法

Sign的计算代码示例，服务器侧可以基于ts计算该sign，与请求中的sign比对是否相等，以达到验证客户端身份的目的。

String secret = "密钥";
String ts = "从消息头中获取ts";
Mac mac = Mac.getInstance("HmacSHA256");
SecretKey secretKey = new SecretKeySpec(secret.getBytes(SystemCharsets.UTF_8), "HmacSHA256");mac.init(secretKey);
byte[] byteHMAC = mac.doFinal(ts.getBytes(SystemCharsets.UTF_8));
byte[] sign = Base64.getEncoder().encode(byteHMAC);

例如：secret 为 2e3b71f5def64d95a727314f028bf5aa， ts为1547630863716时，签名结果应该为：6lFqepUu79KSxVCsrXyB/aLVFIdutsTLLx1cZjxDE4I=。

Agent Server发送Push给Agent Client响应消息：

其中，id：对应请求体id；resultId：对应请求体的result.id。

{
  "id": "43667960-d455-4453-b0cf-1bae4955270d",
  "resultId": "c295ea44-7543-4f78-b524-7a38915ad6e4",
  "result": {
      "code": "{{JSONRPCError错误码，整形类型}}",
      "message": "{{JSONRPCError错误描述}}"
  }
}

目录

PUSH通知