一、应用场景
物联云平台提供后端API接口的注册和管理功能。第三方应用可以将开发完成的API接口注册至物联云平台，由物联云平台的网关进行统一的鉴权和认证访问权限。
物联云平台支持两种注册后端API接口的方式。第一种为第三方应用通过应用签名（Signature）进行后端API注册，第二种为平台内部服务通过平台权限（AccessToken）进行后端API注册。如果平台同时接收到两种认证方式（请求头中同时包含Signature和AccessToken），则优先识别为平台内部服务注册。
第三方应用注册到物联云平台，通过物联云平台网关进行鉴权。
基于物联云平台开发的后端API接口，注册至物联云平台统一认证。
二、功能说明
前往物联云平台管理台【应用中心->API网关->服务管理】中，创建一个服务。记录已创建服务名称，用于后端API注册时，设置为对应API所归属的服务。
第三方应用通过应用签名注册：前往物联云平台管理台【应用中心->应用网关】中，创建一个应用系统类型的应用。记录已创建应用的Appid和AppSecret，用于签名算法（SHA256）。
平台内部服务通过平台权限注册：前往物联云平台管理【系统设置->平台访问授权】中，添加一个授权。记录已创建授权的AccessKeyId和AccessKeySecret，用于获取AccessToken。使用AccessToken进行后端API注册。
三、前提条件
已创建对应的服务。
应用签名注册，需要已创建对应的应用网关。
平台权限注册，需要已创建的对应的AccessToken。
四、关键流程
4.1 外部SAAS系统注册API
流程说明：
- 首先，外部SAAS系统 从企业管理台获得 网关应用标识和应用秘钥 用作注册后端API必备条件。
- 其次，外部SAAS系统 解析需要注册的后端API，并对需要注册的后端API利用 网关应用标识和应用秘钥 进行签名，从而向物联网中台发起 后端API注册 请求。
- 最后，物联网中台接收到 后端API注册 请求进行一系列请求参数校验后，将注册的后端API定义为企业内部后端API，只能由所属企业进行访问。
4.2 后端API管理
流程说明：
- 首先，**B端成员 **登录到物联网中台，获得物联网中台调用凭证以及刷新凭证。
- 其次，B端成员 在企业管理台根据产品功能一次向物联网中台发起 查询后端API 或者 根据服务查询后端API列表 请求。
- 最后，物联网中台接收到查询后端API请求后，依照**B端成员 **归属企业不同来圈定可查询的后端API范围，进而返回不同的后端API数据。
五、API列表
5.1 后端API管理
5.1.1 后端API注册
接口描述
注册后端API目前支持两种形式，第一为第三方SAAS服务利用应用签名进行后端API注册，第二平台内部服务利用平台权限进行后端API注册；优先识别内部服务注册，即是请求头同时传AccessToken和Signature会被认为是内部服务注册；API必须为同一个服务Service，service + path + method联合唯一。
请求方式
POST
请求地址
/v3/service/gateway-admin/apis/backend-registe
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Signature | false | String | 签名算法初步为SHA256(AppID+AppSecret+参数Body) |
| Access-Token | false | String | 调用凭证 平台权限 |
| Content-Type | true | String | application/json |
| App-ID | false | String | 应用标识 |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| service | body | true | String | API归属服务 |
| apis | body | true | Array | 后端API列表 |
| apis.path | body | true | String | API路径 |
| apis.method | body | true | String | API方法，枚举: GET POST PUT DELETE |
| apis.name | body | true | String | API名称 |
| apis.timeout | body | true | Int | API调用超时时间 单位毫秒，最大值为30000毫秒 |
| apis.allow_auths | body | true | Array | 允许的认证方式，枚举 67108864: APP签名 2: B端成员 4: C端用户 64: NULL认证 16777216: 外部认证 |
| apis.role_auths | body | true | Array | 需要角色进行认证的认证方式，枚举 67108864: APP签名 2: B端成员 4: C端用户 64: NULL认证 16777216: 外部认证 |
| apis.params | body | true | Array | 参数列表 |
| apis.params.name | body | true | String | 参数名称，必须为大小写字母、数字、下划线组成，长度为1~64以内 |
| apis.params.desc | body | false | String | 参数描述，长度为0~64 |
| apis.params.location | body | true | Int | 参数位置，枚举 1:Query 2:Header 3:Body 4:Path |
| apis.params.type | body | true | Int | 参数类型，枚举 1:String 2:Int 3:Long 4:Double 5:Boolean 6:Array，location只能是3:Body 7:Object，location只能是3:Body |
| apis.params.required | body | true | Boolean | 是否必须 |
| apis.response | body | true | Object | 接口响应示例 |
| apis.response.type | body | true | Int | 接口响应格式，枚举 1: JSON |
| apis.response.success_sample | body | false | String | 成功响应示例，JSON字符串 |
| apis.response.fail_sample | body | false | String | 失败响应示例，JSON字符串 |
| apis.response.errors | body | false | Array | 错误列表，最多32个 |
| apis.response.errors.code | body | false | String | 错误码 |
| apis.response.errors.message | body | false | String | 错误信息 |
请求示例：
{
"service": "event-service",
"apis": [{
"path": "/v1/service/events",
"method": "POST",
"name": "事件列表",
"timeout": 20000,
"allow_auths": [2, 4],
"role_auths": [2],
"params": [{
"name": "name",
"desc": "事件名称",
"location": 3,
"type": 1,
"required": true
}],
"response": {
"type": 1,
"success_sample": "{\"name\":\"你好\"}",
"fail_sample": "{\"name\":\"你好\"}",
"errors": [{
"code": "4001001",
"message": "参数不合格"
}]
}
}]
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| status | true | Int | HTTP状态码 |
| code | true | Int | 业务错误码 |
| msg | false | String | 业务错误信息 |
| data | false | Object | 业务数据 |
| data.count | true | Int | 后端API数量 |
| data.list | true | Array | 后端API列表 |
| data.list.id | true | String | 后端API标识 |
| data.list.path | true | String | 后端API路径 |
| data.list.method | true | String | 后端API路径 |
返回示例：
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {
"count": 1,
"list": [{
"id": "1234656",
"path": "/v1/service/events",
"method": "POST"
}]
}
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 40010001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 40322001 | 签名错误 |
| 40022051 | 签名格式不正确 |
| 40022011 | 服务格式长度不正确 |
| 40022052 | 路径格式不正确 |
| 40022020 | HTTP接口方法不正确 |
| 40022057 | 接口重复 |
| 40022053 | API名称不正确 |
| 40022047 | 认证方式未知 |
| 40022048 | 返回类型未知 |
| 40022049 | 错误码达到上限 |
| 40022019 | 参数名称非法 |
| 40022055 | 参数位置未知 |
| 40022056 | 参数类型未知 |
| 40022042 | 参数类型与位置不匹配 |
| 40022054 | 后端参数重复 |
5.1.2 查询后端API
接口描述
企业成员根据后端API标识查询后端API信息。
- 先从缓存中获取，如果有则直接返回
- 缓存中没有则从数据库中获取，删除缓存中数据之后更新到缓存，缓存有效期为3小时+随机60秒
- 如数据库中没有，则虚拟一个无效应用信息放入缓存中，有效期为30分钟+随机60秒。
请求方式
GET
请求地址
/v3/service/gateway-admin/apis/backends/{id}
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业成员 平台权限 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| id | path | true | String | 后端API标识 |
请求示例：
{
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| status | true | Int | HTTP状态码 |
| code | true | Int | 业务错误码 |
| msg | false | String | 业务错误信息 |
| data | false | Object | 业务数据 |
| data.id | true | String | API标识 |
| data.path | true | String | API路径 |
| data.method | true | String | API方法，枚举: GET POST PUT DELETE |
| data.name | true | String | API名称 |
| data.timeout | true | Int | API调用超时时间 单位毫秒，最大值为30000毫秒 |
| data.service | true | String | API归属服务 |
| data.type | true | Int | API拥有者类型，枚举 1: 平台类型服务 2: 企业类型服务 |
| data.owner | true | String | API拥有者标识 type为1时，固定为XLINK type为2时，固定为企业标识 |
| data.allow_auths | true | Array | 允许的认证方式，枚举 67108864: APP签名 2: B端成员 4: C端用户 64: NULL认证 16777216: 外部认证 |
| data.role_auths | true | Array | 需要角色进行认证的认证方式，枚举 67108864: APP签名 2: B端成员 4: C端用户 64: NULL认证 16777216: 外部认证 |
| data.params | true | Array | 参数列表 |
| apis.params.name | true | String | 参数名称，必须为大小写字母、数字、下划线组成，长度为1~64以内 |
| data.params.desc | false | String | 参数描述，长度为0~64 |
| data.params.location | true | Int | 参数位置，枚举 1:Query 2:Header 3:Body 4:Path |
| data.params.type | true | Int | 参数类型，枚举 1:String 2:Int 3:Long 4:Double 5:Boolean 6:Array，location只能是3:Body 7:Object，location只能是3:Body |
| data.params.required | true | Boolean | 是否必须 |
| data.response | true | Object | 接口响应示例 |
| data.response.type | true | Int | 接口响应格式，枚举 1: JSON |
| data.response.success_sample | false | String | 成功响应示例，JSON字符串 |
| data.response.fail_sample | false | String | 失败响应示例，JSON字符串 |
| data.response.errors | false | Array | 错误列表，最多32个 |
| data.response.errors.code | false | String | 错误码 |
| data.response.errors.message | false | String | 错误信息 |
| data.create_time | true | String | 创建时间，格式为2019-12-16T16:00:00.000Z |
| data.update_time | false | String | 更新时间，格式为2019-12-16T16:00:00.000Z |
返回示例：
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {
"id": "1234656",
"path": "/v1/service/events",
"method": "POST",
"name": "事件列表",
"timeout": 20000,
"service": "event-service",
"type": 1,
"owner": "8123123",
"allow_auths": [2],
"role_auths": [2],
"update_time": "2019-12-16T16:00:00.000Z",
"create_time": "2019-12-16T16:00:00.000Z",
"params": [{
"name": "name",
"desc": "参数-名称",
"location": 3,
"type": 1,
"required": true
}],
"response": {
"type": 1,
"success_sample": "{\"name\":\"你好\"}",
"fail_sample": "{\"name\":\"你好\"},
"errors": [{
"code": "4001001",
"message": "参数不合格"
}]
}
}
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 40010001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
| 40022003 | 分组不存在 |
5.1.3 根据服务查询后端API列表
接口描述
企业成员根据服务列表查找后端API列表，企业可用的服务有企业下的服务以及平台服务。
请求方式
POST
请求地址
/v3/service/gateway-admin/services/{id}/apis
请求头
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| Access-Token | true | String | 调用凭证 企业成员 平台权限 |
| Content-Type | true | String | application/json |
请求参数
| 名称 | 位置 | 必填 | 类型 | 备注 |
|---|---|---|---|---|
| offset | body | false | Int | 偏移量 |
| limit | body | false | Int | 查询量 |
| sort | body | false | Object | 排序字段 |
| query | body | false | Object | 查询条件 |
| query.logic | body | true | String | 当出现query时，此字段必填，条件逻辑关系, and 或 or |
| query.where | body | false | Object | 查询条件集合 |
请求示例：
{
"offset": 0,
"limit": 10,
"sort": {
"name": "desc"
},
"query": {
"logic": "and",
"where": {
"name": {
"$eq": "视频安防"
},
"desc": {
"$in": ["452877796"]
}
}
}
}返回参数说明
| 名称 | 必填 | 类型 | 备注 |
|---|---|---|---|
| status | true | Int | HTTP状态码 |
| code | true | Int | 业务错误码 |
| msg | false | String | 业务错误信息 |
| data | false | Object | 业务数据 |
| data.count | false | String | 后端API总数 |
| data.list | false | Array<Object> | 后端API列表 |
| data.list.id | true | String | 后端API标识 |
| data.list.path | true | String | API路径 |
| data.list.method | true | String | API方法，枚举: GET POST PUT DELETE |
| data.list.name | true | String | API名称 |
| data.list.timeout | true | Int | API调用超时时间 单位毫秒，最大值为30000毫秒 |
| data.list.service | true | String | API归属服务 |
| data.list.type | true | Int | API拥有者类型，枚举 1: 平台类型服务 2: 企业类型服务 |
| data.list.owner | true | String | API拥有者标识 type为1时，固定为XLINK type为2时，固定为企业标识 |
| data.list.allow_auths | true | Array |
允许的认证方式，枚举 67108864: APP签名 2: B端成员 4: C端用户 64: NULL认证 16777216: 外部认证 |
| data.list.role_auths | true | Array |
需要角色进行认证的认证方式，枚举 67108864: APP签名 2: B端成员 4: C端用户 64: NULL认证 16777216: 外部认证 |
| data.list.params | true | Array<Object> | 参数列表 |
| apis.list.params.name | true | String | 参数名称，必须为大小写字母、数字、下划线组成，长度为1~64以内 |
| data.list.params.desc | false | String | 参数描述，长度为0~64 |
| data.list.params.location | true | Int | 参数位置，枚举 1:Query 2:Header 3:Body 4:Path |
| data.list.params.type | true | Int | 参数类型，枚举 1:String 2:Int 3:Long 4:Double 5:Boolean 6:Array，location只能是3:Body 7:Object，location只能是3:Body |
| data.list.params.required | true | Boolean | 是否必须 |
| data.list.response | true | Object | 接口响应示例 |
| data.list.response.type | true | Int | 接口响应格式，枚举 1: JSON |
| data.list.response.success_sample | false | String | 成功响应示例，JSON字符串 |
| data.list.response.fail_sample | false | String | 失败响应示例，JSON字符串 |
| data.list.response.errors | false | Array<Object> | 错误列表，最多32个 |
| data.list.response.errors.code | false | String | 错误码 |
| data.list.response.errors.message | false | String | 错误信息 |
| data.list.create_time | true | String | 创建时间，格式为2019-12-16T16:00:00.000Z |
| data.list.update_time | false | String | 更新时间，格式为2019-12-16T16:00:00.000Z |
返回示例：
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {
"count": 1,
"list": [{
"id": "1234656",
"path": "/v1/service/events",
"method": "POST",
"name": "事件列表",
"timeout": 20000,
"service": "event-service",
"type": 1,
"owner": "8123123",
"allow_auths": [2],
"role_auths": [2],
"update_time": "2019-12-16T16:00:00.000Z",
"create_time": "2019-12-16T16:00:00.000Z",
"params": [{
"name": "name",
"desc": "参数-名称",
"location": 3,
"type": 1,
"required": true
}],
"response": {
"type": 1,
"success_sample": "{\"name\":\"你好\"}",
"fail_sample": "{\"name\":\"你好\"},
"errors": [{
"code": "4001001",
"message": "参数不合格"
}]
}
}]
}
}错误码：
| 错误码 | 描述 |
|---|---|
| 4001001 | 请求数据字段验证不通过 |
| 40010001 | 请求数据字段验证不通过 |
| 4001002 | 请求数据必须字段不可为空 |
| 4031001 | 调用凭证权限被禁止访问 |
| 4031003 | 无效的调用凭证 |
| 4031002 | 需要调用凭证 |
| 4041001 | 接口不存在 |
| 5031001 | 系统错误 |
| 4031024 | 权限不足 |
