Time Series Instances - Execute Batch
Executes a batch get, create, update, delete operation on multiple time series instances.
POST https://{environmentFqdn}/timeseries/instances/$batch?api-version=2020-07-31
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
environment
|
path | True |
string |
Per environment FQDN, for example 10000000-0000-0000-0000-100000000109.env.timeseries.azure.com. You can obtain this domain name from the response of the Get Environments API, Azure portal, or Azure Resource Manager. |
api-version
|
query | True |
string |
Version of the API to be used with the client request. Currently supported version is "2020-07-31". |
Request Header
Name | Required | Type | Description |
---|---|---|---|
x-ms-client-request-id |
string |
Optional client request ID. Service records this value. Allows the service to trace operation across services, and allows the customer to contact support regarding a particular request. |
|
x-ms-client-session-id |
string |
Optional client session ID. Service records this value. Allows the service to trace a group of related operations across services, and allows the customer to contact support regarding a particular group of requests. |
Request Body
Name | Type | Description |
---|---|---|
delete |
Time series instances to be deleted. Time series ID or name may be specified. |
|
get |
Time series IDs or names of time series instances to return. |
|
put |
Time series instances to be created or updated. |
|
update |
Time series instance to be updated. If instance does not exist, an error is returned. |
Responses
Name | Type | Description |
---|---|---|
200 OK |
Successful operation. Headers x-ms-request-id: string |
|
Other Status Codes |
Unexpected error. Headers x-ms-request-id: string |
Security
azure_auth
Azure Active Directory OAuth2 Flow
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Name | Description |
---|---|
user_impersonation | impersonate your user account |
Examples
Instances |
Instances |
Instances |
Instances |
Instances |
Instances |
InstancesBatchDeleteByIds
Sample request
POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31
{
"delete": {
"timeSeriesIds": [
[
"2da181d7-8346-4cf2-bd94-a17742237429",
"T1"
],
[
"18672e3d-2beb-4007-9846-042b09ef3c72",
"T2"
]
]
}
}
Sample response
{
"delete": [
null,
{
"code": "InvalidInput",
"message": "Time series instance with ID '[\"18672e3d-2beb-4007-9846-042b09ef3c72\", \"T2\"]' cannot be deleted. There are already ingested events associated with this time series ID.",
"innerError": {
"code": "CannotDeleteInstance"
}
}
]
}
InstancesBatchDeleteByNames
Sample request
POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31
{
"delete": {
"names": [
"F2W6.GF",
"F1W7.GS1"
]
}
}
Sample response
{
"delete": [
null,
{
"code": "InvalidInput",
"message": "Time series instance with ID '[\"18672e3d-2beb-4007-9846-042b09ef3c72\", \"T2\"]' cannot be deleted. There are already ingested events associated with this time series ID.",
"innerError": {
"code": "CannotDeleteInstance"
}
}
]
}
InstancesBatchGetByIds
Sample request
POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31
{
"get": {
"timeSeriesIds": [
[
"006dfc2d-0324-4937-998c-d16f3b4f1952",
"T1"
]
]
}
}
Sample response
{
"get": [
{
"instance": {
"typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
"name": "F1W7.GS1",
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952",
"T1"
],
"description": "ContosoFarm1W7_GenSpeed1",
"hierarchyIds": [
"33d72529-dd73-4c31-93d8-ae4e6cb5605d"
],
"instanceFields": {
"Name": "GeneratorSpeed",
"Plant": "Contoso Plant 1",
"Unit": "W7",
"System": "Generator System",
"Status": false,
"Version": 1.3,
"Code": 28
}
}
}
]
}
InstancesBatchGetByNames
Sample request
POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31
{
"get": {
"names": [
"F1W7.GS1"
]
}
}
Sample response
{
"get": [
{
"instance": {
"typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
"name": "F1W7.GS1",
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952",
"T1"
],
"description": "ContosoFarm1W7_GenSpeed1",
"hierarchyIds": [
"33d72529-dd73-4c31-93d8-ae4e6cb5605d"
],
"instanceFields": {
"Name": "GeneratorSpeed",
"Plant": "Contoso Plant 1",
"Unit": "W7",
"System": "Generator System",
"Status": false,
"Version": 1.3,
"Code": 28
}
}
}
]
}
InstancesBatchPut
Sample request
POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31
{
"put": [
{
"typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
"name": "F1W7.GS1",
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952",
"T1"
],
"description": "ContosoFarm1W7_GenSpeed1",
"hierarchyIds": [
"33d72529-dd73-4c31-93d8-ae4e6cb5605d"
],
"instanceFields": {
"Name": "GeneratorSpeed",
"Plant": "Contoso Plant 1",
"Unit": "W7",
"System": "Generator System",
"Status": false,
"Version": 1.3,
"Code": 28
}
}
]
}
Sample response
{
"put": [
{
"error": null
}
]
}
InstancesBatchUpdate
Sample request
POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/instances/$batch?api-version=2020-07-31
{
"update": [
{
"typeId": "9b84e946-7b36-4aa0-9d26-71bf48cb2aff",
"name": "F1W7.GS1",
"timeSeriesId": [
"006dfc2d-0324-4937-998c-d16f3b4f1952",
"T1"
],
"description": "ContosoFarm1W7_GenSpeed1",
"hierarchyIds": [
"33d72529-dd73-4c31-93d8-ae4e6cb5605d"
],
"instanceFields": {
"Name": "GeneratorSpeed",
"Plant": "Contoso Plant 1",
"Unit": "W7",
"System": "Generator System",
"Status": false,
"Version": 1.3,
"Code": 28
}
}
]
}
Sample response
{
"update": [
{
"error": null
}
]
}
Definitions
Name | Description |
---|---|
Instance |
Result of a batch operation on a particular time series instance. Instance object is set when operation is successful (except put operation) and error object is set when operation is unsuccessful. |
Instances |
Request to perform a single operation on a batch of instances. Exactly one of "get", "put", "update" or "delete" must be set. |
Instances |
Response of a single operation on a batch of instances. Only one of "get", "put", "update" or "delete" will be set based on the request. |
Instances |
Request to get or delete instances by time series IDs or time series names. Exactly one of "timeSeriesIds" or "names" must be set. |
Time |
Time series instances are the time series themselves. In most cases, the deviceId or assetId is the unique identifier of the asset in the environment. Instances have descriptive information associated with them called instance fields. At a minimum, instance fields include hierarchy information. They can also include useful, descriptive data like the manufacturer, operator, or the last service date. |
Tsi |
Information about an API error. |
Tsi |
A particular API error with an error code and a message. |
Tsi |
Additional error information. |
InstanceOrError
Result of a batch operation on a particular time series instance. Instance object is set when operation is successful (except put operation) and error object is set when operation is unsuccessful.
Name | Type | Description |
---|---|---|
error |
Error object - set when the operation is unsuccessful. |
|
instance |
Time series instance object - set when the operation is successful (except put operation). |
InstancesBatchRequest
Request to perform a single operation on a batch of instances. Exactly one of "get", "put", "update" or "delete" must be set.
Name | Type | Description |
---|---|---|
delete |
Time series instances to be deleted. Time series ID or name may be specified. |
|
get |
Time series IDs or names of time series instances to return. |
|
put |
Time series instances to be created or updated. |
|
update |
Time series instance to be updated. If instance does not exist, an error is returned. |
InstancesBatchResponse
Response of a single operation on a batch of instances. Only one of "get", "put", "update" or "delete" will be set based on the request.
Name | Type | Description |
---|---|---|
delete |
List of error objects corresponding by position to the "delete" array in the request. Null means the instance has been deleted, or did not exist. Error object is set when operation is unsuccessful (e.g. when there are events associated with this time series instance). |
|
get |
List of instance or error objects corresponding by position to the "get" array in the request. Instance object is set when operation is successful and error object is set when operation is unsuccessful. |
|
put |
List of error objects corresponding by position to the "put" array in the request. Error object is set when operation is unsuccessful. |
|
update |
List of error objects corresponding by position to the "update" array in the request. Instance object is set when operation is successful and error object is set when operation is unsuccessful. |
InstancesRequestBatchGetOrDelete
Request to get or delete instances by time series IDs or time series names. Exactly one of "timeSeriesIds" or "names" must be set.
Name | Type | Description |
---|---|---|
names |
string[] |
List of names of the time series instances to return or delete. |
timeSeriesIds |
Time |
List of time series IDs of the time series instances to return or delete. |
TimeSeriesInstance
Time series instances are the time series themselves. In most cases, the deviceId or assetId is the unique identifier of the asset in the environment. Instances have descriptive information associated with them called instance fields. At a minimum, instance fields include hierarchy information. They can also include useful, descriptive data like the manufacturer, operator, or the last service date.
Name | Type | Description |
---|---|---|
description |
string |
This optional field contains description about the instance. |
hierarchyIds |
string[] |
Set of time series hierarchy IDs that the instance belong to. May be null. |
instanceFields |
|
Set of key-value pairs that contain user-defined instance properties. It may be null. Supported property value types are: bool, string, long, double and it cannot be nested or null. |
name |
string |
Optional name of the instance which is unique in an environment. Names acts as a mutable alias or display name of the time series instance. Mutable, may be null. |
timeSeriesId |
Time |
Time Series ID that uniquely identifies the instance. It matches Time Series ID properties in an environment. Immutable, never null. |
typeId |
string |
This represents the type that this instance belongs to. Never null. |
TsiError
Information about an API error.
Name | Type | Description |
---|---|---|
error |
A particular API error with an error code and a message. |
TsiErrorBody
A particular API error with an error code and a message.
Name | Type | Description |
---|---|---|
code |
string |
Language-independent, human-readable string that defines a service-specific error code. This code serves as a more specific indicator for the HTTP error code specified in the response. Can be used to programmatically handle specific error cases. |
details |
Contains additional error information. May be null. |
|
innerError |
Contains more specific error that narrows down the cause. May be null. |
|
message |
string |
Human-readable, language-independent representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users. |
target |
string |
Target of the particular error (for example, the name of the property in error). May be null. |
TsiErrorDetails
Additional error information.
Name | Type | Description |
---|---|---|
code |
string |
Language-independent, human-readable string that defines a service-specific error code. This code serves as a more specific indicator for the HTTP error code specified in the response. Can be used to programmatically handle specific error cases. |
message |
string |
Human-readable, language-independent representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users. |