上传代理数据

如果代理要将数据上传到 MindSphere，MindSphere 需要进行额外配置才能知道如何解读代理的数据流。此配置需要在 MindSphere 中对以下各项进行定义：

配置数据源服务
开通属性集服务
数据源和属性集的映射

准备数据上传

创建数据源配置

Mindsphere需要数据源配置来解译从代理接收到的数据。没有这种配置，MindShpere将不能理解数据。数据源配置包含数据源和数据点。数据源是逻辑组，例如一个传感器或者机器，这个逻辑组包含一个或更多的测量的数据点，例如温度或压力。

请像下面展示一样使用Agent Management Service创建数据源配置的：

PUT /api/agentmanagement/v3/agents//dataSourceConfiguration HTTP/1.1
Content-Type:application/json
If-Match:etag
Authorization:Bearer eyx...
{
 "configurationId": "string",
 "dataSources": [
 {
 "name": "string",
 "description": "string",
 "dataPoints": [
 {
 "id": "string"，
 "name": "string",
 "description": "string",
 "type": "int",
 "unit": "string",
 "customData": {}
 }
 ],
 "customData": {}
 }
 ]
}

参数	描述	备注
dataSource.name	数据源名称	强制项。允许任何 string。
dataSource.description	数据源的描述	可选项。允许任何 string。
dataPoint.id	数据点 ID	强制项。每个代理必须唯一。不允许重复
dataPoint.name	数据点名称	强制项。允许任何 string，例如压力、电压、电流等。
dataPoint.description	数据点的描述	可选项。允许任何 string。
dataPoint.type	数据点的数据类型。默认情况下，MindSphere 提供以下基本类型：Double、Long、Int、String、Boolean	强制项
dataPoint.unit	数据点的单位	强制项。允许任何 string，例如百分数、SI 等。允许空 string。
dataPoint.customData	提供自定义数据（如果有）	可选
dataSources.customData	提供自定义数据（如果有）	可选

如果成功，MindSphere 将返回 HTTP 响应 200 OK，其中带有包含创建的数据源配置的 JSON 文本：

{
 "id": "string"，
 "eTag":"2",
 "configurationId": "string",
 "dataSources": [
 {
 "name": "string",
 "description": "string",
 "dataPoints": [
 {
 "id": "string"，
 "name": "string",
 "description": "string",
 "type": "int",
 "unit": "string",
 "customData": {}
 }
 ],
 "customData": {}
 }
 ]
}

警告

更新现有数据源配置时，将删除代理的所有数据点映射。

说明

要使用 Exchange Services，需要将参数configurationId提供给 MindSphere。

创建数据点映射

您在创建数据点映射时，在 MindSphere 中不仅需要数据源配置也需要相对应的属性集。

MindSphere 需要数据点映射来存储从代理接收到的数据。这将数据源配置中的数据点映射到表示代理的数字实体的属性。当 MindSphere 从代理接收数据时，它会查找数据点映射到哪个属性并将数据存储在那里。

请像下面展示一样使用 MindConnect API 创建数据点映射：

POST /api/mindconnect/v3/dataPointMappings HTTP/1.1
Content-Type:Application/Json
Authorization:Bearer eyc..
{
 "agentId":"11961bc396cd4a87a9b26b723f5b7ba0",
 "dataPointId":"DP0001",
 "entityId":"83e78008eadf453bae4f5c7bef3db550",
 "propertySetName":"ElectricalProperties",
 "propertyName":"Voltage"
}

参数	描述	故障排除
agentId	String、已验证、已检查空值。必须存在于 Agent Management 中。	HTTP 400:Agent is empty! HTTP 404:AgentId, {...} in the data point mapping does not exist!
dataPointId	String、已验证、已检查空值。必须存在于 Agent Management 中，并且属于规定的代理的数据源配置。	HTTP 400:DataPointId is empty! HTTP 404:DataPointId, {...} in the data point mapping does not exist in the related agent!
entityId	String、已验证、已检查空值。必须存在于 IoT 实体服务中。	HTTP 400:Entity ID is empty! HTTP 404:Not Found
propertySetName	String、已验证、已检查空值。必须存在于 IoT 类型服务中，并且属于规定的实体的实体类型。	HTTP 400:PropertySetName is empty! HTTP 404:Property set not found with name {...} HTTP 404:Entity type does not own a property Set with name {...}
propertyName	String、已验证。必须存在于 IoT 类型服务中，并且属于规定的属性集。	HTTP 400:PropertyName is empty! HTTP 404:Property set does not own a property with name {...}

必须考虑以下几个方面：

数据点和属性的单位和类型应匹配。
如果属性没有单位（NULL)，则数据点单位应为空字符串。
被选择的属性不得为静态。
一个数据点无法映射到有同一属性名称的多个属性。

在创建数据点映射之前，MindSphere 执行以下检查：

创建数据点映射工作流程和检查

如果成功，MindSphere 将返回 HTTP 响应 201 Created，其中带有包含已创建的映射配置的 JSON 文本。其只将单个数据点映射到单个属性。如果需要更多映射，则必须重复此步骤。

{
 "id":"4fad6258-5def-4d84-a4c2-1481b209c116",
 "agentId":"11961bc396cd4a87a9b26b723f5b7ba0",
 "dataPointId":"DP0001",
 "dataPointUnit": "%",
 "dataPointType":"INT",
 "entityId":"83e78008eadf453bae4f5c7bef3db550",
 "propertySetName":"ElectricalProperties",
 "propertyName":"Voltage",
 "propertyUnit": "%",
 "propertyType":"INT",
 "qualityEnabled":true
}

警告

更新现有数据源配置时，将删除代理的所有数据点映射。

上传数据

MindConnect API 的 MindSphere exchange 端点可使代理将它的数据上传到 MindSphere。此数据可以是以下类型：

时间序列
文件
事件

代理需要一个拥有 mdsp:core:DefaultAgent 权限范围的访问令牌来上传数据。

格式符合 HTTP 分片规范的子集，但只允许嵌套 2 个级别。

必须新建行

<CR><LF>在请求结尾处表示 **必须**新建行（回车和换行）。此表示在以下示例中起到强调作用。
将数据上传到 MindSphere 时，需要用 \r\n 替换这些字符。

上传时间序列数据

下面是一个带有分片消息的示例请求，用于上载时间序列数据：

POST /api/mindconnect/v3/exchange
Content-Type: multipart/mixed; boundary=f0Ve5iPP2ySppIcDSR6Bak
Authorization: Bearer access_token ...

--f0Ve5iPP2ySppIcDSR6Bak
Content-Type:multipart/related;boundary=penFL6sBQHJJUN3HA4ftqC

--penFL6sBQHJJUN3HA4ftqC
Content-Type:application/vnd.siemens.mindsphere.meta+json

{
 "type": "item",
 "version":"1.0",
 "payload": {
 "type": "standardTimeSeries",
 "version":"1.0",
 "details": {
 "configurationId": ""
 }
 }
}
--penFL6sBQHJJUN3HA4ftqC
Content-Type:application/json

[
 {
 "timestamp":"2017-02-01T08:30:03.780Z",
 "values": [
 {
 "dataPointId": "",
 "value":"9856",
 "qualityCode":"0"
 },
 {
 "dataPointId": "",
 "value":"3766",
 "qualityCode":"0"
 }
 ]
 }
]
--penFL6sBQHJJUN3HA4ftqC--
--f0Ve5iPP2ySppIcDSR6Bak--
<CR><LF>

分片消息以 --f0Ve5iPP2ySppIcDSR6Bak 作为标识符开始。它以 --f0Ve5iPP2ySppIcDSR6Bak-- 作为标识符结束，该标识符等于由双破折号附加的起始标识符。接受分片请求的结构后，MindSphere 将返回 HTTP 响应 200 OK并带有一个空体。MindSphere 异步验证和存储数据。只要访问令牌有效，代理就可以继续上传数据。

分片消息出现在这个初始边界内。每个分片消息由元数据和有效载荷组成，因此每个消息包含两个边界开始标识符，并且末尾还有一个边界结束标识符：

--initial boundary

--boundary1
Metadata

--boundary1
Payload

--boundary1--

--initial boundary--
<CR><LF>

说明

分片消息的元数据部分中的属性 configurationId 告诉 MindSphere 如何解译它接收到的数据(参见[Creating a Data Source Configuration]一节)。

上传文件

代理可以上传文件到 MindSphere，并将其存储在各自的 asset 中。在 MindSphere 中，元数据和有效载荷对被称为元组。每个元组可以包含不同类型的数据（例如，一个元组可以包含特定的时间戳数据，而另一个元组可以包含八位字节/流数据）。以下示例包含八位字节/流 mime 类型的交换有效载荷：

--5c6d7e29ef6868d0eb73
Content-Type:application/vnd.siemens.mindsphere.meta+json

{
 "type": "item",
 "version":"1.0",
 "payload": {
 "type": "file",
 "version":"1.0",
 "details":{
 "fileName":"data_collector.log.old",
 "creationDate":"2017-02-10T13:00:00.000Z",
 "fileType":"log"
 }
 }
}

--5c6d7e29ef6868d0eb73
Content-Type:application/octet-stream

 ...File content here ...

--5c6d7e29ef6868d0eb73--
--f0Ve5iPP2ySppIcDSR6Bak--
<CR><LF>

上传事件

代理可以上传事件到 MindSphere，并将其存储在各自的 asset 中。事件必须为源自 type AgentBaseEvent 的事件类型。以下是适用于上传事件的规则：

有效负载需要字段 eventId 和 version。对于 version 来讲，允许的值有 MAJOR、 MINOR。
事件类型必须存在于Event Management。否则，事件将被终止。
严重度是可选的，但有无效严重度值的事件将被终止。允许的整数值取决于事件的 version。
version 1.0: 1 (URGENT), 2 (IMPORTANT), 3 (INFORMATION)
version 2.0: 20 (ERROR), 30 (WARNING), 40 (INFORMATION)

AgentBaseEvent 模型

{ "id": "core.connectivity.event.type.AgentBaseEvent",
  "name": "AgentBaseEvent",
  "ttl": 35,
  "parentId": "com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent",
  "fields": [
    {
      "name": "eventId",
      "filterable": true,
      "required": true,
      "updatable": true,
      "type": "STRING"
    },
    {
      "name": "version",
      "filterable": true,
      "required": true,
      "updatable": true,
      "type": "STRING"
    }
  ]
}

这是一个源于 AgentBaseEvent 的自定义事件类型示例：

                                  { "name": "FileUploadCompletedEvent", "parentId": "core.connectivity.event.type.AgentBaseEvent", "ttl": 35, "scope": "LOCAL", "fields": [ { "name": "fileNumber", "filterable": true, "required": false, "updatable": true, "type": "INTEGER" }, { "name": "fileSize", "filterable": true, "required": false, "updatable": true, "type": "DOUBLE" }, { "name": "fileName", "filterable": true, "required": true, "updatable": true, "type": "STRING" }, { "name": "isValid", "filterable": true, "required": false, "updatable": true, "type": "BOOLEAN" } ] ">}
 --FRaqbC9wSA2XvpFVjCRGry
Content-Type:multipart/related;boundary=5c6d7e29ef6868d0eb73

--5c6d7e29ef6868d0eb73
Content-Type:application/vnd.siemens.mindsphere.meta+json

{
 "type": "item",
 "version":"1.0",
 "payload": {
 "type": "businessEvent",
 "version":"1.0"
 }
}
--5c6d7e29ef6868d0eb73
Content-Type:application/json

[
    {
        "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "correlationId": "fd7fb194-cd73-4a54-9e53-97aca7bc8568",
        "timestamp": "2018-07-11T11:06:25.317Z",
        "severity": 2,
        "type": "FileUploadCompletedEvent",
        "description": "file uploaded event",
        "version": "1.0",
        "details":{
            "fileName": "test1",
            "fileSize": 11.2,
            "isValid": "true",
            "fileNumber": 15
        }
    }
]
--5c6d7e29ef6868d0eb73--
--FRaqbC9wSA2XvpFVjCRGry--
<CR><LF>
 重放交换请求
 如果 MindSphere 在通过 MindConnect API 上传后无法处理数据。MindConnect 的恢复服务会将未处理的数据存储 15 个日历日。 对于存储的未处理数据的列表，请使用 recoverableRecords 端点。如下所示，它响应的是一个可恢复记录的页面。该相应可以使用 JSON 过滤器 通过 agentId，correlationId，requestTime 和 dropReason 字段进行过滤。
 {
      "id": "4fad6258-5def-4d84-a4c2-1481b209c116",
      "correlationId": "7had568-5def-4d84-a4c2-1481b209c116",
      "agentId": "33238f98784711e8adc0fa7ae01bbebc",
      "requestTime": "2018-08-27T16:40:11.235Z",
      "dropReason": " <[Dropped] TimeSeries Data is dropped. Validation failed for reason <Pre-processing of <153000> data points ended with <60600> valid and <92400> dropped data points. Following issues found: Data point with no mapping count is <92400>, including <[variable101, variable102, variable103, variable104, variable105, variable106, variable107, variable108, variable109, variable110]>.>>"
}
 要检查记录的有效载荷，MindConnect API 提供了 /recoverableRecords/{id}/downloadLink 端点。响应包含一个 URL，数据由 MindConnect API 上传到该 URL，例如：
 GET /api/mindconnect/v3/recoverableRecords/{id}/downloadLink` HTTP/1.1
"https://bucketname-s3.eu-central-1.amazonaws.com/c9bcd-44ab-4cfa-a87e-d81e727d9af4?X"
 如果无效的映射或注册导致无法处理数据，则可以在更正定义后重放交换请求。使用 MindConnect API 的 /recoverableRecords/{id}/replay 端点触发重放。
  说明
 如果在重放后可以成功处理数据，则会在 2 天后将其从恢复系统中删除。
 
 诊断数据上传
 通过 MindConnect API 上传的数据可以使用诊断服务功能进行诊断。 为了激活代理以进行诊断服务，MindSphere 提供了 MindConnect API 的 diagnosticActivations 端点，需要与以下参数一同使用：
 POST /api/mindconnect/v3/diagnosticActivations HTTP/1.1
Content-Type:Application/Json
Authorization:Bearer eyc..
{
 "agentId":"11961bc396cd4a87a9b26b723f5b7ba0",
 "status":"ACTIVE"
}
    参数  描述  故障排除  
 
   agentId  String，已验证  HTTP 400:Agent is empty!

HTTP 404:Agent id {...} exists!

Agent id {...} could not be enabled.Because agent limitation is {...} for tenant {...}!  
  status  String，已验证
允许以下输入：ACTIVE、INACTIVE、NULL。如果为 NULL，则默认情况下将值设置为 ACTIVE。  HTTP 400: Custom statuses are not allowed. Use one of the allowed input values  
 
 
  说明
 每个租户最多可以激活 5 个代理的诊断服务。1 小时后，诊断激活状态设置为不活跃状态。可以通过 diagnosticActivations/id 端点删除激活。
 
 recoverableRecords 端点提供了诊断激活列表。如下所示，它响应的是一个诊断激活页面。该响应可以使用 JSON 过滤器 通过 agentId 和 status 字段进行过滤。
 {
 "content": [
 {
 "id":"0b2d1cdecc7611e7abc4cec278b6b50a",
 "agentId":"3b27818ea09a46b48c7eb3fbd878349f",
 "status":"ACTIVE"
 }
 ],
 "last":true,
 "totalPages":1,
 "totalElements":1,
 "numberOfElements":1,
 "first":true,
 "sort": {},
 "size":20,
 "number":0
}
 可使用 diagnosticActivations/id 端点上传或删除激活：
 PUT /api/mindconnect/v3/diagnosticActivations HTTP/1.1
{
 "status":"INACTIVE"
}
    参数  描述  故障排除  
 
   status  String，已验证
允许以下输入：ACTIVE、INACTIVE  HTTP 400:Custom statuses are not allowed.状态值必须是以下之一：[ACTIVE、INACTIVE]  
 
 
 diagnosticInformation 端点列出了诊断数据。如下所示，其响应是一个页面，可以使用 JSON 过滤器 通过 agentId、correlationId、message、source、timestamp 和 severity 字段进行过滤。
 
{
 "content": [
 {
 "agentId":"3b27818ea09a46b48c7eb3fbd878349f",
 "correlationId":"3fcf2a5ecc7611e7abc4cec278b6b50a",
 "severity":"INFO",
 "message": "[Accepted] Exchange request arrived",
 "source":"TIMESERIES",
 "state":"ACCEPTED",
 "timestamp":"2018-08-27T16:40:11.235Z"
 },
 {
 "agentId":"78e73978d6284c75ac2b8b5c33ffff57",
 "correlationId":"39301469413183203248389064099640",
 "severity":"ERROR",
 "message": "[Dropped] Registration is missing.Data type is:notstandardTimeSeries"
 "source":"TIMESERIES",
 "state":"DROPPED",
 "timestamp":"2018-08-27T16:40:11.235Z"
 },
 ],
 "last":true,
 "totalPages":1,
 "totalElements":2,
 "numberOfElements":2,
 "first":true,
 "sort": {},
 "size":20,
 "number":0
}
 给定激活的诊断数据由 /diagnosticActivations/{id}/messages 端点提供。它的响应是一个页面，如下所示，可以使用JSON 过滤器通过correlationId、message、source、timestamp 和 severity 字段对其进行过滤。
 {
  "content": [
    {
      "correlationId": "3fcf2a5ecc7611e7abc4cec278b6b50a",
      "severity": "INFO",
      "message": "[Accepted] Exchange request arrived",
      "source": "TIMESERIES",
      "state": "ACCEPTED",
      "timestamp": "2018-08-27T16:40:11.235Z"
    },
    {
      "correlationId": "39301469413183203248389064099640",
      "severity": "ERROR",
      "message": "[Dropped] Registration is missing. Data type is: notstandardTimeSeries"
      "source": "TIMESERIES",
      "state": "DROPPED",
      "timestamp": "2018-08-27T16:40:11.235Z"
    },
  ],
  "last": true,
  "totalPages": 1,
  "totalElements": 2,
  "numberOfElements": 2,
  "first": true,
  "sort": {},
  "size": 20,
  "number": 0
}
 相关链接
  Agent Management Service
 MindConnect API
 上线代理
 获取代理访问令牌
 
 还有问题?
    向社区提问  
 
   除非另行声明，该网站内容遵循MindSphere开发许可协议.  
 
   Last update: July 11, 2019

参数	描述	故障排除
`agentId`	String，已验证	HTTP 400:Agent is empty! HTTP 404:Agent id {...} exists! Agent id {...} could not be enabled.Because agent limitation is {...} for tenant {...}!
`status`	String，已验证允许以下输入：`ACTIVE`、`INACTIVE`、`NULL`。如果为 `NULL`，则默认情况下将值设置为 `ACTIVE`。	HTTP 400: Custom statuses are not allowed. Use one of the allowed input values