In this release
The new Streaming API management goes out to preview, giving you full control to setup and control Streams. Also, in this release we implemented Agent specific properties that represent agent properties bag, and new endpoints are released in the preview API. Released new endpoint that gives possibility to retrieve latest observations for multiple actuators. Lastly, ExtendedTwinInfo was moved from allowWriteTwinClasses section of Resource Permission Policy to a new allowWriteExternals, and renamed to AppSpecificProperties.
New functionality
Resource Permission Policy with allowWriteExternals section
RPP improvement: allowWriteExternals section. In a previous release a new value(ExtendedTwinInfo) in allowWriteTwinClasses was introduced to manage security for Application Specific Properties. Starting from this release the value ExtendedTwinInfo is no longer valid for allowWriteTwinClasses. There is a new section in RPP, called allowWriteExternals and to provide permissions for applications to write Application Specific Properties, this section should contain value AppSpecificProperties.
Agent Specific Properties (Preview API)
Agent Specific Properties – represents agent properties bag. All endpoints for Agent Specific properties are authorized by application ID. Persons do not have permission to access Agent Specific Properties, only application agents.
Endpoints to manage Agent Specific Properties:
Agent Specific Properties (Preview API)
Agent Specific Properties – represents agent properties bag. All endpoints for Agent Specific properties are authorized by application ID. Persons do not have permission to access Agent Specific Properties, only application agents.
Endpoints to manage Agent Specific Properties:
– GET /preview/json/agent/{agentId}/agentspecificproperties/ schema/ {schemaId} – Get Agent specific properties for agent with matching unique identifier;
– POST /preview/json/agent/agentspecificproperties/schema/ {schemaId} – Get Agent specific properties by schema id;
– POST /preview/json/agent/agentspecificproperties – Create Agent specific properties for agent with matching unique identifier;
– PUT /preview/json/agent/agentspecificproperties – Update Agent specific properties for agent with matching unique identifier;
– DELETE /preview/json/agent/{agentId}/agentspecificproperties/ schema/ {schemaId} – Delete Agent specific properties for agent with matching unique identifier;
– POST /preview/json/agents/agentspecificproperties – Create Agent specific properties for agents;
– PUT /preview/json/agents/agentspecificproperties – Update Agent specific properties for agents;
– POST /preview/json/agents/agentspecificproperties/delete – Delete Agent specific properties for agents.
Streaming API Management (Preview API)
Streaming API – online telemetry flow that could be consumed by any client. Each data consumption is regulated by ProptechOS ResourcePermissionPolicy. Data flow consumption is possible via Organization access. Each Organization may have up to 10 streams that could be consumed by any EventHub consumer or any Kafka client.
1. Stream Management
Stream – ProptechOS agent that may be granted with ResourcePermissionPolicies to get access to sensor stream telemetry. For each Stream agent one EventHub could be set up.
Endpoints to manage Stream:
– GET /preview/json/organization/stream – get all available streams;
– GET /preview/json/organization/stream/{id} – get specific stream;
– POST /preview/json/organization/stream – create new stream;
– PUT /preview/json/organization/stream – update existing stream;
– PUT /preview/json/organization/stream/{id}/grant/rpp – grant stream with ResourcePermissionPolicies;
– PUT /preview/json/organization/stream/{id}/revoke/rpp – revoke ResourcePermissionPolicies from stream;
– GET /preview/json/organization/stream/{id}/policy – get stream connection policies.
Stream Json Schema:
Mandatory fields:
– organization – existing Organization id;
– resourcePermissionPolicies – at least one ResourcePermissionPolicy id with capability ‘Streaming’ should be provided.
2. Telemetry Flow Set Up
In order to consume telemetry data flow – Stream set up job should be completed. Job will create EventHubs Namespace for Organization if there is no Namespace created yet, EventHub and additional consumer groups if needed (‘$Default’ is created by default).
Endpoints to set up telemetry flow:
– POST /preview/json/organization/stream/{id}/job – initiate set up job;
– GET /preview/json/organization/{id}/stream/job/{jobId} – get initiated job status.
Available job operations:
– SET_UP – initiate resources creation;
– REMOVE – initiate EventHub remove;
– RESTART – initiate Telemetry flow restart;
– ADD_CONSUMER_GROUPS – add new additional consumer groups;
– REMOVE_CONSUMER_GROUPS – remove consumer groups.
3. Organization Streaming Resources Management:
Endpoints to manage Organization Streaming resources:
– GET /preview/json/organization/{id}/stream – get all stream resources assigned to organization;
– DELETE /preview/json/organization/{id}/stream/job – initiate job to drop all assigned to organization stream resources;
– GET /preview/json/organization/{id}/stream/job/{jobId} – get delete job status.
Actuator endpoint
New endpoint that gives possibility to retrieve latest observations for multiple actuators:
– POST /json/actuator/observations/latest
Breaking changes
None
Fixes and minor updated (internal links are added only for reference)
Improvements:
- PLAT-4198 – Change next_page_token to nextPageToken param for GET Geometry paged request, to make it consistent with other paged requests.
- PLAT-4209 – A new response status(Service Unavailable – 503 code) was added to Geometry batch create/update endpoints, when API experiencing issues with the database in which Geometry objects were saved.
