Agent Management Java 客户端¶

简介¶

Agent Management Java 客户端允许您上线、下线、更新和删除代理。可提供连接功能，实现与 MindSphere 平台的通信。

有关该服务的更多信息，请参见 Agent Management。

提示

在 IoT 环境中，assets 指 entity，aspects 指 propertyset。以下代码样本根据使用的 APIs 在这些术语中转换。
以下示例中的占位符由尖括号< >表示。

代理操作¶

代理客户端可以列出、创建、更新、读取和删除代理。

客户端名称：AgentOperationsClient

基本 Agent Management¶

创建代理¶

// Construct the AgentOperationsClient object
AgentOperationsClient agents_client = AgentOperationsClient.builder()
                                        .mindsphereCredentials(<credentials>)
                                        .restClientConfig(<config>)
                                        .build();

Agent agent = null;
try {
  agent = agents_client.createAgent(<agent_input>);
}catch (MindsphereException e) {
  // Exception handling
}

使用 SHARED_SECRET 安全配置文件创建代理¶

// Construct the AgentOperationsClient object as shown above

Agent agent = null;
try {
  agent = agents_client.createAgentWithSharedSecret(<entity_id>, <agent_name>);
}catch (MindsphereException e) {
 // Exception handling
}

使用 RSA 安全配置文件创建代理¶

// Construct the AgentOperationsClient object as shown above
Agent agent = null;
try {
  agent = agents_client.createAgentWithRSA(<entity_id>, <agent_name>);
}catch (MindsphereException e) {
  // Exception handling
}

列出所有代理¶

获取满足指定过滤输入条件的所有代理。

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.getAllAgents(<filter>, <size>, <page>, <sort>);
} catch (MindsphereException e) {
  // Exception handling
}

通过 ID 获取代理¶

// Construct the AgentOperationsClient object as shown above
Agent agent = null;

try {
  agent = agents_client.getAgentByID(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

更新代理¶

// Construct the AgentOperationsClient object as shown above
Agent agent = null;

try {
  agent = agents_client.updateAgent(<agent_id>, <agent_update>, <ifMatch>);
} catch (MindsphereException e) {
  // Exception handling
}

删除代理¶

// Construct the AgentOperationsClient object as shown above
try {
  agents_client.deleteAgent(<agent_id>, <ifMatch>);
} catch (MindsphereException e) {
  // Exception handling
}

获取代理的在线状态¶

// Construct the AgentOperationsClient object as shown above
OnlineStatus online_status = null;

try {
  online_status = agents_client.getAgentOnlineStatus(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

使用过滤器获取代理¶

获取具有特定名称的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByName(<filter_name>);
} catch (MindsphereException e) {
  // Exception handling
}

从列表中获取具有名称的代理¶

获取具有任一特定名称的代理列表。

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByNameIn(<filter_name_1>, <filter_name_2>);
} catch (MindsphereException e) {
  // Exception handling
}

获取具有特定名称的代理并以降序列出¶

获取具有特定名称且按降序排序的代理列表。

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByNameInDescendingOrder(<filter_name>);
} catch (MindsphereException e) {
  // Exception handling
}

获取名称以特定字符串开头的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByNameStartsWith(<filter_string>);
} catch (MindsphereException e) {
  // Exception handling
}

获取名称以特定字符串结尾的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByNameEndsWith(<filter_string>);
} catch (MindsphereException e) {
  // Exception handling
}

获取名称含有特定字符串的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByNameContains(<filter_string>);
} catch (MindsphereException e) {
  // Exception handling
}

获取具有特定 ID 的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByAgentId(<filter_id>);
} catch (MindsphereException e) {
  // Exception handling
}

从列表中获取具有 ID 的代理¶

获取具有任一特定 ID 的代理的列表。

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByIdIn(<filter_id_1>,<filter_id_2>);
} catch (MindsphereException e) {
  // Exception handling
}

获取 ID 以特定字符串开头的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByIdStartsWith(<filter_string>);
} catch (MindsphereException e) {
  // Exception handling
}

获取 ID 以特定字符串结尾的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByIdEndsWith(<filter_string>);
} catch (MindsphereException e) {
  // Exception handling
}

获取 ID 中包含特定字符串的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.filterAgentsByIdContains(<filter_string>);
} catch (MindsphereException e) {
  // Exception handling
}

获取代理的排序列表¶

获取按名称排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsByName();
} catch (MindsphereException e) {
  // Exception handling
}

获取按名称降序排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsByNameDescendening();
} catch (MindsphereException e) {
  // Exception handling
}

获取按 ID 排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsById();
} catch (MindsphereException e) {
  // Exception handling
}

获取按 ID 降序排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsByIdDescendening();
} catch (MindsphereException e) {
  // Exception handling
}

获取按实体 ID 排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsByEntityId();
} catch (MindsphereException e) {
  // Exception handling
}

获取按实体 ID 降序排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsByEntityIdDescendening();
} catch (MindsphereException e) {
  // Exception handling
}

获取按安全配置文件排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsBySecurityProfile();
} catch (MindsphereException e) {
  // Exception handling
}

获取按安全配置文件以降序排序的代理¶

// Construct the AgentOperationsClient object as shown above
AgentsList agents_list = null;

try {
  agents_list = agents_client.sortAgentsBySecurityProfileDescendening();
} catch (MindsphereException e) {
  // Exception handling
}

默认设置操作¶

代理默认设置客户端用于获取 RSA 配置文件的访问令牌、客户端声明和密钥。

客户端名称：AgentsDefaultSettingClient

获取访问令牌¶

访问令牌用于访问 MindSphere 服务。可以通过以下方式获取访问令牌：

创建代理、使代理上线及获取访问令牌。

// Construct the AgentsDefaultSettingClient object
AgentsDefaultSettingClient agents_default_setting_client = AgentsDefaultSettingClient.builder()
                                        .mindsphereCredentials(<credentials>)
                                        .restClientConfig(<config>)
                                        .build();

CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessToken(<entity_id>);
}catch (MindsphereException e) {
  // Exception handling
}

创建具有指定 asset ID、名称和安全配置文件的代理。使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessToken(<entity_id>, <agent_name>, <profile>);
}catch (MindsphereException e) {
  // Exception handling
}

创建具有指定 asset ID 和名称的代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessToken(<entity_id>, <agent_name>);
}catch (MindsphereException e) {
  // Exception handling
}

获取具有 SHARED_SECRET 的访问令牌¶

可以通过以下方式获取采用 SHARED_SECRET 安全配置文件的访问令牌：

创建采用 SHARED_SECRET 安全配置文件的代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenWithSharedSecret();
}catch (MindsphereException e) {
  // Exception handling
}

为指定租户创建采用 SHARED_SECRET 安全配置文件的代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenWithSharedSecret(<tenant_id>);
}catch (MindsphereException e) {
  // Exception handling
}

获取采用 RSA 的访问令牌¶

可以通过以下方式获取采用 RSA 安全配置文件的访问令牌：

创建采用 RSA 安全配置文件的代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenWithRSA();
}catch (MindsphereException e) {
  // Exception handling
}

为指定租户创建采用 RSA 安全配置文件的代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenWithRSA(<tenant_id>);
}catch (MindsphereException e) {
  // Exception handling
}

获取 Asset 的访问令牌¶

可以通过以下方式获取 asset 的访问令牌：

为指定 asset ID 创建代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenForEntity(<entity_id>);
}catch (MindsphereException e) {
  // Exception handling
}

为指定 asset ID 和租户创建代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenForEntity(<entity_id>, <tenant_id>);
}catch (MindsphereException e) {
  // Exception handling
}

获取某个 Asset Type 的访问令牌¶

可以通过以下方式获取 asset type 的访问令牌：

为指定 asset type 创建代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenForAssetType(<asset_type_id>);
}catch (MindsphereException e) {
  // Exception handling
}

为指定 asset type 和父 ID 创建代理，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenForAssetType(<asset_type_id>, <asset_parent_id>);
}catch (MindsphereException e) {
  // Exception handling
}

为指定 asset type、父 ID 和租户创建代理。使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenForAssetType(<tenant_id>, <asset_type_id>, <asset_parent_id>);
}catch (MindsphereException e) {
  // Exception handling
}

获取代理的访问令牌¶

可以通过以下方式获取现有代理的访问令牌：

使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenForAgent(<agent_id>);
}catch (MindsphereException e) {
  // Exception handling
}

使指定租户的代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenForAgent(<agent_id>, <tenant_id>);
}catch (MindsphereException e) {
  // Exception handling
}

带有上线配置上线并获取访问令牌¶

使具有指定配置的代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenWithOnBoardingConfig(<boarding_config>);
}catch (MindsphereException e) {
  // Exception handling
}

说明

可以通过 BoardingOperationsClient.getBoardingConfiguration(agentId) 检索 boardingConfig 对象。

当状态为 ONBOARDING 时，获取访问令牌¶

当代理状态为 ONBOARDING 时，使代理上线并获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
CreatedObjects created_objects = null;
try {
  created_objects = agents_default_setting_client.getAccessTokenDuringStatusOnBoarding(<agent_id>);
}catch (MindsphereException e) {
  // Exception handling
}

采用 SHARED_SECRET 的代理上线后，获取访问令牌¶

当采用 SHARED_SECRET 安全配置文件的代理状态为 ONBOARDED 时，获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
AccessToken access_token = null;
try {
  access_token = agents_default_setting_client.getAccessTokenAfterOnBoardedWithSharedSecret(<agent_id>, <tenant>, <client_secret>);
}catch (MindsphereException e) {
  // Exception handling
}

说明

可以通过 RegistrationOperationsClient.onBoardAgent() 检索 clientSecret 字符串。

使用客户端声明获取访问令牌¶

使用客户端声明获取访问令牌。

// Construct the AgentsDefaultSettingClient object as shown above
AccessToken access_token = null;
try {
  access_token = agents_default_setting_client.getAccessTokenFromClientAssertion(<client_assertion>);
}catch (MindsphereException e) {
  // Exception handling
}

说明

可以通过 agentsDefaultSettingClient.getClientAssertionForSharedSecret() 或 agentsDefaultSettingClient.getClientAssertionForRSA() 检索 clientAssertion 字符串。

获取 RSA 密钥¶

为采用 RSA 安全配置文件的代理生成公钥和私钥。

// Construct the AgentsDefaultSettingClient object as shown above
JWKModel model = null;
try {
  model = agents_default_setting_client.getKeysForRSAProfile();
}catch (MindsphereException e) {
  // Exception handling
}

获取 SHARED_SECRET 客户端声明¶

为采用 SHARED_SECRET 安全配置文件的代理生成客户端声明。

// Construct the AgentsDefaultSettingClient object as shown above
String client_assertion = null;
try {
  client_assertion = agents_default_setting_client.getClientAssertionForSharedSecret(<agent_id>, <tenant>, <client_secret>);
}catch (MindsphereException e) {
  // Exception handling
}

获取 RSA 客户端声明¶

为采用 RSA 安全配置文件的代理生成客户端声明。

// Construct the AgentsDefaultSettingClient object as shown above
String client_assertion = null;
try {
  client_assertion = agents_default_setting_client.getClientAssertionForRSAProfile(<agent_id>, <tenant>);
}catch (MindsphereException e) {
  // Exception handling
}

代理数据源配置操作¶

数据源配置客户端获取、创建并更新数据源配置。

客户端名称：DataSourceConfigurationOperationsClient

获取数据源配置¶

获取具有指定 ID 的代理的数据源配置。

// Construct the DataSourceConfigurationOperationsClient object
DataSourceConfigurationOperationsClient data_source_configuration_client = DataSourceConfigurationOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

DataSourceConfiguration data_source_configuration_client = null;
try {
  data_source_configuration = data_source_configuration_client.getDataSourceConfiguration(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

创建数据源配置¶

为具有指定 ID 的代理创建数据源配置。

// Construct the DataSourceConfigurationOperationsClient object as shown above
//Create a DataSource object
DataSource data_sources_item = new DataSource();
data_sources_item.setName(<name>);
data_sources_item.setDescription(<description>);
data_sources_item.setDataPoints(<data_points>) {
data_sources_item.customData(<custom_data>) {

//Create a DataSourceConfigurationInput object
DataSourceConfigurationInput configuration = new DataSourceConfigurationInput();
configuration.setConfigurationId(<configuration_id>);
configuration.addDataSourcesItem(data_sources_item);

DataSourceConfiguration data_source_configuration = null;

try {
  data_source_configuration = data_source_configuration_client.createDataSourceConfiguration(<agent_id>, configuration);
} catch (MindsphereException e) {
  // Exception handling
}

更新数据源配置¶

更新具有指定 ID 的代理的数据源配置。

// Construct the DataSourceConfigurationOperationsClient object as shown above
DataSourceConfiguration data_source_configuration = null;

try {
  data_source_configuration = data_source_configuration_client.updateDataSourceConfiguration(<agent_id>, <configuration>, <ifMatch>);
} catch (MindsphereException e) {
  // Exception handling
}

代理上线操作¶

上线客户端用于使代理下线并获取上线配置和上线状态。

客户端名称：BoardingOperationsClient

获取上线配置¶

获取具有指定 ID 的代理的上线配置。

// Construct the BoardingOperationsClient object
BoardingOperationsClient boarding_client = BoardingOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

BoardingConfiguration boarding_configuration = null;
try {
  boarding_configuration = boarding_client.getBoardingConfiguration(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

使代理下线¶

使具有指定 ID 的代理下线。

// Construct the BoardingOperationsClient object as shown above
OnboardingStatus onboarding_status = null;

try {
  onboarding_status = boarding_client.offBoard(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

获取上线状态¶

获取具有指定 ID 的代理的上线状态。

// Construct the BoardingOperationsClient object as shown above
OnboardingStatus onboarding_status = null;

try {
  onboarding_status = boarding_client.getBoardingStatus(<agent_id>);
} catch (MindsphereException e) {
  // Exception handling
}

代理注册操作¶

注册客户端可以注册代理并更新代理信息。

客户端名称：RegistrationOperationsClient

注册代理¶

注册代理。

// Construct the RegistrationOperationsClient object
RegistrationOperationsClient registration_client = RegistrationOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

ClientIdentifier client_identifier = null;
try {
  client_identifier = registration_client.onBoardAgent(<initial_access_token>, <keys>);
} catch (MindsphereException e) {
  /

说明

可以通过 BoardingOperationsClient.getBoardingConfiguration(agentId) 获取 initialAccessToken 字符串。

注册采用 SHARED_SECRET 安全配置文件的代理¶

// Construct the RegistrationOperationsClient object
ClientIdentifier client_identifier = null;
try {
  client_identifier = registration_client.onBoardAgentWithSharedSecretProfile(<initial_access_token>);
} catch (MindsphereException e) {
  /

注册采用 RSA 安全配置文件的代理¶

// Construct the RegistrationOperationsClient object
ClientIdentifier client_identifier = null;
try {
  client_identifier = registration_client.onBoardAgentWithRSAProfile(<initial_access_token>, <keys>);
} catch (MindsphereException e) {
  // Exception handling
}

更新 SHARED_SECRET 安全配置文件的客户端信息¶

更新具有指定 ID 的客户端的客户端信息。

// Construct the RegistrationOperationsClient object
ClientIdentifier client_identifier = null;

try {
  client_identifier = registration_client.rotateKeysForSharedSecret(<registration_access_token>, <client_id>);
} catch (MindsphereException e) {
  // Exception handling
}

更新 RSA 安全配置文件的客户端信息¶

更新具有指定 ID 的客户端的客户端信息。

// Construct the RegistrationOperationsClient object
ClientIdentifier client_identifier = null;
try {
  client_identifier = registration_client.rotateKeysForRSA(<registration_access_token>, <client_id>, <keys>);
} catch (MindsphereException e) {
  // Exception handling
}

代理令牌操作¶

令牌客户端用于获取访问令牌和 OAuth 服务器的密钥信息。

客户端名称：TokenOperationsClient

获取访问令牌¶

获取访问令牌。

// Construct the TokenOperationsClient object
TokenOperationsClient access_token_client = TokenOperationsClient.builder()
                                      .mindsphereCredentials(<credentials>)
                                      .restClientConfig(<config>)
                                      .build();

AccessToken access_token = null;
try {
  access_token = access_token_client.getAccessToken(<grant_type>, <client_assertion_type>, <client_assertion>);
} catch (MindsphereException e) {
  // Exception handling
}

提供 OAuth 服务器的密钥信息¶

提供 OAuth 服务器的密钥信息。

// Construct the TokenOperationsClient object as shown above
TokenKey token_key = null;
try {
  token_key = access_token_client.getPublicKeyFromServer(<ifNoneMatch>);
} catch (MindsphereException e) {
  // Exception handling
}

Last update: June 23, 2023