回调服务接入指南

说明

火山引擎云手机-iPaaS支持通过 HTTP 或 HTTPS 协议将账号业务下云手机实例资源的状态变动等事件消息推送到接入方提供的 URL 回调地址。接入方在接收到消息后，可按照下述消息内容格式做进一步处理或消费。

接入配置

接入云手机-iPaaS回调服务需要完成以下配置：

1. 配置业务维度的回调消息接收地址：接入方需提供公网可访问的 URl 回调地址，并在云手机业务维度配置并订阅了相关事件的回调消息（可通过火山引擎 云手机控制台 > 业务管理 > 功能配置 页面进行配置；详细信息，参考 控制台指南）。

2. 配置用于鉴权的 AccessKey 和 SecretKey（AK、SK），请求时会通过 AK、SK 计算出签名，接入方可以自行验证（可通过火山引擎 云手机控制台 > 业务管理 > 功能配置 页面进行配置；详细信息，参考 控制台指南）。

重试机制

首次推送失败后（非成功响应），回调服务将每隔1秒重推消息。若重试3次仍未成功，将停止推送，超时时长为5秒。

参数说明

请求格式

Header

Body

格式：json

AsyncTaskEvent 结构说明

任务类型说明

参考示例：

{
    "id": "13579xyz24680",
    "event_type": "AsyncTask",    
    "event_async_task": {
        "instance_id":"i-1748455288xxxxxx",
        "host_id":"h-1248455288xxxxxx",
        "global_task_id":"t-7187279730302xxxxxx",
        "task_type":"ResetFactory",
        "task_status":200,
        "content": "instance reset factory success",
        "start_time":1672143930,
        "end_time":1672143938
    }
}

InstanceStatusEvent 结构说明

Status 具体定义

参考示例：

{
    "id": "13579xyz24680",
    "event_type": "InstanceStatus",
    "event_instance_status": {
        "instance_id": "i-1776357725xxxxxx",
        "from_status": 519,
        "from_status_str": "ColdRebooting",
        "to_status": 256,
        "to_status_str": "Running"
    }
}

返回格式

附件

鉴权及签名计算流程

接收到请求后，执行以下验证过程：

1. 可选项，建议按照如下方式进行检查操作： 检查时间戳，如果不符合以下条件直接返回403（防重放攻击）：timestamp - 5分钟 < 服务器接收到请求时间 < timestamp + expiretime + 5分钟。

2. 必选项： 通过 AK 找到对应的 SK，使用相同的摘要算法生成认证字符串，并与用户请求中包含的认证字符串进行比对。

3. 如果认证字符串相同，系统认为用户合法，并执行后续的用户权限验证的相关操作。

4. 如果认证字符串不同，系统将忽略该操作并返回 HTTP code 403。

流程及参数说明

按以下流程生成认证字符串（可参考后面的代码示例）：

1. 以 $auth_ver/$access_key/$timestamp/$expiretime 为认证字符串前缀。

2. 使用 基于sha256的HMAC摘要算法，以 secret_key 为 key， 对认证字符串前缀生成摘要 sign_key。

3. POST 请求：保证不被篡改的参数放入请求的 body 部分，序列化生成 sign_content，用同样的摘要算法，以上一步得到的 sign_key 对 sign_content 生成摘要 signature。

4. 最终的认证字符串为：

$auth_ver/$access_key/$timestamp/$expiretime/$signature

5. 把认证字符串放在 HTTP 请求的 Header 中：

iPaaS-Auth：$auth_ver/$access_key/$timestamp/$expiretime/$signature

代码示例

Golang

import (
    "crypto/hmac"
    "crypto/sha256"
    "fmt"
    "time"
)

func sha256HMAC(key []byte, data []byte) []byte {
    mac := hmac.New(sha256.New, key)
    mac.Write(data)
    return []byte(fmt.Sprintf("%x", mac.Sum(nil)))
}

func Sign(ver string, ak string, sk string, signContent []byte) string {
    expiration := 1800  
    signKeyInfo := fmt.Sprintf("%s/%s/%d/%d", ver, ak, time.Now().Unix(), expiration)
    signKey := sha256HMAC([]byte(sk), []byte(signKeyInfo))
    signature := sha256HMAC(signKey, signContent)
    return fmt.Sprintf("%v/%v", signKeyInfo, string(signature))
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static String Sha256HMAC(String key, byte[] data) throws Exception {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec keySpec = new SecretKeySpec(key.getBytes(), "HmacSHA256");
    sha256_HMAC.init(keySpec);
    byte[] hash = sha256_HMAC.doFinal(data);

    byte[] hexChars = new byte[hash.length * 2];
    for ( int j = 0; j < hash.length; j++ ) {
        byte[] s = String.format("%02x", hash[j] & 0xFF).getBytes();
        hexChars[j * 2] = s[0];
        hexChars[j * 2 + 1] = s[1];
    }
    return new String(hexChars);
}

public static String Sign(String ver, String ak, String sk, byte[] data) throws Exception {
    int expiration = 1800;  
    long timestamp = System.currentTimeMillis() / 1000L;
    String signKeyInfo = String.format("%s/%s/%d/%d", ver, ak, timestamp, expiration);
    String signKey = Sha256HMAC(sk, signKeyInfo.getBytes());
    String signature = Sha256HMAC(signKey, data);
    return String.format("%s/%s", signKeyInfo, signature);
}