Asset Management Client for Python¶
Introduction¶
The Asset Management Service is used to interact with the digital representation of a machine or automation system. Refer to Asset Management for more information about the service.
Further implementation of the IOT AssetManagement SDK library has been shown in a sample project that you can download and test in local or on Insights Hub application. Please refer to this repository: industrial-iot-python-sdk-examples
Hint
Placeholders in the following samples are indicated by angular brackets < >
.
Aspect Type Operations¶
The aspect type client manages static and dynamic aspect types. It lists, creates, updates, reads, and deletes aspect types.
Client name: AspecttypeClient
List all Aspect Types¶
Get all aspect types of the tenant.
# Import the RestClientConfig and UserToken from mindsphere_core module
from mindsphere_core import RestClientConfig
from mindsphere_core import UserToken
# Import the MindsphereError from mindsphere_core.exceptions module
from mindsphere_core.exceptions import MindsphereError
# Import the AspecttypeClient from assetmanagement module
from assetmanagement import AspecttypeClient
# Import all required models from assetmanagement.models
from assetmanagement import ListAspectTypesRequest
# Create the RestClientConfig and UserToken objects
config = RestClientConfig(
proxy_host = "<proxy_host>",
proxy_port = <proxy_port>
)
credentials = UserToken(
authorization = "<token>"
)
# Create the AspecttypeClient object using the RestClientConfig and UserToken objects
aspecttypeClient = AspecttypeClient(
rest_client_config = config,
mindsphere_credentials = credentials
)
try:
# Create the request object
request_object = ListAspectTypesRequest(
page = <page>,
size = <size>,
sort = "<sort>",
filter = "<filter>",
if_none_match = "<if_none_match>"
)
# Initiate the API call to list aspect types
response = aspecttypeClient.list_aspect_types(request_object)
except MindsphereError as err:
# Exception Handling
Create an Aspect Type¶
# Create the AspecttypeClient object as shown above
try:
# Create the Aspect Variable objects
aspect_variable1 = AspectVariable(
name = "<name>",
data_type = "<data_type>",
unit = "<unit>",
searchable = <searchable>,
length = <length>,
default_value = <default_value>,
quality_code = "<quality_code>"
)
aspect_variable2 = AspectVariable(
name = "<name_2>",
data_type = "<data_type_2>",
unit = "<unit_2>",
searchable = <searchable_2>,
length = <length_2>,
default_value = <default_value_2>,
quality_code = "<quality_code_2>
)
# Create the AspectType object
aspect_type = AspectType(
name = "<aspect_name>",
category = "<aspect_category>",
scope = "<aspect_scope>",
description = "<aspect_description>",
variables = [aspect_variable1, aspect_variable2],
)
# Create the request object
request_object = SaveAspectTypeRequest(
id = "<aspect_id>",
aspecttype = aspect_type,
if_match = None
)
# Initiate the API call to save the aspect type
response = aspecttypeClient.save_aspect_type(request_object)
except MindsphereError as err:
# Exception Handling
Update an Aspect Type¶
Variables can only be added, but not removed or renamed.
# Create the AspecttypeClient object as shown above
try:
# Create the AspectVariable object
aspect_variable1 = AspectVariable(
name = "<var_name>",
data_type = "<data_type>",
unit = "<unit>",
searchable = <searchable>,
length = <length>,
default_value = <default_value>,
quality_code = "<quality_code>'
)
# Create the AspectType object
aspect_type = AspectType(
name = "<aspect_name>",
category = "<category>",
scope = "<scope>",
description = "<description>",
variables = [aspect_variable1],
)
# Create the request object
request_object = UpdateAspectTypeRequest(
id = "<aspect_id>",
aspecttype = aspect_type,
if_match = "<if_match>"
)
# Initiate the API call to update an aspect type
response = aspecttypeClient.update_aspect_type(request_object)
except MindsphereError as err:
# Exception Handling
Read an Aspect Type by ID¶
# Create the AspecttypeClient object as shown above
try:
# Create the request object
request_object = GetAspectTypeRequest(
id = "<aspect_id>",
if_none_match = "<if_none_match>"
)
# Initiate the API call to get an aspect type
response = aspecttypeClient.get_aspect_type(request_object)
except MindsphereError as err:
# Exception Handling
Delete an Aspect Type¶
An aspect type can only be deleted, if no asset type uses it.
# Create the AspecttypeClient object as shown above
try:
# Create the request object
request_object = DeleteAspectTypeRequest(
id = "<aspect_id>",
if_match = "<if_match>"
)
# Initiate the API call to delete an aspect type
response = aspecttypeClient.delete_aspect_type(request_object)
except MindsphereError as err:
# Exception Handling
Asset Type Operations¶
The asset type client manages asset types. It lists, creates, updates, reads and deletes asset types. It can also be used to add and delete file assignments to asset types.
Client name: AssettypeClient
List all Asset Types¶
List all asset types of the tenant.
# Import the RestClientConfig and UserToken from mindsphere_core module
from mindsphere_core import RestClientConfig
from mindsphere_core import UserToken
# Import the MindsphereError from mindsphere_core.exceptions module
from mindsphere_core.exceptions import MindsphereError
# Import the AssettypeClient from assetmanagement module
from assetmanagement.clients.assettype_client import AssettypeClient
# Import all required models from assetmanagement.models
from assetmanagement.models import ListAssetTypesRequest
# Create the RestClientConfig and UserToken objects
config = RestClientConfig(
proxy_host = "<proxy_host>",
proxy_port = <proxy_port>
)
credentials = UserToken(
authorization = "<bearer_token>"
)
# Create the AssettypeClient object using the RestClientConfig and UserToken objects
assettypeClient = AssettypeClient(
rest_client_config = config,
mindsphere_credentials = credentials
)
try:
# Create the request object
request_object = ListAssetTypesRequest(
page = <page>,
size = <size>,
sort = "<sort>",
filter = "<filter>",
if_none_match = "<if_none_match>"
)
# Initiate the API call to list asset types
response = assettypeClient.list_asset_types(request_object)
except MindsphereError as err:
# Exception Handling
Create an Asset Type¶
# Create the AssettypeClient object as shown above
try:
# Create the AssetTypeAspects object
aspect = AssetTypeAspects(
name = "<aspect_name>",
aspect_type_id = "<aspect_typeid>"
)
# Create a list containing the AssetTypeAspect object
asset_type_aspects_list = [aspect]
# Create the VariableDefinition object
variable1 = VariableDefinition(
name = "<variable_name>",
data_type = "<variable_type"",
unit = "<var_unit>",
searchable = "<searchable>",
length = <var_length>,
)
# Create a list containing the VariableDefinition object
variable_list = [variable1]
# Create the FileAssignment object
file_assignment = FileAssignment(
key = "<file_key>",
file_id = "<file_id>"
)
# Create a list containing the FileAssignment object
file_assignments_list = [file_assignment]
# Create the AssetType object
asset_type = AssetType(
name = "<name>",
description = "<description>",
parent_type_id = "<parent_type_id>",
instantiable = "<instantiable>",
scope = "<scope>",
variables = variable_list,
file_assignments = file_assignments_list,
aspects = asset_type_aspects_list
)
# Create the request object
request_object = SaveAssetTypeRequest(
if_match = None,
id = "<asset_type_id>",
assettype = asset_type
)
# Initiate the API call to create an asset type
response = assettypeClient.save_asset_type(request_object)
except MindsphereError as err:
# Exception Handling
Update an Asset Type¶
# Create the AssettypeClient object as shown above
try:
# Create the AssetTypeAspects object
aspect = AssetTypeAspects(
name="<aspectname>",
aspect_type_id="<aspecttype_id>"
)
# Create a list containing the AssetTypeAspects object
asset_type_aspects_list = [aspect]
# Create the VariableDefinition object
variable1 = VariableDefinition(
name = "<variable_name>",
data_type = "<variable_type>",
unit = "<var_unit>",
searchable = "<searchable>",
length = <var_length>,
)
# Create a list containing the VariableDefinition object
variable_list = [variable1]
# Create the File Assignment instance
file_assignment = FileAssignment(
key = "<file_key>",
file_id = "<file_id>"
)
# Create a list containing the FileAssignment object
file_assignments_list = [file_assignment]
# Create the AssetType object
asset_type = AssetType(
name = "<name>",
description = "<description>",
parent_type_id = "<parent_type_id>",
instantiable = <instantiable>,
scope = "<scope>",
variables = variable_list,
file_assignments = file_assignments_list,
aspects = asset_type_aspects_list
)
# Create the request object
request_object = UpdateAssetTypeRequest(
if_match = "<if_match>",
id = "<asset_type_id>",
assettype = asset_type
)
# Initiate the API call to update an asset type
response = assettypeClient.update_asset_type(request_object)
except MindsphereError as err:
# Exception Handling
Read an Asset Type¶
# Create the AssettypeClient object as shown above
try:
# Create the request object
request_object = GetAssetTypeRequest(
if_none_match = "<if_none_match>",
exploded = "<exploded>",
id = "<asset_type_id>"
)
# Initiate the API call to get asset types
response = assettypeClient.get_asset_type(request_object)
except MindsphereError as err:
# Exception Handling
Delete an Asset Type¶
Deletion is only possible for asset types without children and when there is no asset instantiating them.
# Create the AssettypeClient object as shown above
try:
# Create the request object
request_object = DeleteAssetTypeRequest(
if_match = "<if_match>",
id = "<asset_type_id>"
)
# Initiate the API call to delete an asset type
response = assettypeClient.delete_asset_type(request_object)
except MindsphereError as err:
# Exception Handling
Add a New File Assignment to an Asset Type¶
By default, the file is automatically assigned to asset types which extend this type and assets instantiated from it.
# Create the AssettypeClient object as shown above
try:
# Create the KeyedFileAssignment object
assignment = KeyedFileAssignment(
file_id = "<file_id>"
)
# Create the request object
request_object = SaveAssetTypeFileAssignmentRequest(
if_match = "<if_match>",
assignment = assignment,
id = "<asset_type_id>",
key = "<file_key>"
)
# Initiate the API call to add a file assignment to an asset
response = assettypeClient.save_asset_type_file_assignment(request_object)
except MindsphereError as err:
# Exception Handling
Delete a File Assignment from an Asset Type¶
If the file is assigned to the type's parent, its key will be displayed in the inherited value field.
# Create the AssettypeClient object as shown above
try:
# Create the request object
request_object = DeleteAssetTypeFileAssignmentRequest(
if_match = "<if_match>",
id = "<asset_type_id>",
key = "<file_key>"
)
# Initiate the API call to delete a file assignment from an asset type
response = assettypeClient.delete_asset_type_file_assignment(request_object)
except MindsphereError as err:
# Exception Handling
Asset Operations¶
The asset client manages a user's assets and their locations. Three different types of assets can be created: device types, agent types and hierarchy types. The asset client lists, creates, updates, reads, deletes, moves and replaces assets. It can also be used to add and delete file assignments to assets.
Client name: AssetsClient
List all Assets¶
List all assets available for the authenticated user.
# Import the RestClientConfig and UserToken from mindsphere_core module
from mindsphere_core import RestClientConfig
from mindsphere_core import UserToken
# Import the MindsphereError from mindsphere_core.exceptions module
from mindsphere_core.exceptions import MindsphereError
# Import the AssetsClient from assetmanagement module
from assetmanagement.clients.assets_client import AssetsClient
# Import all required models from assetmanagement.models
from assetmanagement.models import ListAssetsRequest
# Create the RestClientConfig and UserToken objects
config = RestClientConfig(
proxy_host = "<proxy_host>",
proxy_port = <proxy_port>
)
credentials = UserToken(
authorization = "<bearer_token>"
)
# Create the AssetsClient object using the RestClientConfig and UserToken objects
assetsClient = AssetsClient(
rest_client_config = config,
mindsphere_credentials = credentials
)
try:
# Create the request object
request_object = ListAssetsRequest(
page = <page>,
size = <size>,
sort = "<sort>",
filter = "<filter>",
if_none_match = "<if_none_match>"
)
# Initiate the API call to list assets
response = assetsClient.list_assets(request_object)
except MindsphereError as err:
# Exception Handling
Create an Asset¶
# Create the AssetsClient object as shown above
try:
# Create the Asset object
asset_obj = Asset(
name = "<name>",
parent_id = "<parent_id>",
type_id = "<asset_type_id>"
)
# Create the request object
request_object = AddAssetRequest(
asset = asset_obj
)
# Initiate the API call to create an asset
response = assetsClient.add_asset(request_object)
except MindsphereError as err:
# Exception Handling
Read an Asset¶
All static properties of the asset are returned.
# Create the AssetsClient object as shown above
try:
# Create the request object
request_object = GetAssetRequest(
if_none_match = "<if_none_match>",
id = "<id>"
)
# Initiate the API call to get an asset
response = assetsClient.get_asset(request_object)
except MindsphereError as err:
# Exception Handling
Update an Asset¶
Only values can be modified, but not the asset structure. The asset structure can be modified in the asset type.
# Create the AssetsClient object as shown above
try:
# Create the Location object
location = Location(
country = "<country>",
region = "<region>",
longitude = "<longitude>',
locality = "<locality>",
latitude = "<latitude>",
postal_code = "<postal_code>"
)
# Create the KeyedFileAssignment object
assignment = KeyedFileAssignment(
file_id = "<file_id>"
)
# Create the AssetUpdate object
asset_object = AssetUpdate(
name = "<name>",
external_id = "<external_id>",
description = "<description>",
location = location,
file_assignments = [assignment]
)
# Create the request object
request_object = UpdateAssetRequest(
if_match = "<if_match>",
id = "<asset_id>",
asset = asset_object
)
# Initiate the API call to update an asset
response = assetsClient.update_asset(request_object)
except MindsphereError as err:
# Exception Handling
Delete an Asset¶
After deletion, users with an admin role can still read the asset, but modification is not possible anymore. It is not possible to delete an asset if it has children.
# Create the AssetsClient object as shown above
try:
# Create the request object
request_object = DeleteAssetRequest(
if_match = "<if_match>",
id = "<asset_id>"
)
# Initiate the API call to delete an asset
asset = assetsClient.delete_asset(request_object)
except MindsphereError as err:
# Exception Handling
Move an Asset¶
Move an asset and all of its children in the hierarchy.
# Create the AssetsClient object as shown above
try:
# Create the AssetMove object
move_parameters = AssetMove(
new_parent_id = "<parent_id>"
)
# Create the request object
request_object = MoveAssetRequest(
if_match = "<if_match>",
id = "<asset_id>",
move_parameters = move_parameters
)
# Initiate the API call to move an asset
response = assetsClient.move_asset(request_object)
except MindsphereError as err:
# Exception Handling
Replace an Asset¶
# Create the AssetsClient object as shown above
try:
# Create the Asset object
asset_obj = Asset(
name = "<name>",
parent_id = "<parent_id>",
type_id = "<type_id>"
)
# Create the request object
request_object = ReplaceAssetRequest(
if_match = "<if_match>",
id = "<asset_id>",
asset = asset_obj
)
# Initiate the API call to replace an asset
response = assetsClient.replace_asset(request_object)
except MindsphereError as err:
# Exception Handling
Get the User's Root Asset¶
Read the user's root asset, from which the whole asset hierarchy can be rebuilt.
# Create the AssetsClient object as shown above
try:
# Create the request object
request_object = GetRootAssetRequest(
if_none_match = "<if_none_match>"
)
# Initiate the API call to get the root asset
response = assetsClient.get_root_asset(request_object)
except MindsphereError as err:
# Exception Handling
Add a New File Assignment to an Asset¶
The file is assigned to all children of the asset by default.
# Create the AssetsClient object as shown above
try:
# Create the KeyedFileAssignment object
assignment = KeyedFileAssignment(
file_id = "<file_id>"
)
# Create the request object
request_object = SaveAssetFileAssignmentRequest(
if_match = "<if_match>",
assignment = assignment,
id = "<asset_id>",
key = "<file_key>"
)
# Initiate the API call to add a file assignment to an asset
response = assetsClient.save_asset_file_assignment(request_object)
except MindsphereError as err:
# Exception Handling
Delete a File Assignment from an Asset¶
# Create the AssetsClient object as shown above
try:
# Create the request object
request_object = DeleteAssetFileAssigmentRequest(
if_match = "<if_match>",
id = "<asset_id>",
key = "<file_key>"
)
# Initiate the API call to delete an asset's file assignment
response = assetsClient.delete_asset_file_assigment(request_object)
except MindsphereError as err:
# Exception Handling
Structure Operations¶
The structure client is used to list an asset's aspects and variables.
Client name: StructureClient
Get an Asset's Variables¶
Get all variables of an asset.
# Import the RestClientConfig and UserToken from mindsphere_core module
from mindsphere_core import RestClientConfig
from mindsphere_core import UserToken
# Import the MindsphereError from mindsphere_core.exceptions module
from mindsphere_core.exceptions import MindsphereError
# Import the StructureClient from assetmanagement module
from assetmanagement.clients.structure_client import StructureClient
# Import all required models from assetmanagement.models
from assetmanagement.models import *
# Create the RestClientConfig and UserToken objects
config = RestClientConfig(
proxy_host = "<proxy_host>",
proxy_port = <proxy_port>
)
credentials = UserToken(
authorization = "<bearer_token>"
)
# Create the StructureClient object using the RestClientConfig and UserToken objects
structureClient = StructureClient(
rest_client_config = config,
mindsphere_credentials = credentials
)
try:
# Create the request object
request_object = ListAssetVariablesRequest(
filter = "<filter>",
if_none_match = "<if_none_match>",
size = <size>,
id = "<asset_id>",
page = <page>,
sort = "<sort>"
)
# Initiate the API call to list an asset's variables
response = structureClient.list_asset_variables(request_object)
except MindsphereError as err:
# Exception Handling
Get all Aspects of an Asset¶
# Create the StructureClient object as shown above
try:
# Create the request object
request_object = ListAssetAspectsRequest(
filter = "<filter>",
if_none_match = "<if_none_match>",
size = <size>,
id = "<asset_id>",
page = <page>,
sort = "<sort>"
)
# Initiate the API call to list an asset's aspects
response = structureClient.list_asset_aspects(request_object)
except MindsphereError as err:
# Exception Handling
Locations Operations¶
The locations client manages the location of an asset. It can be used to create, update and delete an asset's location.
Client name: LocationsClient
Create or Update an Asset's Location¶
If no location is defined for the asset yet, a new one is created. Otherwise, it is updated.
# Import the RestClientConfig and UserToken from mindsphere_core module
from mindsphere_core import RestClientConfig
from mindsphere_core import UserToken
# Import the MindsphereError from mindsphere_core.exceptions module
from mindsphere_core.exceptions import MindsphereError
# Import the LocationsClient from assetmanagement module
from assetmanagement.clients.locations_client import LocationsClient
# Import all required models from assetmanagement.models
from assetmanagement.models import *
# Create the RestClientConfig and UserToken objects
config = RestClientConfig(
proxy_host = "<proxy_host>",
proxy_port = <proxy_port>
)
credentials = UserToken(
authorization = "<bearer_token>"
)
# Create the LocationsClient object using the RestClientConfig and UserToken objects
locationsClient = LocationsClient(
rest_client_config = config,
mindsphere_credentials = credentials
)
try:
# Create the Location object
location = Location(
country = "<country>",
region = "<region>",
longitude = "<longitude>",
locality = "<locality>",
latitude = "<latitude>",
postal_code = "<postal_code>"
)
# Create the request object
request_object = SaveAssetLocationRequest(
if_match = "<if_match>",
location = location,
id = "<asset_id>"
)
# Initiate the API call to save an asset's location
response = locationsClient.save_asset_location(request_object)
except MindsphereError as err:
# Exception Handling
Delete an Asset's Location¶
# Create the LocationsClient object as shown above
try:
# Create the request object
request_object = DeleteAssetLocationRequest(
if_match = "<if_match>",
id = "<asset_id>"
)
# Initiate the API call to delete an asset's location
response = locationsClient.delete_asset_location(request_object)
except MindsphereError as err:
# Exception Handling
Billboard Operations¶
The billboard client can be used to list all available resources.
Client name: BillboardClient
List all Available Resources¶
# Import the RestClientConfig and UserToken from mindsphere_core module
from mindsphere_core import RestClientConfig
from mindsphere_core import UserToken
# Import the MindsphereError from mindsphere_core.exceptions module
from mindsphere_core.exceptions import MindsphereError
# Import the BillboardClient from assetmanagement module
from assetmanagement.clients.billboard_client import BillboardClient
# Import all required models from assetmanagement.models
from assetmanagement.models import *
# Create the RestClientConfig and UserToken objects
config = RestClientConfig(
proxy_host = "<proxy_host>",
proxy_port = <proxy_port>
)
credentials = UserToken(
authorization = "<bearer_token>"
)
# Create the BillboardClient object using the RestClientConfig and UserToken objects
billboardClient = BillboardClient(
rest_client_config = config,
mindsphere_credentials = credentials
)
try:
# Initiate the API call to retrieve the billboard
response = billboardClient.get_billboard()
except MindsphereError as err:
# Exception Handling
File Operations¶
The files client manages files that can be assigned to a resource. It is used to list, read, upload, delete, replace and download a file.
Client name: FilesClient
List all Files¶
Get the metadata of all uploaded files.
# Import the RestClientConfig and UserToken from mindsphere_core module
from mindsphere_core import RestClientConfig
from mindsphere_core import UserToken
# Import the MindsphereError from mindsphere_core.exceptions module
from mindsphere_core.exceptions import MindsphereError
# Import the FilesClient from assetmanagement module
from assetmanagement.clients.files_client import FilesClient
# Import all required models from assetmanagement.models
from assetmanagement.models import *
# Create RestClientConfig and UserToken objects
config = RestClientConfig(
proxy_host = "<proxy_host>",
proxy_port = <proxy_port>
)
credentials = UserToken(
authorization = "<bearer_token>"
)
# Create the FilesClient object using the RestClientConfig and UserToken objects
filesClient = FilesClient(
rest_client_config = config
mindsphere_credentials = credentials
)
try:
# Create the request object request = ListFilesRequest(
page = <page>,
size = <size>,
sort = "<sort>",
filter = "<filter>",
if_none_match = "<if_none_match>"
)
# Initiate the API call to list files
response = filesClient.list_files(request)
except MindsphereError as err:
# Exception Handling
Get a File¶
Get the metadata of a file with the specified ID.
# Create the FilesClient object as shown above
try:
# Create the request object
request = GetFileRequest(
file_id = "<file_id>",
if_none_match = "<if_none_match>"
)
# Initiate the API call to retrieve files
response = filesClient.get_file(request)
except MindsphereError as err:
# Exception Handling
Download a File¶
Return the file with the specified ID.
# Create the FilesClient object as shown above
try:
# Create the request object
request = DownloadFileRequest(
file_id = "<file_id>"
)
# Initiate the API call to download files
response = filesClient.download_file(request)
except MindsphereError as err:
# Exception Handling
Replace a File¶
Update a previously uploaded file. The maximum file size is 5 MB.
# Create the FilesClient object as shown above
try:
# Create the request object
request_object = ReplaceFileRequest(
file_id = "<file_id>",
if_match = "<if_match>",
scope = "<scope>",
description = "<description>",
file = "<file_path>",
name = "<name>"
)
# Initiate the API call to replace a file
response = filesClient.replace_file(request)
except MindsphereError as err:
# Exception Handling
Upload a File¶
Upload a file to be used in Asset Management.
# Create the FilesClient object as shown above
try:
# Create the request object
request = UploadFileRequest(
file = "<Path of the file on the file system>",
scope = "<scope>",
name = "<name>",
description = "<description>"
)
# Initiate the API call for file upload
response = filesClient.upload_file(request)
except MindsphereError as err:
# Exception Handling
Delete a File¶
# Create the FilesClient object as shown above
try:
# Create the request object
request = DeleteFileRequest(
file_id = "<file_id>",
if_match = "<if_match>"
)
# Initiate the API call to delete a file
response = filesClient.delete_file(request)
except MindsphereError as err:
# Exception Handling