从 MindSphere V2 迁移到 V3
简介
本文档的目标用户是 MindSphere V2 的开发人员。本文档旨在帮助 MindSphere V2 开发人员快速了解 MindSphere V3。本指南的适用范围是使用 Northbound API 的 MindSphere V2 Cloud Foundry 应用。目前不适用于使用 Southbound API 的应用。
MindSphere V3 中的大多数操作步骤与 V2 平台上的操作步骤相同。MindSphere V2 开发人员主要需要关注以下几个方面:
主要变化
次要变化
先决条件
生成访问令牌以调用 API
所有 MindSphere 端点都受到安全保护,只有身份验证成功后才能与之连接。MindSphere 介绍了获取访问令牌的两种方法:
生成用于访问 API 的 URL
有关如何为 MindSphere Gateway 构建适当的 URL,请参见 URL 方案 部分。
IoT 模型
概念
V2 和 V3 之间的 IoT 模型完全不同。总的来说,aspect 类型和 asset type 在 V3 中是以模板的形式提供的。这样用户便可轻松地管理 assets。aspect 类型附加到 asset type,而 asset 是基于 asset type 创建的。
- 在 V3 中,aspect 类型是 variables 的集合,就像 V2 中的 aspect。但 aspect 类型是一个模板,可以重复使用。aspect 类型没有层次结构,可以分为静态 aspect 或动态 aspect。
- 静态 aspect 的 variables 的值基本都很稳定,没有太大变化。这些 variables 可在搜索 asset 时使用。
- 动态 aspect 使用时间戳进行管理,其 variables 的值会随时间变化。也就是说,这些 variables 用于时间序列数据。
- asset type 包括 aspect 类型和 variables。当 aspect 类型附加到 asset types 时,aspects 类型将完全反映在 asset type 中,包含所有参数(包括 variables)。
- asset type 具有层次结构。新创建的 type 继承父 type 中定义的所有 variables 和 aspects。
- Assets 与 V2 中的相同,但只能基于 asset type 创建。
V3 相对于 V2 的更改
- IoT 模型更改:
V2 | V3 | 更改 |
---|---|---|
Asset | Asset | 几乎相同,但在 V3 中是基于 asset type 的。 |
Asset Type | 在 V3 中是模板。 | |
Aspect | Aspect 类型 | 在 V3 中是模板。 |
- 创建 IoT 模型的流程不同:
新建 IoT 模型
每个步骤都附带一个示例。该示例的内容是为电动自行车创建 asset。有关示例中使用的 API 端点的详细信息,请参见 V3 API 参考。
概述
说明
- 创建 aspect 类型和 asset type 的步骤 1 和 2 为可选项。如果已经有适用的 types,则可以忽略这两个步骤。
- 您可以使用端点
GET /aspecttypes
和GET /assettypes
查询所有现有 types。
1.创建(或更新)aspect 类型(可选)
此步骤创建一个 aspect 类型 running
。此 aspect 类型关注运行状态下的功耗。该类型有两个 variables,可以在其它电子运行设备上重复使用。
put https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/casmcne.running
{
"name": "running",
"category": "dynamic",
"scope": "private",
"description": "running state",
"variables": [
{
"name": "voltage",
"dataType":"DOUBLE",
"unit":"V",
"searchable":true,
"length":null,
"qualityCode":true
},{
"name": "current",
"dataType":"DOUBLE",
"unit":"A",
"searchable":true,
"length":null,
"qualityCode":true
}
]
}
- 创建成功后,MindSphere 返回一个 HTTP 响应
201 已创建 aspect 类型
,JSON 正文还包含有关新建 aspect 类型的其它数据。 - 在同一端点上使用
GET
来检查新建的 aspect:
{
"parentTypeId": "core.basicasset",
"instantiable":true,
"tenantId": "casmcne",
"name":"Electric-Bicycle",
"description": "the device of the Electric-Bicycle",
"scope": "private",
"variables": [
{
"name": "speed",
"unit": "km/h",
"searchable":true,
"dataType":"DOUBLE",
"length":null
}
],
"aspects": [
{
"name": "running",
"aspectType": {
"id": "casmcne.running",
"tenantId": "casmcne",
"name": "running",
"category": "dynamic",
"scope": "private",
"description": "running state",
"variables": [
{
"name": "current",
"unit":"I",
"searchable":false,
"qualityCode":false,
"dataType":"DOUBLE",
"length":null
},
{
"name": "voltage",
"unit":"V",
"searchable":false,
"qualityCode":false,
"dataType":"DOUBLE",
"length":null
}
],
"etag":0,
"_links": {
"self": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/casmcne.running"
}
}
}
}
],
"etag":0,
"_links": {
"self": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/casmcne.elecbike"
},
"parent": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/core.basicasset"
}
},
"id": "casmcne.elecbike"
}
小窍门
- 建议检查所有现有的 aspect 类型以供参考。
id
的格式为[tenant prefix id].[aspect type]
。- 更新模型时,应在消息头中设置
if-match
。 - 不再提供对现有 variables 和 aspect 名称进行更改的功能。
2.创建(或更新)asset type(可选)
此步骤为电动自行车创建 asset type。它包括 variable 和 aspect。variable 是自行车的速度。aspect 的作用是获取自行车运行时的功耗。
put https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/casmcne.elecbike
asset type:
https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/casmcne.elecbike
json:
{
"name":"Electric-Bicycle",
"description": "the device of the Electric-Bicycle",
"parentTypeId": "core.basicasset",
"scope": "private",
"variables": [
{
"name": "speed",
"dataType":"DOUBLE",
"unit": "km/h",
"searchable":true,
"length":null
}
],
"aspects": [
{
"name": "running",
"aspectTypeId": "casmcne.running"
}
]
}
- 创建成功后,MindSphere 返回一个 HTTP 响应
201 已创建 asset type
,JSON 正文还包含有关新建 asset type 的其它数据。
小窍门
id
的格式为[tenant prefix id].[asset type]
。aspectTypeId
在步骤 1 中创建。- 请注意,asset types 是在层次模型中创建的。
- 如果
parenttypeid
指向 asset type,这意味着您将该 asset type 创建为子 asset type。子 asset types 继承其父级类型,可以扩展其父级类型的 aspect 和 variables。
3.创建 asset
此步骤创建电动自行车 asset elecbike_No.1
:
post https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets
{
"typeId": "casmcne.elecbike",
"t2Tenant":null,
"parentId":"1ad478aa9e7f4d1196cbe3d0dd44f002",
"name": "elecbike_No.1",
"externalId": "",
"description": "elecbike No.1",
"location": {
"country":"China",
"region":"Sichuan Province",
"locality":"Chengdu",
"streetAddress":"XiXin Avenue No.07",
"postalcode":"610000",
"longitude":103.9602020,
"latitude":30.7429640
},
"variables": [],
"aspects": []
}
- 创建成功后,MindSphere 返回一个 HTTP 响应
201 已创建 asset
,JSON 正文还包含有关新建 asset 的其它数据。
{
"assetId":"696126dda1714921b3715cce46300fbe",
"tenantId": "casmcne",
"name": "elecbike_No.1",
"etag":0,
"externalId": "",
"t2Tenant":null,
"description": "elecbike No.1",
"parentId":"1ad478aa9e7f4d1196cbe3d0dd44f002",
"typeId": "casmcne.elecbike",
"location": {
"country":"China",
"region":"Sichuan Province",
"locality":"Chengdu",
"streetAddress":"XiXin Avenue No.07",
"postalCode":null,
"longitude":103.960202,
"latitude":30.742964
},
"variables": [],
"aspects": [],
"deleted":null,
"_links": {
"self": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe"
},
"aspects": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/aspects"
},
"variables": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/variables"
},
"location": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/location"
},
"parent": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/1ad478aa9e7f4d1196cbe3d0dd44f002"
}
}
}
小窍门
- 请注意,assets 是在层次模型中创建的。
parentid
是 asset 的类别。
4.查询 asset 结构以进行验证
使用步骤 3 的响应中的链接获取 asset 的 aspect 或 variables 的结构,例如:
Get https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/variables
Get https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/aspects
MindSphere APIs
请在 API 和服务 部分获取当前 MindSphere V3 API 的参考文档。
以下概要介绍了 MindSphere V2 API 和 V3 API 之间的差异。
V3 中的访问令牌范围
与 V2 相比,V3 中的授权控制更加细化。有关使用 MindSphere 服务 API 的概念以及特定角色和权限的详细信息,请参见 角色和范围。
V3 中新增的 API
以下是 V3 中新增的 API:
- Agent Management Service
- Anomaly Detection Service
- Event Analytics Service
- Identity Management Service
- IoT File Service
- IoT Time Series Service
- IoT TS Aggregates Service
- KPI Calculation Service
- MindConnect API
- OAuth Authorization Server API
- Signal Calculation Service
- Signal Validation Service
- Trend Prediction Service
- Usage Transparency Service
另请参见 服务索引 获取相关服务的概述和简要说明。
V2 和 V3 中的 API 比较
下表列出了 V2 和 V3 中 API 名称的更改情况:
V2 API 名称 | V3 API 名称 |
---|---|
Asset Management API | Asset Management API |
Data Flow Engine | Data Flow Engine |
Event Management API | Event Management API |
CommunicationService MessageQueueProducer | Notification API |
Recipients | Notification API |
Template | Notification API |
CommunicationChannel | Notification API |
CommunicationCategory | Notification API |
应用注册
在 V3 中注册应用之前还需要执行一个步骤:
- 配置应用的角色和范围。
有关详细信息,请参见 运行Cloud Foundry 托管的应用。
还有问题?
除非另行声明,该网站内容遵循MindSphere开发许可协议.