Using Asset Service

Using Asset Service

Use the Asset service to create, update, and store asset model data that defines asset properties and relationships between assets and other modeling elements.

Asset Service API Request Methods and Parameters

The Asset service supports POST, GET, PUT, PATCH, and DELETE request methods. The Asset service supports the fields, filter, and pageSize request parameters.

Client applications can access asset data using Asset service REST API endpoints. These endpoints provide a JSON interface where you can post the data that describes all of your assets. To use these APIs, your application makes HTTPS requests and parses the response. You can use any web-development language to access the APIs.

Requests timeout automatically after 120 seconds.

Request Methods

MethodDescription
POSTCreates or updates a set of resources. You can POST to a collection, but not to a specific resource. A POST request cannot exceed 50 MB.

If you plan to use Audit History, you need to add Audit History metadata to your request headers.

GETRetrieves resources. Use GET /assets to return all domain objects.
PUTCreates or updates a single resource. You can use this method for an individual resource, but not for a collection.
PATCHUpdate values of a resource property. You can add, remove, modify, and replace values of a resource record. You can use this method for an individual resource, but not for a collection. Use this method if you are concerned about network efficiency.
DELETERemoves or deletes a resource. You can use this method for an individual resource, but not for a collection.
Note: Excessive DELETE requests un-stabilize Predix-Asset service. Use them only occasionally when necessary to delete an object.

Request Parameters

Request ParametersDescription
fieldsRetrieves selected fields of a large object or a collection of large objects. For example, to retrieve a few attributes from an asset with many attributes, indicate the selected attributes in the fields clause. See asset-service-sample-api.html#reference_2d928f3d-d43c-4bd0-af27-8d266dae34ee.
filterUse Graph Expression Language (GEL) in the filter clause of a GET request to filter the data that appears in results. See asset-service-using.html#concept_828157be-2bee-44dd-b154-714f242bd175.
pageSizeDefines the number of entities to be returned per page (default is 100). Maximum pageSize is 1000. See asset-service-sample-api.html#reference_42c26985-0340-4438-ace1-9e1c3868a2b5.

The following sample request uses filter and the fields request parameters:

http://<your-asset_instance-uri>/locomotives?filter=type=Diesel-electric&fields=uri,model

The request syntax is described in the following table:

Request itemDescription
http://<your-asset_instance-uri>/URI of your Asset service instance, from the VCAP_SERVICES environment variable. A typical URI looks similar to this: http://predix-asset-rc.grc-apps.svc.ice.ge.com.
/locomotivesTarget endpoint for your request.
?Separates the endpoint from the request parameters.
filter=type=Diesel-electricFilter clause containing a GEL query requesting all locomotives of the type Diesel-electric.
&Separates request parameters.
fields=uri,modelClause requesting that only uri and model are returned.

See also asset-service-sample-api.html#reference_8c1e0944-babc-4f8a-bba0-8492e8439fa5.

Graph Expression Language (GEL) Syntax

Understand the Graph Expression Language (GEL) that is used to query and update Predix Asset repositories.

Use Graph Expression Language (GEL) in the filter clause of a API request to run a query against Asset service data. You can use any combination of operators or multiple operators of the same type.

The filter clause in a GEL query allows you to filter the data that appears in results. This section lists several operators and expressions with examples, but you can use any combination of operators or multiple operators of the same type. Filters are not allowed in POST, PUT, PATCH, or DELETE requests.

GEL Symbols and Operators

Use the following syntax when constructing GEL queries.
SymbolOperatorInterpretation
()Use parentheses to override the default left-to-right order of operations. Evaluation then takes place from left to right within the parentheses first. The single result is then used as a single term for evaluation outside the parentheses.
:ANDRead the colon character “:” as AND. The ampersand “&” is a reserved character and has special meaning in URLs.

See EQUALS (=) combined with AND (:).

|ORRead the pipe “|”as OR.

See EQUALS (=) combined with OR (|).

..RANGERead two periods (..) as a range between two numbers, two dates, or two strings.

See asset-service-sample-api.html#reference_545df9e3-07a4-44ff-b7ce-870c3328d0d8

Using the Dot Character in Keys and Values

If your JSON Key value includes a dot character, you need to escape the Dot (.) in a query to pass the information after the Dot in the query to the server. Otherwise, your query will be truncated at the Dot.

uri: “/assets/1”,
model.id: “76865”

To query this information: filter=model\.id=76865

If a Dot appears in your data value, do not escape the Dot.

filter=hqLatLng.lat=47.655492
SymbolOperatorInterpretation
.DotThe dot (.) is used to flatten keys of internal JSON objects. Example: value1.value2

If a key contains a dot, there are 2 cases you must consider.

Case 1: The key has the dot in the data posted by the user. In this case the user needs to escape it with a backslash at the time of querying so that it is not interpreted as a control character in the GEL syntax.

Example JSON: {uri: /assets/1, a.b : c}

The query for "c" would look like this: filter=a\.b=c

Case 2: The key has a dot which is formed when internal objects are flattened. In this case, do not escape the dot character.

The key has the dot in the data posted by the user. In this case the user needs to escape it with a backslash so that it is not interpreted as a control character in the GEL syntax.

On the other hand, if the value contains the dot character, do not escape it.

Example JSON: {uri : /assets/1, a:{b:c}} To query for "c" in this case, do not escape the dot. filter=a.b=c

.

RELATE Operations

Use forward and backward relate requests to query relationships of objects stored in your asset model. There are two ways to traverse relationships:
  • A forward-relate request uses the “>” operator and traverses in the direction of the relationship.
  • A backward-relate request uses the “<” operator and traverses in the opposite direction of the relationship.

See asset-service-sample-api.html#reference_838fcfd0-a03f-462e-97c2-2dad689c38cd.

SymbolOperatorInterpretation
>FORWARD-RELATERead the greater than character “>” as forward-relate. It selects values stored in the currently selected objects based on predicate (property key). The new selection is the set of values where the object.predicate == value is included in the current selection.  
>FORWARD-RELATERead the greater than character “>” as forward-relate. It selects values stored in the currently selected objects based on predicate (property key). The new selection is the set of values where the object.predicate == value is included in the current selection.  
> [token]FORWARD-RELATE with transitive closure

Read the letter “t” followed by a number enclosed in square brackets [tn] as a transitive closure token. For example, the following query retrieves all parent assets of piston asset, moving up five levels in the asset hierarchy:

/asset?filter=name=piston>parent[t5]

<BACKWARD-RELATE

Read the less than character “<” as backward-relate. If the predicate is the property key in another REST resource, and the value in the URI of a REST resource in the current selection, then that object is selected.

For example, the following query finds all locomotives with a given manufacturer:

<asset-app-url>/locomotive?filter=(name=General Electric Transportation)<manufacturer

See asset-service-sample-api.html#reference_838fcfd0-a03f-462e-97c2-2dad689c38cd.

<[token]BACKWARD-RELATE with transitive closure

Read the letter “t” followed by a number enclosed in square brackets [tn] as a transitive closure token. For example, the following query retrieves all child assets of the GE-Aircraft asset, moving five levels down in the asset hierarchy:

/asset?filter=name=GE-Aircraft<parent[t5]

Using Special Characters in GEL Query Keys and Values

If your query keys and values include special characters that conflict with the GEL operators, escape the special character with a backslash to prevent a processing conflict.

For example, for a forward relate (>) in a key, precede the > with a backslash (\>) before you submit the query.

Character Limitations for Attribute Keys and Values

Attribute keys and attribute values are limited to 65,000 characters.

EntityBehavior
Attribute valuesIf an attribute value contains more than 65,000 characters, the JSON object will be stored in the Asset repository, but searching on a 65,000-character value is not supported.
Attribute keysAn attribute key cannot contain more than 65,000 characters. The JSON will be rejected at the time of the PUT or POST request.
The following error message will be returned:
PA_ENTITY_KEY_EXCEEDS_CHAR_LIMIT
"Entity keys may not contain more than 65000 characters"

Creating GEL Queries

Follow this railroad diagram to create your GEL queries. Start on the left edge and follow the tracks to the right edge. Oval shapes represent literals. Rounded rectangles represent rules and descriptions.

Figure: GEL Query Railroad Diagram

Unbinding an Asset Service Instance

Use the cf unbind-service command to unbind and asset instance from an application.

Procedure

Unbind an Asset service instance:
where
  • <appName> is the name of your application.
  • <service-instance-name> is my_asset_instance.
The service instance is unbound from the application.

Deleting an Asset Service Instance

Use the cf delete-service command to delete an asset service instance. Deleting an Asset service instance also deletes any data that is in the Asset service instance data repositories.

Procedure

Delete an Asset service instance:
cf delete-service predix-asset <my_asset_instance>

Validating Asset Data

Validate Predix Asset data against a JSON schema upon ingestion.

Data ingested into a Predix Asset service is automatically validated against the schema that defines the domain objects.

Supported REST Methods

  • GET to display the current schema that defines your domain objects.
  • DELETE to delete a current schema that defines your domain objects; you cannot modify properties, but you can delete the current schema and replace it with a new one.
  • PUT to upload a new schema; you can add properties to an existing schema or replace an entire schema, but you cannot modify any existing properties in the current schema.
Note: JSON Version 4 is required. Any other version will return an error code.

Syntax

/system/schema/entities/{entity-type}

Endpoint

/system/schema/entities/assets

Troubleshooting Asset Data Validation

Error messages are returned showing the error code, customized message describing the error, and the suggested resolution, as shown in this example:

 "code": "PA_SCHEMA_DATA_VALIDATION_FAILURE",
  "message": "Provided data has failed schema validation(s)",
 "suggestion": "Please ensure it conforms with defined
      schema",
Error ConditionResponse Status CodeEvent Message and Resolution
The uploaded data does not match the schema that describes the domain object.422Message: Provided data has failed schema validation(s)",

Suggestion: Ensure that the data you provide is compliant with the schema definition.

The schema could not be uploaded.422Messages: Provided schema has failed JSON schema validation(s).

Suggestion: Please ensure the schema conforms to JSON schema, Version 4.

An attempt to remove a property from an existing schema failed.422Message: Provided schema ca not remove existing schema property.

Suggestion: Property <custom field> can not be removed.

You can add new properties to an existing schema, but you cannot remove an existing property. You must delete the existing schema and upload a new one to change properties.

An attempt to modify an existing schema property failed422Message: Provided schema cannot change existing schema property type.

Suggestion: Property <property-name> cannot change from type {1} to {2}.

You cannot change a property type in an existing schema. You must delete the schema and upload a new one.

An attempt to upload a schema has failed because the schema contained an incorrect property type.422Message: Provided schema has failed JSON schema validations(s).

Suggestion: The schema must contain: {properties:{uri:{type:'string'}}}. Any other property type causes the schema validation to fail.

Other error notifications.422Message: A custom message will be sent indicating details of the error

Suggestion:

.