Skip to content

jerik.olfermann.ext@siemens.com sebastian.haenisch@siemens.com pruthula.s@siemens.com title: MindSphere SDK - 入门指南 - 开发文档


MindSphere SDK for Java - 入门指南

先决条件

  • Java 8
  • 构建工具 Gradle 或 Maven
  • 具有所需 API 范围的用户授权令牌或服务凭证
  • 环境变量 HOST_ENVIRONMENT 设置为当前区域。在 Cloud Foundry 中托管应用时,必须在 manifest 文件中添加 variable:
env:
HOST_ENVIRONMENT: {region}

如果未指定,HOST_ENVIRONMENT 将默认为 eu1

  • 如果您正在使用服务凭证,可为其设置环境变量,以使客户端能够自行获取令牌。

  • MINDSPHERE_CLIENT_ID
    指定服务凭证 ID

  • MINDSPHERE_CLIENT_SECRET
    指定服务凭证

  • MINDSPHERE_TENANT
    指定租户名称

说明

为服务凭证设置环境变量不是强制性操作。服务凭证或用户令牌可以在 MindsphereCredentials 对象中作为参数进行设置,如以下 API 客户端和凭证配置中所述。

注意

开发者/客户负责保证凭证的安全。开发者/客户决定通过环境变量提供凭证是否足够安全。

请求服务凭证

有关请求服务凭证的信息,请参见创建服务凭证

安装说明

下载 MindSphere SDK

西门子工业在线支持 (SIOS) 门户下载 MindSphere SDK for Java。所下载压缩包的 jarpom 文件结构如下:

mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

说明

从版本 1.2.0 开始,MindSphere SDK for Java 工件的组 ID 从 mindsphere 更改为 com.siemens.mindsphere。更新压缩包结构,如下所示:

com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

说明

x.y.z 是 MindSphere SDK for Java 的版本号(例如 1.0.0)。

下载 MindSphere SDK for Java 的传递相关项时需要文件 mindsphere-sdk-x.y.z.pom

使用构建工具 Maven 为项目添加 SDK 相关项

  • 在本地 Maven 仓库中创建 SDK 文件夹结构:
$PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
$PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
$PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

   <!-- Version 1.2.0 onwards -->
$PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
$PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
$PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

其中 $PATH 为:

  • 在 Mac 中:~/.m2/repository
  • 在 Windows 中:C:\Users\{username}\.m2\repository
  • 在 Linux 中:/home/{User_Name}/.m2/repository

  • pom.xml 中添加相关项:

   <dependency>
       <groupId>mindsphere</groupId>
       <artifactId>mindsphere-sdk</artifactId>
       <version>x.y.z</version>
   </dependency>

   <!-- Version 1.2.0 onwards -->
   <dependency>
       <groupId>com.siemens.mindsphere</groupId>
       <artifactId>mindsphere-sdk</artifactId>
       <version>x.y.z</version>
   </dependency>

使用构建工具 Gradle 为项目添加 SDK 相关项

  • 在本地 Maven 仓库中创建 SDK 文件夹结构,或者在系统的任何位置创建类似的文件夹结构:
$PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
$PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
$PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

   <!-- Version 1.2.0 onwards -->
$PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
$PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
$PATH\com\siemens\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

其中 $PATH 为:

  • 在 Mac 中:~/.m2/repository
  • 在 Windows 中:C:\Users\{username}\.m2\repository
  • 在 Linux 中:/home/{User_Name}/.m2/repository

  • 建议 gradle 在项目的 build.gradle 中查看本地 Maven 仓库,如下所示:

repositories {
mavenLocal()
mavenCentral()

// Use this if SDK jars are not placed in local maven repository.
maven {
url file('{Absolute path of the created repository folder}')
}
}
  • build.gradle 中添加相关项:
compile 'mindsphere:mindsphere-sdk:x.y.z'

       <!-- Version 1.2.0 onwards -->
compile 'com.siemens.mindsphere:mindsphere-sdk:x.y.z'

构建完成后,MindSphere SDK for Java 的所有传递相关项都将下载到您的应用中。

API 客户端和凭证配置

API 的最低级别构建块为 RestClientConfigMindsphereCredentials。这些对象将在客户端实例之间创建和共享。构建器模式用于实例化这些对象。

客户端配置

可以使用配置参数构建 RestClientConfig 对象。目前所有参数均为可选参数。

RestClientConfig config = RestClientConfig.builder()
 .connectionTimeoutInSeconds(100)
 .proxyHost("host")
 .proxyPort(8080)
 .build();

可以为 RestClientConfig 对象配置以下参数:

名称 描述 类型 默认值
connectionTimeoutInSeconds 连接超时(秒) Integer 100
socketTimeoutInSeconds 套接字超时(秒) Integer 100
proxyHost 代理服务器的 host 地址 String
proxyPort 代理服务器端口 Integer
proxyUsername 登录代理服务器使用的用户名 String
proxyPassword 登录代理服务器使用的密码 String
hostEnvironment 当前区域 String eu1
proxySchema 代理服务器使用的架构 String http

凭证配置

MindsphereCredentials 对象可以直接使用用户令牌或技术令牌凭证进行构建。如果凭证是通过环境变量进行的设置,则不需要构建 MindsphereCredentials 对象。

用户授权令牌的代码示例:

MindsphereCredentials credentials = MindsphereCredentials.builder()
 .authorization("usertokenFromRequestHeader")
 .build();

服务凭证的代码示例:

MindsphereCredentials credentials = MindsphereCredentials.builder()
 .clientId("ClientId")
 .clientSecret("ClientSecret")
 .tenant("TenantName")
 .build();

可以为 MindsphereCredentials 对象配置以下参数:

名称 描述 类型 强制项
authorization Bearer 类型的令牌(如果开发者的应用已生成此令牌)。 String 用户令牌的必需参数
clientId 服务凭证 Id String 使用服务凭证的用户的必需参数
clientSecret 服务凭证 String 使用服务凭证的用户的必需参数
tenant 开发者租户的名称 String 使用服务凭证的用户的必需参数

API 客户端实例化和使用

API 客户端实例需要使用构建器模式以参数形式传递 RestClientConfigMindsphereCredentials 实例。

使用 IoT Time Series API 客户端的代码示例:

@RequestMapping(method = RequestMethod.GET, value = "/{entity}/{propertySetName}")
public TimeseriesData getTimeSeriesAsObject(@PathVariable("entity") String entity,
 @PathVariable("propertySetName") String propertySetName,
 @RequestHeader("Authorization") String token) throws MindsphereException
{

 MindsphereCredentials credentials = MindsphereCredentials.builder()
 .authorization(token)
 .build();

 RestClientConfig config = RestClientConfig.builder()
 .connectionTimeoutInSeconds(100)
 .proxyHost("host")
 .proxyPort(portnumber)
 .hostEnvironment("host-environment")
 .build();

 TimeseriesClient timeseriesClient = TimeseriesClient.builder()
 .mindsphereCredentials(credentials)
 .restClientConfig(config)
 .build();

 TimeseriesData timeseriesData = null;
 try {
 timeseriesData = timeseriesClient.getLatestTimeseries(entity, propertySetName);
 } catch (MindsphereException e) {
 // Exception handling
 }

 return timeseriesData;
}

Last update: March 22, 2023