Skip to content

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