Usage Transparency Service – 示例¶
添加用量到 UTS¶
运营商和应用可以使用此 API 创建一个作业,该作业将多个租户和用户的应用指定用量(例如,创建的报告页面的数量、配置的资产等)添加到 UTS 。
使用以下端点向 UTS 添加用量:
POST /usagesJobs
请求示例:
{
"users": [
{
"tenantId": "siemenshcops",
"userId": "john.doe@healthcare.siemens.com",
"userType": "user",
"resources": [
{
"application": "manage-my-machines",
"alias": "analyze-my-performance",
"resource": "asset-id-1",
"usages": [
{
"value": 20,
"unit": "mmm-recurring-unit",
"datetime": "2011-07-14T19:43:37Z"
}
]
}
]
}
]
}
响应示例:
{
"id": "35a4cb01-2497-4191-ad1c-551a1942c409-20190520131",
"time": "2011-07-14T19:43:37Z",
"status": "ACCEPTED",
"usagesCount": 7
}
检索查询状态¶
该 API 给出了作业的总体状态概述,以及使用 /UsagesJobs
或 /usage
API添加的用量。 作业状态描述如下:
- ACCEPTED: 作业已创建并且用量已接受。
- INPROGRESS: 至少有一个由作业添加的用量正在处理中。
- ERRORS: 在处理这些用量时,至少遇到了一个错误。
- COMPLETED: 该用量的所有处理流程均已完成。
使用以下端点从 UTS 检索查询状态:
GET /usagesJobs
响应示例:
{
"jobs": [
{
"id": "35a4cb01-2497-4191-ad1c-551a1942c409-20190520131",
"time": "2011-07-14T19:43:37Z",
"status": "ACCEPTED",
"usagesCount": 7
}
],
"page": {
"number": 2,
"size": 10,
"totalElements": 40,
"totalPages": 4
}
}
检索用量的查询状态¶
该 API 给出了使用/UsagesJobs
或 /usage
API 添加的用量的状态摘要。 用量状态描述如下:
- ACCEPTED:用量已被接受。
- VERIFIED:已经根据规则引擎中配置的规则验证了用量(如适用)。
- VERIFICATIONFAILED:至少有一个用量的验证失败。
- NOVERIFICATION:没有发现适用的规则,因此没有进行验证。
- AGGREGATED: 根据规则中定义的聚合函数,将用量聚合为每日运行的聚合值。如果没有适用的规则,则使用默认的聚合函数
SUM
。每小时执行一次聚合,并更新每日聚合。一旦聚合,将通过用户界面或数据端点查询 UTS 以报告用量。 - SENTFORBILLING: 如果启用了账单功能,则数据已成功发送到账单系统。
- FAILEDTOSENDFORBILLING: 发送数据到账单系统时遇到错误。可能是网络问题或其他内部错误。
- RECEIVEDFORBILLING: 发送到账单的数据在账单系统中得到验证。
使用以下端点检索用量的查询状态:
GET /usagesJobs/{id}
响应示例:
{
"id": "35a4cb01-2497-4191-ad1c-551a1942c409-20190520131",
"time": "2011-07-14T19:43:37Z",
"status": "ACCEPTED",
"usagesCount": 7,
"usagesSummary": [
{
"application": "manage-my-machine",
"unit": "mm-onboarding-unit",
"usagesCount": 2,
"processStatus": "ACCEPTED"
}
],
"page": {
"number": 2,
"size": 10,
"totalElements": 40,
"totalPages": 4
}
}
检索处理错误¶
该 API 给出了与被指定的作业接收的一组用量相关的处理错误。 在 Verification Errors
的情况下,错误信息包含未通过验证的用量列表。 在 Billing Errors
的情况下,错误信息包含账单 ID 。 要解决这些问题,请联络支持团队。
使用以下端点检索处理错误:
GET /usagesJobs/{id}/errors
响应示例:
{
"errors": [
{
"code": "mdsp.<provider>.<service/app>.<errorid>",
"message": "<error message in english>",
"messageParameters": [
{
"name": "name1",
"value": "value1"
}
],
"logref": "0bff7e7a-cd25-4576-9908-4180ef086174",
"errorType": "ValidationError",
"info": "http://developer.mindsphere.io/uts/documentation/billing"
}
],
"page": {
"number": 2,
"size": 10,
"totalElements": 40,
"totalPages": 4
}
}
Last update: December 5, 2019