Skip to content

从 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 介绍了获取访问令牌的两种方法:

  • 获取访问令牌以便从您的应用调用 MindSphere。请参见 身份验证和授权 部分。
  • 在全球技术访问中心 (GTAC) 批准您的请求后获取访问令牌。请参见 自托管应用 部分。

生成用于访问 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 模型的流程不同:

image

新建 IoT 模型

每个步骤都附带一个示例。该示例的内容是为电动自行车创建 asset。有关示例中使用的 API 端点的详细信息,请参见 V3 API 参考

概述

  1. 创建(或更新)aspect 类型
  2. 创建(或更新)asset type
  3. 创建 asset
  4. 查询 asset 结构以进行验证

说明

  • 创建 aspect 类型和 asset type 的步骤 1 和 2 为可选项。如果已经有适用的 types,则可以忽略这两个步骤。
  • 您可以使用端点 GET /aspecttypesGET /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:

另请参见 服务索引 获取相关服务的概述和简要说明。

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开发许可协议.


Last update: July 11, 2019