IAAS OPEN-API接入文档

1.简介

2.修改历史

3. OPEN-API概览

OPEN API大都为JSON格式的HTTP API，方便各业务方接入使用

3.1 接入地址

线上接入域名: openapi.axicomin.cn

3.1.1 接口查询限制

单供应商单接口每分钟限制查询100次

3.2 鉴权

3.2.1 组成

鉴权参数由3个部分组成, 放入到HTTP Header中

cloud-id 接入ID, 字符串。一般为供应商ID, 申请后分配
timestamp 时间戳(精确到秒), 创建认证Token时的时间戳, 前后10分钟内有效
uthorization 认证token, 计算后生成

// HTTP Header
cloud-id: test_suppiler
timestamp: 1730713268
authorization: f3dc0f4e8a7e674d043459ba4055d159

3.2.2 计算方法

鉴权Token由以下参数组合计算得来。

cloud_id (同上)
timestamp (同上)
http query, HTTP请求的Query部分, 按照字段的字母顺序排列后构成。不存在则为空串
http request body, HTTP请求的Request Body部分内容, 字符串形式。不存在则为空字符串
accesssecretkey 认证的密钥; 根据cloud-id分配得来
鉴权方式: + 将httpquery, httpbody, accesssecretkey, timestamp(字符串) 拼接成一个字符串X + 然后对X计算MD5，即为token
鉴权方式: + 将httpquery, httpbody, accesssecretkey, timestamp(字符串) 拼接成一个字符串X + 然后对X计算MD5，即为token
鉴权参考Python代码如下:

import hashlib

def generate_token():
    cloud_id = "test_suppiler"

    # 取当前临近时间。前后10min内有效
    timestamp = 1730713268

    # 按照query field字母序排列, 不存在则http_query = ''
    http_query = "a=1&b=2&c=3"

    # 需要跟实际传给API的request body一致的字符串, 不存在则http_body = ''
    http_body = '{"aa":123,"bb":456}'

    access_secret_key = "test_access_secret_key"

    data = [b"",b"", b"", b""]
    data[0] = http_query.encode('utf-8')
    data[1] = http_body.encode('utf-8')
    data[2] = access_secret_key.encode('utf-8')
    data[3] = str(timestamp).encode('utf-8')

    md5_hash = hashlib.md5()
    md5_hash.update(b"".join(data))
    return md5_hash.hexdigest()

鉴权参考Golang代码如下:

package main

import (
    "crypto/md5"
    "encoding/hex"
    "fmt"
    "strconv"
)

func generateToken() string {
    // cloudID := "test_suppiler"

    // Current timestamp, assuming it's within a 10-minute range.
    timestamp := 1730713268

    // Query field in alphabetical order, or empty if not present
    httpQuery := "a=1&b=2&c=3"

    // Request body as a string or empty if not present
    httpBody := `{"aa":123,"bb":456}`

    accessSecretKey := "test_access_secret_key"

    // Prepare the data slices in the same order as Python code
    data := []byte(httpQuery + httpBody + accessSecretKey + strconv.Itoa(timestamp))

    // Generate the MD5 hash
    hash := md5.Sum(data)

    // Convert the hash to a hex string
    return hex.EncodeToString(hash[:])
}

func main() {
    token := generateToken()
    fmt.Println("Generated token:", token)
}

3.3 查询接口列表

3.3.1 供应商月账单查询

POST: /iaas/v1/supplier/monthbill
Request:

{
    // 查询月份, string, 必要参数
    "month": "2024-10"
}

Response:

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        // 被查询月份, string
        "month": "2024-10",
        // 合计收入, double, RMB
        "amount": 888888.88,
        // 具体收入列表, array
        "incomes": [
            {
                // 计费分组, string, 设备录入时填写
                "group": "default",
                // 计费模型, enum, 1:日95月平均
                "model": 1,
                // 分组收入, double, RMB
                "income": 8888.88,
                // 计费带宽列表, array, 根据计费模型展示。如日95维度
                "bandwidths": [
                    {
                        // 时间, string
                        "time": "2024-10-01 00:00:00",
                        // 对应维度的带宽(Mbps), double
                        "upload": 7777.77
                    }
                ]
            }
        ]
    }
}

3.3.2 供应商日维度+设备维度收益查询

POST: /iaas/v1/supplier/income/device
Request:

{
    // 起始时间, string, 必要参数
    "start_date": "2024-10-01",
    // 结束时间, string, 必要参数
    "end_date": "2024-10-11",

    // 设备ID, array, 必要参数, 最少1个,最多20个
    "devices": ["test_device"]
}

Response:

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        "incomes": [
            {
                // 设备ID, string, 设备录入时填写
                "device": "test_device",
                // 计费模型, enum, 1:日95月平均
                "model": 1,
                // 日维度收入, double, RMB
                "income": 8888.88,
                // 根据计费模型得到的带宽。比如在日95月平均模型上,此带宽为日95月平均的带宽值。Mbps
                "bandwidth": 6666.66,
                // 具体带宽列表汇聚, array, 根据计费模型统计,一般为日95带宽值
                "bandwidths": [
                    {
                        // 时间, string
                        "time": "2024-10-01 00:00:00",
                        // 对应维度的带宽(Mbps), double
                        "upload": 7777.77,
                        // 设备最大的带宽上限(仅录入存在时返回), double
                        "upload_bandwidth_capacity": 10000,
                        // 设备带宽利用率%, double, 录入存在时返回,
                        "upload_bandwidth_rate": 77.7
                    }
                ],
                // 计费周期, array, 2值, 表示前后开始和结束时间
                "time_range": ["2024-10-01 00:00:00", "2024-10-11 23:59:59"]
            }
        ]
    }
}

单设备模糊查询;性能比较差,当前仅支持单次单个设备查询
POST: /iaas/v1/supplier/income/fuzzydevice
Request:

{
    // 起始时间, string, 必要参数
    "start_date": "2024-10-01",
    // 结束时间, string, 必要参数
    "end_date": "2024-10-11",

    // 设备ID公共部分, 必要参数, 最多单次仅支持一个。标记部分最小要10位字符串
    "device": "test_device",

    // 展示形式, 默认为0
    // 0, 表示将这些容器单独展示, 计算各自的95%
    // 1, 表示将这些容器的数据进行合并计算, 进行展示
    "data_style": 0,
}

Response:

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        "incomes": [
            {
                // 设备ID, string, 设备录入时填写
                "device": "test_device",
                // 计费模型, enum, 1:日95月平均
                "model": 1,
                // 日维度收入, double, RMB
                "income": 8888.88,
                // 根据计费模型得到的带宽。比如在日95月平均模型上,此带宽为日95月平均的带宽值。Mbps
                "bandwidth": 6666.66,
                // 具体带宽列表汇聚, array, 根据计费模型统计,一般为日95带宽值
                "bandwidths": [
                    {
                        // 时间, string
                        "time": "2024-10-01 00:00:00",
                        // 对应维度的带宽(Mbps), double
                        "upload": 7777.77,
                        // 具体贡献带宽的设备,仅在data_style=1时展示
                        "devices": ["device1", "device2", "device3"]
                    }
                ],
                // 计费周期, array, 2值, 表示前后开始和结束时间
                "time_range": ["2024-10-01 00:00:00", "2024-10-11 23:59:59"]
            }
        ]
    }
}

3.3.3 供应商日维度+设备组维度收益查询

POST: /iaas/v1/supplier/income/group
Request:

{
    // 起始时间, string, 必要参数
    "start_date": "2024-10-01",
    // 结束时间, string, 必要参数
    "end_date": "2024-10-11",

    // 设备组, array, 可选, 不填返回所有分组
    "group": ["default"]
}

Response:

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        "incomes": [
            {
                // 设备分组, string, 设备录入时填写
                "group": "default",
                // 计费模型, enum, 1:日95月平均
                "model": 1,
                // 日维度收入, double, RMB
                "income": 8888.88,
                // 根据计费模型得到的带宽。比如在日95月平均模型上,此带宽为日95月平均的带宽值。Mbps
                "bandwidth": 6666.66,
                // 带宽列表汇聚, array, 根据计费模型构建, 一般为日95值
                "bandwidths": [
                    {
                        // 时间, string
                        "time": "2024-10-01 00:00:00",
                        // 对应维度的带宽(Mbps), double
                        "upload": 7777.77
                    }
                ],
                // 计费周期, array, 2值, 表示前后开始和结束时间
                "time_range": ["2024-10-01 00:00:00", "2024-10-11 23:59:59"]
            }
        ]
    }
}

3.3.4 单设备带宽查询

带宽详细查询接口，效率不及日维度账单数据, 纯收益带宽数据查看3.3.2接口

POST: /iaas/v1/device/bandwidth
Request:

{
    // 起始时间, string, 必要参数
    "start_date": "2024-10-01",
    // 结束时间, string, 必要参数
    "end_date": "2024-10-11",

    // 设备ID, array, 必要参数, 最少1个, 最多20个
    "devices": ["test_deivce"],

    // 是否返回带宽详情列表。enum, 可选参数。默认0
    // 0 根据供应商设备分组自动适配
    // 1 5min维度
    // 2 小时维度
    // 3 日95维度
    "bandwidth_query_type": 0,
}

Response

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        // 具体设备数据, array
        "devices": [
            {
                // 设备ID, string
                "device": "test_device",
                // 设备分组, string
                "group": "default",
                "bandwidths": [
                    {
                        // 时间, string
                        "time": "2024-10-11 00:00:00",
                        // 带宽, double, Mbps
                        "upload": 6666.66
                    }
                ]
            }
        ],
        // 查询失败的设备, 出现异常时才会显示
        "errors": {
            // 找不到的设备SN
            "not_found": ["test_device1"],
            // 查询失败的设备SN
            "failed": ["test_device2"]
        }
    }
}

3.3.5 设备维度信息查询

POST: /iaas/v1/device/info
Request:

{
    // 起始时间(日期维度), string, 必要参数
    "start_date": "2024-10-01",
    // 结束时间(日期维度), string, 必要参数
    "end_date": "2024-10-11",

    // 设备ID, array, 必要参数, 最少1个, 最多20个
    "devices": ["test_deivce"],
}

Response

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        "devices": [
            {
                // 设备ID, string
                "device": "test_device",
                // 设备分组, string
                "group": "default",
                // 选定时间区间内最后一次探测的NAT类型, enum
                // 取值范围包括"Public", "FullCone", "RestrictedCone", "PortRestrictedCone", "Symmetric", "Unknown", "Error"
                "nat_type": "FullCone",
                // 公开IP, 0.0.0.0表示暂未采集或者录入
                "public_ip": "12.34.56.78",
                // 运营商信息, enum, 包括CTCC, CUCC, CMCC
                "asn": "CMCC",
                "sla": [{
                    // 日期, string
                    "date": "2024-10-01",
                    // 可用性描述, string, 取值看具体内容, 默认"ok"表示可用, 不在线则offline
                    "status": "ok",
                    // 不在线状态, 在status为offline时出现, 提示哪些设备哪些时段不在线
                    "offline": {
                        // 具体的设备SN
                        "test_device": {
                            // 具体的不在线时段
                            "offline_interval": ["12:00-12:05"]
                        }
                    }
                }]
            }
        ],
        // 查询失败的设备, 出现异常时才会显示
        "errors": {
            // 找不到的设备SN
            "not_found": ["test_device1"],
            // 查询失败的设备SN
            "failed": ["test_device2"]
        }
    }
}

3.3.6 供应商维度+设备分组维度信息查询

POST: /iaas/v1/device/list
Request:

{
    // 起始时间(日期维度), string, 必要参数
    "start_date": "2024-10-01",
    // 结束时间(日期维度), string, 必要参数
    "end_date": "2024-10-11",

    // 设备分组标记, string, 可选。默认default
    "group": "default",
    // 分页起始页, int, 可选。默认从1开始
    "page_index": 1,
    // 分页起始页, int, 可选。默认50，最大100
    "page_size": 50
}

Response

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        "page_index": 1,
        "page_size": 50,
        // 总共有多少页, int, 可选。
        "page_total": 10,
        "devices": [
            {
                // 设备ID, string
                "device": "test_device",
                // 设备分组, string
                "group": "default",
                // 选定时间区间内最后一次探测的NAT类型, enum
                // 取值范围包括"Public", "FullCone", "RestrictedCone", "PortRestrictedCone", "Symmetric", "Unknown", "Error"
                "nat_type": "FullCone",
                "public_ip": "12.34.56.78",
                // 运营商信息, enum, 包括CTCC, CUCC, CMCC
                "asn": "CMCC",
                "sla": [{
                    // 日期, string
                    "date": "2024-10-01",
                    // 可用性描述, string, 取值看具体内容, 默认"ok"表示可用, 不在线则offline
                    "status": "ok",
                }]
            }
        ]
    }
}

3.4 管理接口列表

3.4.1 设备组添加

POST: /iaas/v1/device/group/add
Request:

{
    "group_name":"android" // Group名称, string, 必要
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "group_name": "android",
        "group_id": 6 // group_id, uint, 用于修改等场景
    }
}

3.4.2 设备组修改

POST: /iaas/v1/device/group/update
Request:

{
    "group_name": "andorid", // 修改后的Group名称, string, 必要
    "group_id": 6 // 需要修改的GroupID, uint, 必要
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "group_name": "andorid",
        "group_id": 6
    }
}

3.4.3 设备组查询

POST: /iaas/v1/device/group/get
Request:

{
    "group_name":"andorid" // 需要查询的GroupName, string, 必要
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "group_name": "andorid",
        "group_id": 6
    }
}

3.4.4 设备组删除

POST: /iaas/v1/device/group/delete
Request:

{
    "group_name":"andorid", // Group名称, string, 必要
    "group_id":6 // GroupID, uint, 必要
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "group_name": "andorid",
        "group_id": 6
    }
}

3.4.5 设备添加

POST: /iaas/v1/device/info/add
Request:

{
    "group_name": "default", // Group名称, string, 可选。不填默认为default

    "device_sn": "test_device_1",
    // 设备SN, string, 必要。
    // 用于各接口的查询

    "device_pcdn_sn_list": "test_docker_1,test_docker_2",
    // 设备PCDN程序上登记的SN列表。string，可选。如不填，则默认跟device_sn一样。
    // 存在多个时，用逗号分隔，如test_docker_1,test_docker_2
    // 使用场景:
    // 1. 单容器单机器，如一个盒子设置或者X86只看各自容器，则device_sn可填对应的容器关联的SN, 比如test_docker1, 此时device_pcdn_sn_list可填可不填，填则继续写test_docker1
    // 2. X86机器，分了5个容器，分别是test_docker1, test_docker2... 如果想在查询时不关注分docker，只看总机器，则device_sn填写原机器sn为test_device_1, device_pcdn_sn_list为对应的test_docker1, test_docker2, 查询可用test_device_1
    // 3. 单容器单机器，便于查询。device_sn填写机器原本的sn信息，如device_sn=test_device_1, device_pcdn_sn_list填写test_docker1, 查询时可用原本sn进行使用

    "ipv4": "10.10.10.10", // IPV4地址，string，可选
    "nat_type": "FullCone",
    // nat类型，string enum，可选。
    // 取值范围包括"Public", "FullCone", "RestrictedCone", "PortRestrictedCone", "Symmetric", "Unknown"

    "bandwidth_capacity": 20000 // 容器对应带宽，uint，可选
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "group_name": "default",
        "group_id": 2, // 设备组ID，uint
        "device_id": 35, // 设备数字化ID, uint
        "device_sn": "test_device"
    }
}

3.4.6 设备信息更新

POST: /iaas/v1/device/info/update
Request:

{
    "device_id": 35, // 设备的数字化ID, uint, 必要。不可修改
    "device_sn": "test_device_2", // 设备的原SN, string, 必要

    "device_new_sn": "test_device_3", // 设备新的sn, 可选, 不想改就不用填和传
    "group_name": "default", // 设备组，string, 可选，不想改就不用填和传。对应的组需要存在, 否则会更新失败
    "ipv4": "10.10.10.11", // IPV4, string, 可选，不想改就不用填和传。
    "nat_type": "Public", // Nat类型，string枚举，可选，不想改就不用填和传。
    "bandwidth_capacity": 20000, // 带宽阈值，uint, 可选，不想改就不用填和传。
    "device_pcdn_sn_list": "test_device_2" // 子sn列表，stirng，可选，不想改就不用填和传。
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "device_id": 35,
        "device_sn": "test_device_3",
        "group_name": "default",
        "ipv4": "10.10.10.11",
        "nat_type": "Public",
        "bandwidth_capacity": 20000
    }
}

3.4.7 设备信息查询

POST: /iaas/v1/device/info/gets
Request:

{
    "device_sn_list": ["test_device_3"] // 设备SN列表, 字符串数组
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "total": 1, // 设备总数, uint
        "devices": [
            {
                "group_name": "default",
                "device_id": 35,
                "device_sn": "test_device_3",
                "ipv4": "10.10.10.11",
                "nat_type": "Public",
                "bandwidth_capacity": 20000,
                "device_pcdn_sn_list": "test_device_2"
            }
        ]
    }
}

3.4.8 设备信息失效

POST: /iaas/v1/device/info/invalidate
Request:

{
    "device_sn": "test_device_3",
    "device_id": 35
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "device_id": 35,
        "device_sn": "test_device_3"
    }
}

3.4.9 单设备模糊查询容器

POST: /iaas/v1/device/info/fuzzyget
Request:

{
    "device": "test_device" // 模糊查询设备部分,最小10位
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "total": 1, // 容器数量, uint
        "devices": [
            {
                "group_name": "default",
                "device_id": 35,
                "device_sn": "test_device_3",
                "ipv4": "10.10.10.11",
                "nat_type": "Public",
                "bandwidth_capacity": 20000,
                "device_pcdn_sn_list": "test_device_2"
            },
            {
                "group_name": "default",
                "device_id": 36,
                "device_sn": "test_device_4",
                "ipv4": "10.10.10.11",
                "nat_type": "Public",
                "bandwidth_capacity": 20000,
                "device_pcdn_sn_list": "test_device_2"
            }
        ]
    }
}

3.4.10 单设备带宽查询（合并容器，模糊查询）

根据设备的部分信息，模糊查询设备下所有容器的带宽之和。5min维度数据

POST: /iaas/v1/device/fuzzybandwidth
Request:

3.4.10 单设备带宽查询（合并容器，模糊查询）
根据设备的部分信息，模糊查询设备下所有容器的带宽之和。5min维度数据

POST: /iaas/v1/device/fuzzybandwidth
Request:

Response

{
    // 0为正常返回
    // 非0为异常, 具体错误信息参考msg
    "status": 0,
    "msg": "ok",
    "data": {
        // 具体设备数据, array
        "devices": [
            {
                // 模糊查询的关键词, string
                "label": "test_device",
                // 容器信息
                "devices": [
                    {
                        // 设备/容器ID
                        "device_sn": "test_device1",
                        // 设备/容器分组
                        "group": "default",
                        // 对后续带宽的贡献权重次数
                        "count": 20
                    }
                ],
                "bandwidths": [
                    {
                        // 时间, string
                        "time": "2024-10-11 00:00:00",
                        // 带宽, double, Mbps
                        "upload": 6666.66
                    },
                    {
                        // 时间, string
                        "time": "2024-10-11 00:00:05",
                        // 带宽, double, Mbps
                        "upload": 9999.99
                    }
                ]
            }
        ]
    }
}

3.4.11 列举当前供应商下所有设备

根据当前供应商, 查询其账号下的所有设备信息

POST: /iaas/v1/device/info/listbysupplier
Request:

{
    "page_index": 1, // 分页ID, 默认从1开始
    "page_size": 100, // 分页大小, 默认为100
    "start_time": "2025-04-20 22:22:01", // 过滤设备更新信息时间, 参考用, 不一定准确。可选，不填选择所有
    "end_time": "2025-04-22 22:22:01" // 过滤设备更新信息时间, 参考用, 不一定准确。可选，不填选择所有
}

Response

{
    "status": 0,
    "msg": "ok",
    "data": {
        "page_index": 1,
        "page_size": 100,
        "page_count": 50, // 当前这一页设备查询数量
        "start_time": "2025-04-20 22:22:01", // 输入填写设备过滤时间时才有
        "end_time": "2025-04-22 22:22:01",// 输入填写设备过滤时间时才有
        "devices": [
            {
                "device_sn": "PREFIX20d4SUFFIX1577838226895",
                "utime": "2025-04-05 10:00:12",
                "nat_type": "PortRestrictedCone",
                "ipv4": "183.197.137.181",
                "asn": "CMCC"
            },
            {
                "device_sn": "PREFIX6dc4SUFFIX1743670483692",
                "utime": "2025-04-05 10:00:12",
                "nat_type": "PortRestrictedCone",
                "ipv4": "183.197.137.181",
                "asn": "CMCC"
            },
        ]
    }
}

3.4.12 列举当前供应商下在线设备状态

根据当前供应商, 查询其账号下的所有设备PCDN_SN状态

POST: /iaas/v1/device/online
Request:

{
    "page_index":1, //分页ID, 默认从1开始
    "page_size": 200,  // 分页大小, 默认为100
	// 查询列表类型：
	//onlin只查询在线设备列表
	//all在线设备和离线设备列表
    "listtype":"onlin只查询在线设备列表
	//all在线设备和离线设备列表e"  
}

Response
其中选择参数是all,展示的设备中状态为1是在线，0为不在线

{
  'status': 0,
  'msg': 'ok',
  'logid': 'e1f76a3f-47fa-485a-9aa7-43923c2e74cb_ECOP-172-30-24-104-8051-0122115258-89441',
  'data': {
    'total': 104,
    'page': 1,
    'page_size': 200,
    'total_page': 1,
    'devices': [{
      'device_sn': 'aisiqin_dXQufdcHPr36dwRZx12tKigUHiQySYJc_14',
      'status': 1
    }, {
      'device_sn': 'aisiqin_oiSr2cbBpp6wnoxoRRRAY71AhgBs0pKq_54',
      'status': 0
    }, {
      'device_sn': 'aisiqin_xiBhFhYamdD5KUFbFGXCk4HkUqZUniHO_02',
      'status': 0
    }, {
      'device_sn': 'aisiqin_oiSr2cbBpp6wnoxoRRRAY71AhgBs0pKq_12',
      'status': 0
    }]
  }
}

3.4.12 搜索当前供应商下在线设备状态