持久访问令牌
此 API 可以获取具有管理员权限的令牌,并定义其有效期。
令牌生成后,即可在其有效期内调用平台后端的各项服务 API。
工作原理
当外部应用程序需要集成平台服务时,访问这些服务需要获取一种称为访问令牌的令牌。
对平台服务的访问和使用可能是永久性的,也可能是临时性的。
平台的授权服务为这些集成场景提供了两个 API,分别用于获取和删除持久令牌,详见下文。
创建访问令牌
请求
POST /services/gear/AuthorizationService.svc/CreateClientAccessTokenAllIntegrations
Host: gear.cloud.studio请求正文
请求正文是一个 JSON 对象,格式如下。
在此示例中,请求创建并持久保存一个访问令牌,但未指定过期日期,此时过期日期默认为 01/01/2099。
}
"clientAccessToken": {
"Description": "Testing 10",
"ClientID": 79
},
"login": {
"LoginType": 1,
"Email": "xxxxx.xxxxxxx@cloud.studio",
"Password": "xxxxxxxxxxx"
}
}如需设置过期日期,请求正文应如下所示,其中新增了 expiration 字段,表示访问令牌的过期时刻。
{
"clientAccessToken": {
"Description": "Testing 10",
"ClientID": 79
},
"login": {
"LoginType": 1,
"Email": "xxxxxx.xxxxxx@cloud.studio",
"Password": "xxxxxxxxx"
},
"expiration": 3600
}请求正文字段
| 名称 | 说明 | 必填 |
|---|---|---|
| Description | 用户自定义的描述,通常说明要创建的访问令牌的用途,最多 255 个字符,支持 Unicode。 | 是 |
| clientID | 要为其创建令牌的客户的标识符。 | 是 |
| LoginType | 此字段必须为值 1。 | 是 |
| 用于请求创建访问令牌的账户的电子邮件地址 (*)。 | 是 | |
| Password | 用于创建访问令牌的账户的密码。 | 是 |
| expiration | 访问令牌自创建之时起的有效时长(秒)。如果省略或为 0,令牌将于 01/01/2099 过期。 | 否 |
(*) 所创建的访问令牌的权限和特权继承自请求中所含凭据对应用户的权限和特权。因此,如果访问令牌需要拥有与平台管理员相同的权限,则用于执行该 API 的用户必须具备相应的特权。
响应
请求处理成功时,响应将返回 HTTP 状态码 200,并包含所创建的访问令牌以及有关其过期时间、**关联客户标识符(参见“删除访问令牌”)**和所提交描述的附加数据。
{
"CreateClientAccessTokenAllIntegrationsResult": {
"AccessToken": "8e15e6d1-821a-4b71-a78d-8338e3307d2b",
"ClientAccessTokenID": 214,
"ClientID": 79,
"DateTimeCreated": {
"Date": {
"Day": 16,
"Month": 12,
"Year": 2022
},
"Time": {
"Hour": 18,
"Millisecond": 660,
"Minute": 38,
"Second": 33
}
},
"Description": "German Prueba 1",
"ExpirationDateTime": {
"Date": {
"Day": 1,
"Month": 1,
"Year": 2099
},
"Time": {
"Hour": 0,
"Millisecond": 0,
"Minute": 0,
"Second": 0
}
}
}
}重要注意事项
根据以下几种可能的使用情况,调用该 API 时可能出现以下异常场景。
描述重复
如果连续两次发送创建访问令牌的请求,且请求所发送 JSON 对象中 Description 字段的内容完全相同,则请求将失败。
凭据多次错误
如果连续三次向访问令牌创建 API 发送的请求中电子邮件 / 密码凭据不正确,请求将失败,响应中将包含错误消息 "Please complete the captcha"。
出现这种情况时,可登录平台前端,使用正确的电子邮件和密码组合执行登录操作来解决。此时系统会要求进行验证码验证。
验证码验证通过并成功进入平台后,即可重新调用该 API。
删除访问令牌
请求
POST /services/gear/AuthorizationService.svc/DeleteClientAccessToken
Host: gear.cloud.studio请求正文
{
"accessToken": "99a4d0a4-932d-468b-9c17-49b5afdffb0d",
"clientAccessTokenID": 14
}请求正文字段
| 名称 | 说明 | 必填 |
|---|---|---|
| accessToken | 要删除的已创建访问令牌。 | 是 |
| clientAccessTokenID | 与要删除的访问令牌关联的客户标识符。 | 是 |
响应
删除请求处理成功时,响应将返回 HTTP 状态码 200 和空正文。HTTP 状态码为 500 的响应应视为请求失败,其正文格式如下。
删除请求成功时的响应正文与请求失败时的响应正文:
{}{
"Exception": {
"ClassName": "ServiceException",
"FaultCode": "8001",
"FaultData": "",
"Message": "The access token is invalid or it doesn't have sufficient permissions to execute the requested operation"
}
}可使用持久访问令牌的平台服务及其对应 API
以下列出可使用此 API 所创建访问令牌的部分服务作为示例:
1-/services/gear/DashboardService.svc/GetDashboard
2-/services/core/AlarmService.svc/GetAlert
3-/services/gear/DeviceService.svc/CreateDeviceModel
4-/services/gear/DeviceService.svc/EditDeviceModel
5-/services/gear/DeviceService.svc/DeleteDeviceMod
最后更新于