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。所下载压缩包的 jar
和 pom
文件结构如下:
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 的最低级别构建块为 RestClientConfig
和 MindsphereCredentials
。这些对象将在客户端实例之间创建和共享。构建器模式用于实例化这些对象。
客户端配置¶
可以使用配置参数构建 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 客户端实例需要使用构建器模式以参数形式传递 RestClientConfig
和 MindsphereCredentials
实例。
使用 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;
}