跳至主要內容

项目 HTTP API

约 4554 字大约 15 分钟

项目 HTTP API

项目 HTTP API 为您提供了项目级别的 API 接口,包括对项目、设备类型、设备组、设备信息、设备扩展信息、设备数据、设备通信、设备告警、用户等全面的资源访问,采用 HTTP RESTful API 风格。

准备工作

获得项目 API 接入地址

在 ThingsCloud 控制台的项目中,进入任意设备的详情页,在 连接 页面中可以找到 应用端 API 接入点,请使用 https 加密访问,确保数据安全性。

不同项目的 API 接入点可能不同,请您以控制台获取的地址为准。

创建 API 应用

在正式使用 API 之前,您还需要进入 ThingsCloud 控制台 > 项目应用,创建 API 类型的项目应用,获得 AppID 和 API Key,用于请求 API 时的身份验证。

API 请求代码示例

以获取 API AccessToken 为例,以下是常用编程语言请求 API 的示例代码,仅供参考:

NodeJS
const axios = require('axios');

const postData = {
  app_id: '<app_id>',
  access_key: '<access_key>',
  secret_key: '<secret_key>'
};

axios.post('https://<api-endpoint>/api/v1/access_token', postData, {
  headers: {
    'Content-Type': 'application/json'
  }
})
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

获取 AccessToken

通过身份验证 API,获得 AccessToken,用于所有 API 请求的身份标识。

提示

请注意,项目 HTTP API 中的 AccessToken 不是 设备证书中的 AccessToken,它们只是名字相同,没有任何关系,请勿混用。

身份验证支持以下两种方式:

服务器获取 AccessToken

通过服务器发起请求,获取 AccessToken。这种方式,API 密钥保存在服务器,可有效防止泄露。

AccessToken 获取后的有效期为 1 天,过期后请重新获取。

Request Syntax

POST /api/v1/access_token HTTP/1.1
Content-Type: application/json

Request Body

{
	"app_id": "string",
	"access_key": "string",
	"secret_key": "string"
}
  • app_id:在控制台项目应用中获取。
  • access_key:在控制台项目应用中获取。
  • secret_key:在控制台项目应用中获取。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "access_token": "string",
        "expires_in": 86400
    }
}

浏览器获取 AccessToken

通过管理账号和密码,获取 AccessToken。该方式适用于在浏览器网页中由用户输入账号和密码,通过浏览器发起请求,并将成功获取的 AccessToken 保存到 Cookies 中,请求其它 API 时使用。

AccessToken 获取后的有效期为 7 天,过期后请重新获取。

Request Syntax

POST /api/v1/admin_login HTTP/1.1
Content-Type: application/json

Request Body

{
	"app_id": "string",
	"account": "string",
	"password": "string"
}
  • app_id:在控制台项目应用中获取。
  • account:在控制台创建管理员时填写账号名称。
  • password:在控制台创建管理员时填写密码。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "access_token": "string"
    }
}

项目信息

读取项目信息

读取当前项目的信息。

Request Syntax

GET /api/v1/project HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string",
        "descr": "string",
        "tags": {}
    }
}

读取设备状态统计

读取项目中所有设备基本状态的统计。

Request Syntax

GET /api/v1/devices_stat HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "device_total": number,
        "online_device_total": number,
        "offline_device_total": number,
        "active_device_total": number,
        "inactive_device_total": number,
        "alarm_device_total": number
    }
}
  • device_total:总设备数
  • online_device_total:在线设备数
  • offline_device_total:离线设备数
  • active_device_total:活跃设备数
  • inactive_device_total:非活跃设备数
  • alarm_device_total:告警设备数

读取设备告警状态统计

读取项目中所有设备告警状态的统计。

Request Syntax

GET /api/v1/devices_alarm_stat HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "device_total": number,
        "alarm_1_total": number,
        "alarm_2_total": number,
        "alarm_3_total": number,
        "normal_total": number,
    }
}
  • device_total:总设备数
  • alarm_1_total:普通告警设备数
  • alarm_2_total:严重告警设备数
  • alarm_3_total:紧急告警设备数
  • normal_total:正常设备数

设备类型

读取设备类型列表

读取所有设备类型列表。

Request Syntax

GET /api/v1/device_types HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "name": "string",
                "descr": "string",
                "tags": {
                    "key1": "string",
                    "key2": "string"
                },
                "create_time": number,
                "device_count": number,
                "conn_protocol": "string",
                "conn_type": "string"
            },
            ...
        ]
    }
}
  • items:设备类型信息结构体数组

读取设备类型下的设备列表

请见 读取设备列表

读取设备类型扩展信息定义

读取指定设备类型的扩展信息定义。

Request Syntax

GET /api/v1/device_type/<device_type_id>/extend_infos HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_type_id:设备类型 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "info_type": "string",
                "name": "string",
                "descr": "string",
                "enabled": boolean,
                "options": {},
                "create_time": number,
                "update_time": number,
                "is_standard": boolean
            },
        ]
    }
}

设备组

读取设备组树形列表

读取所有设备组的树形列表,包含子组。

Request Syntax

GET /api/v1/device_groups_tree HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "name": "string",
                "descr": "string",
                "tags": {
                    "key1": "string",
                    "key2": "string"
                },
                "create_time": number,
                "children": [
                    {
                        "id": "string",
                        "name": "string",
                        "descr": "string",
                        "tags": {
                            "key1": "string",
                            "key2": "string"
                        },
                    }
                    ...
                ]
            },
            ...
        ]
    }
}
  • items:设备组信息结构体数组

读取设备组下的设备列表

请见 读取设备列表

设备管理

读取设备列表

读取所有设备列表。

Request Syntax

GET /api/v1/devices HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Query

  • page:可选,页码,默认为 1
  • type:可选,指定设备类型 ID
  • group:可选,指定设备组 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "name": "string",
                "descr": "string",
                "device_key": "string",
                "tags": {
                    "key1": "string",
                    "key2": "string"
                },
                "create_time": number,
                "alarm": {},
                "active": {},
                "online": boolean,
                "type": "string",
                "type_info": {
                    "id": "string",
                    "name": "string",
                    "conn_type": "string",
                    "conn_protocol": "string"
                }
            },
            ...
        ],
        "total": number,
        "page_total": number,
    }
}
  • total:设备总数
  • page_total:总页数
  • items:设备信息结构体数组

设备信息结构体主要字段说明:

  • alarm:设备告警状态信息结构
  • active:设备各类消息最新时间戳
  • online:设备在线状态

读取设备信息

读取指定设备的信息。

Request Syntax

GET /api/v1/device/<device_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string",
        "descr": "string",
        "device_key": "string",
        "tags": {
            "key1": "string",
            "key2": "string"
        },
        "create_time": number,
        "alarm": {},
        "active": {},
        "online": boolean,
        "type": "string",
        "type_info": {
            "id": "string",
            "name": "string",
            "conn_type": "string",
            "conn_protocol": "string"
        },
        "groups": [
            "string",
            "string"
        ],
        "view_token": "string",
        "device_code": "string"
    }
}

读取设备证书

读取指定设备的连接证书。

Request Syntax

GET /api/v1/device/<device_id>/certificate HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string",
        "access_token": "string",
        "project_key": "string"
    }
}

读取设备用户列表

读取指定设备关联的所有用户。

Request Syntax

GET /api/v1/device/<device_id>/customers HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

参考 读取用户列表

修改设备基本信息

修改指定设备的基本信息。

Request Syntax

PUT /api/v1/device/<device_id>/info HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "name": "string",
    "descr": "string",
    "device_key": "string"
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

修改设备标签

修改设备的标签。

Request Syntax

PUT /api/v1/device/<device_id>/tags HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "tags": {
        "key1": "string",
        "key2": "string",
        ...
    }
}
  • tags:要更新或增加的标签集合

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

移除设备标签

移除设备的标签。

Request Syntax

POST /api/v1/device/<device_id>/tags_remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "keys": [
        "string",
        "string",
        ...
    ]
}
  • keys:要移除的标签 Key 数组,可同时移除一个或多个标签。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

修改设备分组

修改设备所在的分组。

Request Syntax

PUT /api/v1/device/<device_id>/groups HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "groups": [
        "string",
        "string",
        ...
    ]
}
  • groups:要更新的分组 ID 数组。空数组表示设备不属于任何分组。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

移除设备

移除指定设备。

Request Syntax

DELETE /api/v1/device/<device_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

创建设备

创建新设备。

Request Syntax

POST /api/v1/device HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Body

{
    "name": "string",
    "descr": "string",
    "type": "string",
    "tags": {},
    "device_key": "string"
}
  • name:必填,设备名称。
  • descr:选填,备注信息。
  • type:选填,设备类型 ID。
  • tags:选填,标签键值对。
  • device_key:选填,设备唯一标识。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string"
    }
}

设备扩展信息

读取设备扩展信息

读取指定设备的所有扩展信息。

Request Syntax

GET /api/v1/device/<device_id>/extend_infos HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "info_type": "string",
                "name": "string",
                "descr": "string",
                "value": "string"|boolean|number|object,
                "options": {},
                "create_time": number,
                "update_time": number,
                "is_standard": boolean
            },
        ]
    }
}

修改设备标准扩展信息

修改指定设备的标准扩展信息。

Request Syntax

POST /api/v1/device/<device_id>/standard_infos HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "info_type": "string",
    "value": {
        "key": "string"|boolean|number
    }
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "<info_type>": {
            "key": "string"|boolean|number
        }
    }
}

返回的 info 中会显示更新成功的扩展信息。

修改设备自定义扩展信息

修改指定设备的标准扩展信息。

Request Syntax

POST /api/v1/device/<device_id>/extend_infos HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "infos": {
        "<info-id-1>": "string"|boolean|number,
        "<info-id-2>": "string"|boolean|number,
        ...
    }
}
  • <info-id>:自定义扩展信息的 ID,可通过设备类型扩展信息定义接口获得。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "<info-id-1>": "string"|boolean|number,
        "<info-id-2>": "string"|boolean|number,
        ...
    }
}

返回的 info 中会显示更新成功的扩展信息。

设备数据

读取设备属性列表

读取设备的所有属性列表,包含相关的属性定义。

Request Syntax

GET /api/v1/device/<device_id>/attributes HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": [
        {
            "identifier": "string",
            "value": value,
            "attr_type": "string",
            "data_type": "string",
            "ts": number,
            "model": {
                "name": "string",
                "attr_type": "string",
                "data_type": "string",
                "data_options": {
                    
                }
            }
        },
    ]
}

读取设备当前属性集合

读取设备当前属性的集合,只包含属性标识符和属性值。

Request Syntax

GET /api/v1/device/<device_id>/attributes_raw HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "temperature": 24.1,
        "humidity": 56.8,
        "relay1": true,
        "relay2": false,
        "relay3": false
    }
}

读取设备属性历史数据

读取设备指定属性的历史数据。

Request Syntax

GET /api/v1/device/<device_id>/attribute/<identifier>/series HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID
  • identifier:属性标识符

Request Query

  • page:可选。页码,默认为 1
  • page_records:可选。每页记录数,数值范围为 1-100,默认为 20
  • start_time:可选。指定历史数据的开始时间,单位是 ms。
  • end_time:可选。指定历史数据的结束时间,单位是 ms。

start_timeend_time 同时指定时可查询指定时间范围的历史数据,否则默认查询从当前时间往前的历史数据。指定的时间范围最长不能超过 30 天。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": [
        {
            "ts": number,
            "name": "string",
            "value": value,
            "type": "string"
        },
        ...
    ]
}

移除设备属性

移除设备的指定属性,可同时移除一个或多个属性。

Request Syntax

POST /api/v1/device/<device_id>/attributes_remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "keys": [
        "string",
        "string",
        ...
    ]
}
  • keys:要移除的属性标识符数组,可包含多个属性标识符。例如
{
    "keys": [
        "temperature",
        "humitidy"
    ]
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

设备通信

下发属性到设备

向设备下发属性数据。

Request Syntax

POST /api/v1/control/device/<device_id>/attributes HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "key1": value,
    "key2": value,
    ...
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

更新云端属性

更新设备的云端属性。

Request Syntax

PUT /api/v1/control/device/<device_id>/attributes HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "key1": value,
    "key2": value,
    ...
}

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

下发命令到设备

向设备下发命令消息。

Request Syntax

POST /api/v1/control/device/<device_id>/command HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Request Body

{
    "method": "string",
    "params": {},
    "id": number
}

下发命令消息的详细介绍,请浏览 设备接收云端下发命令

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

下发自定义数据流到设备

向设备下发自定义数据流消息。

Request Syntax

POST /api/v1/control/device/<device_id>/data/<identifier>/set?push_mode=<push_mode> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID
  • identifier:自定义数据流标识符,例如:stream
  • push_mode:自定义数据流下发通道,可填 mqtt 或 tcp

Request Body

{
    "type": "string",
    "message": "string" | {},
}

根据自定义数据流设置的不同消息类型,API 请求正文的具体用法举例如下:

  • 下发 HEX 消息格式
{
    "type": "hex",
    "msg": "01 03 01 FF 00 0C 74 03"
}
  • 下发 Plaintext 消息格式
{
    "type": "text",
    "msg": "t:45,u=31"
}
  • 下发 JSON 消息格式
{
    "type": "json",
    "msg": {
        "command": "openLock",
        "led": "ON",
        "stat": "011001"
    }
}

关于自定义数据流的基本概念,请浏览 自定义数据流

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

设备告警

读取所有告警消息

读取项目中的所有告警消息历史。

Request Syntax

GET /api/v1/alarm_logs HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            "id": "string",
            "device_id": "string",
            "alarm_status": number,
            "alarm_level": number,
            "alarm_info": {},
            "create_time": number,
            "notify_logs": [],
            "device": {
                "id": "string",
                "name": "device2"
            }
        ]
    }
}

读取设备告警消息

读取指定设备的告警消息历史。

Request Syntax

GET /api/v1/device/<device_id>/alarm_logs HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • device_id:设备 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            "id": "string",
            "device_id": "string",
            "alarm_status": number,
            "alarm_level": number,
            "alarm_info": {},
            "create_time": number,
            "notify_logs": [],
            "device": {
                "id": "string",
                "name": "device2"
            }
        ]
    }
}

用户管理

读取用户列表

读取项目中的所有用户列表。

Request Syntax

GET /api/v1/customers HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "account": "string",
                "name": "string",
                "descr": "string",
                "role_id": "string",
                "email": "string",
                "mobile": "string",
                "tags": {},
                "locale": "string",
                "create_time": number,
                "count": {
                    "device_count": number
                }
            }
        ]
    }
}

读取用户角色列表

读取项目中的所有用户角色列表。

Request Syntax

GET /api/v1/customer_roles HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "items": [
            {
                "id": "string",
                "name": "string",
                "descr": "string",
                "allow_operate_device": boolean,
                "allow_alarm_msg_maintain": boolean,
                "allow_add_device": boolean,
                "create_time": number,
                "customer_count": number
            }
        ]
    }
}

读取用户信息

读取指定用户的信息。

Request Syntax

GET /api/v1/customer/{customer_id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id:用户 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "account": "string",
        "name": "string",
        "descr": "string",
        "email": "string",
        "mobile": "string",
        "tags": {},
        "locale": "string",
        "create_time": number,
        "count": {
            "device_count": number
        }
    }
}

读取用户设备列表

读取用户关联的设备列表。

Request Syntax

GET /api/v1/customer/<customer_id>/devices HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id:用户 ID

Request Query

  • page:可选,页码,默认为 1

Response Syntax

参考 读取设备列表

创建用户

为项目创建新用户。

Request Syntax

POST /api/v1/customer HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Body

{
    "name": "string",
    "account": "string",
    "password": "string",
    "descr": "string",
    "email": "string",
    "mobile": "string",
    "tags": {}
}
  • name:必填,用户名称。
  • account:必填,用户登录名。
  • password:必填,用户登录密码。
  • descr:选填,备注信息。
  • email:选填,用户邮箱。
  • mobile:选填,用户手机号。
  • tags:选填,标签键值对。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string"
    }
}

修改用户信息

修改指定用户的基本信息。

Request Syntax

PUT /api/v1/customer/<customer_id>/info HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id:用户 ID

Request Body

{
    "name": "string",
    "descr": "string",
    "email": "string",
    "mobile": "string"
}
  • name:选填,用户名称。
  • descr:选填,备注信息。
  • email:选填,用户邮箱。
  • mobile:选填,用户手机号。

以上字段至少填写一个,可修改一个或多个字段。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

修改用户密码

修改指定用户的登录信息。

Request Syntax

PUT /api/v1/customer/<customer_id>/pwd HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id:用户 ID

Request Body

{
    "password": "string",
}
  • password:必填,用户登录密码。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

修改用户标签

修改指定用户的标签。

Request Syntax

PUT /api/v1/customer/<customer_id>/tags HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id:用户 ID

Request Body

{
    "tags": {
        "key1": "string",
        "key2": "string",
        ...
    }
}
  • tags:要更新或增加的标签集合

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

移除用户

移除指定的用户账号。

Request Syntax

DELETE /api/v1/customer/<customer_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Parameters

  • customer_id:用户 ID

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {}
}

用户登录验证

验证用户账号和密码是否正确。

Request Syntax

POST /api/v1/customer_auth HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Request Body

{
    "account": "string",
    "password": "string",
}
  • account:必填,用户登录名。
  • password:必填,用户登录密码。

Response Syntax

  • 验证成功
HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "name": "string"
    }
}
  • 验证失败
HTTP/1.1 200 OK
Content-type: application/json

{
    "result": false,
    "errcode": number,
    "message": "string"
}

管理员管理

读取当前登录的管理员信息

读取当前登录的管理员信息,仅在通过管理员账号获取 AccessToken 时可用。

Request Syntax

GET /api/v1/admin HTTP/1.1
Content-Type: application/json
Authorization: Bearer <AccessToken>

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        "id": "string",
        "account": "string",
        "name": "string",
        "email": "string",
        "tags": {}
    }
}

全局定义

Response Syntax

请求功能处理成功

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": true,
    "info": {
        ...
    }
}

请求功能处理失败

HTTP/1.1 200 OK
Content-type: application/json

{
    "result": false,
    "errcode": number,
    "message": "string",
    "errors": [],
}

请求资源错误

当请求的 API 资源路径不存在时,返回如下:

HTTP/1.1 404 Not Found
Content-type: application/json

{
    "message": "Request invalid"
}

请求 JSON 格式错误

当请求正文的 JSON 格式错误时,返回如下:

HTTP/1.1 404 Not Found
Content-type: application/json

{
    "result": false,
    "message": "Invalid JSON message",
    "errcode": 400
}