Share via

Time Series Types - Execute Batch

  • Reference
Service:
Time Series Insights
API Version:
2020-07-31

Executes a batch get, create, update, delete operation on multiple time series types.

POST https://{environmentFqdn}/timeseries/types/$batch?api-version=2020-07-31

URI Parameters

Name In Required Type Description
environmentFqdn
 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

TypesRequestBatchGetOrDelete

Definition of what time series types to delete.
get

TypesRequestBatchGetOrDelete

Definition of what time series types to return.
put

TimeSeriesType[]

Definition of what time series types to update or create.

Responses

Name Type Description
200 OK

TypesBatchResponse

Successful operation.

Headers

x-ms-request-id: string
Other Status Codes

TsiError

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

TypesBatchDeleteByIds
TypesBatchDeleteByNames
TypesBatchGetByIds
TypesBatchGetByNames
TypesBatchPut

TypesBatchDeleteByIds

Sample request

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/types/$batch?api-version=2020-07-31

{
  "delete": {
    "typeIds": [
      "9250f816-faed-44c4-88e6-630e5eefa38b"
    ]
  }
}

Sample response

Status code:
200 
{
  "delete": [
    null
  ]
}

TypesBatchDeleteByNames

Sample request

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/types/$batch?api-version=2020-07-31

{
  "delete": {
    "names": [
      "TemperatureSensor"
    ]
  }
}

Sample response

Status code:
200 
{
  "delete": [
    null
  ]
}

TypesBatchGetByIds

Sample request

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/types/$batch?api-version=2020-07-31

{
  "get": {
    "typeIds": [
      "1be09af9-f089-4d6b-9f0b-48018b5f7393",
      "c1cb7a33-ed9b-4cf1-9958-f3162fed8ee8"
    ],
    "names": null
  }
}

Sample response

Status code:
200 
{
  "get": [
    {
      "timeSeriesType": {
        "id": "1be09af9-f089-4d6b-9f0b-48018b5f7393",
        "name": "DefaultType",
        "description": "Default type",
        "variables": {
          "EventCount": {
            "kind": "aggregate",
            "filter": null,
            "aggregation": {
              "tsx": "count()"
            }
          }
        }
      },
      "error": null
    },
    {
      "timeSeriesType": {
        "id": "c1cb7a33-ed9b-4cf1-9958-f3162fed8ee8",
        "name": "TemperatureSensor",
        "description": "This is a temperature sensor.",
        "variables": {
          "AverageTemperature": {
            "kind": "numeric",
            "value": {
              "tsx": "$event.Temperature.Double"
            },
            "filter": null,
            "aggregation": {
              "tsx": "avg($value)"
            }
          }
        }
      },
      "error": null
    }
  ]
}

TypesBatchGetByNames

Sample request

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/types/$batch?api-version=2020-07-31

{
  "get": {
    "names": [
      "DefaultType",
      "TemperatureSensor"
    ]
  }
}

Sample response

Status code:
200 
{
  "get": [
    {
      "timeSeriesType": {
        "id": "1be09af9-f089-4d6b-9f0b-48018b5f7393",
        "name": "DefaultType",
        "description": "Default type",
        "variables": {
          "EventCount": {
            "kind": "aggregate",
            "filter": null,
            "aggregation": {
              "tsx": "count()"
            }
          }
        }
      },
      "error": null
    },
    {
      "timeSeriesType": {
        "id": "c1cb7a33-ed9b-4cf1-9958-f3162fed8ee8",
        "name": "TemperatureSensor",
        "description": "This is a temperature sensor.",
        "variables": {
          "AverageTemperature": {
            "kind": "numeric",
            "value": {
              "tsx": "$event.Temperature.Double"
            },
            "filter": null,
            "aggregation": {
              "tsx": "avg($value)"
            }
          }
        }
      },
      "error": null
    }
  ]
}

TypesBatchPut

Sample request

POST https://10000000-0000-0000-0000-100000000109.env.timeseries.azure.com/timeseries/types/$batch?api-version=2020-07-31

{
  "put": [
    {
      "id": "1be09af9-f089-4d6b-9f0b-48018b5f7393",
      "name": "DefaultType",
      "description": "My Default type",
      "variables": {
        "EventCount": {
          "kind": "aggregate",
          "filter": null,
          "aggregation": {
            "tsx": "count()"
          }
        }
      }
    },
    {
      "id": "c1cb7a33-ed9b-4cf1-9958-f3162fed8ee8",
      "name": "OutdoorTemperatureSensor",
      "description": "This is an outdoor temperature sensor.",
      "variables": {
        "AverageTemperature": {
          "kind": "numeric",
          "value": {
            "tsx": "$event.Temperature.Double"
          },
          "filter": {
            "tsx": "$event.Mode.String = 'outdoor'"
          },
          "aggregation": {
            "tsx": "avg($value)"
          }
        }
      }
    }
  ]
}

Sample response

Status code:
200 
{
  "put": [
    {
      "timeSeriesType": {
        "id": "1be09af9-f089-4d6b-9f0b-48018b5f7393",
        "name": "DefaultType",
        "description": "My Default type",
        "variables": {
          "EventCount": {
            "kind": "aggregate",
            "filter": null,
            "aggregation": {
              "tsx": "count()"
            }
          }
        }
      },
      "error": null
    },
    {
      "timeSeriesType": {
        "id": "c1cb7a33-ed9b-4cf1-9958-f3162fed8ee8",
        "name": "OutdoorTemperatureSensor",
        "description": "This is an outdoor temperature sensor.",
        "variables": {
          "AverageTemperature": {
            "kind": "numeric",
            "value": {
              "tsx": "$event.Temperature.Double"
            },
            "filter": {
              "tsx": "$event.Mode.String = 'outdoor'"
            },
            "aggregation": {
              "tsx": "avg($value)"
            }
          }
        }
      },
      "error": null
    }
  ]
}

Definitions

Name Description
AggregateVariable

Aggregate variable represents any aggregation calculation. Aggregate Variables does not support interpolation.
Boundary

The time range to the left and right of the search span to be used for Interpolation. This is helpful in scenarios where the data points are missing close to the start or end of the input search span. Can be null.
CategoricalVariable

Categorical variable represents signal that needs to be analyzed based on the count or duration of occurrence of limited set of defined values.
Interpolation

The interpolation operation to be performed on the raw data points. Currently, only sampling of interpolated time series is allowed. Allowed aggregate function - eg: left($value). Can be null if no interpolation needs to be applied.
InterpolationKind

The type of interpolation technique : "Linear" or "Step".
NumericVariable

Numeric variable represents a single continuous numeric signal that can be reconstructed using interpolation.
TimeSeriesAggregateCategory

Category used in categorical variables. A category is defined by 'label' and the 'values' that are assigned this label.
TimeSeriesDefaultCategory

Represents the default category.
TimeSeriesType

Time series type defines variables or formulas for doing computation on events associated with time series instances. Each time series instance is associated with exactly one type. A type can have one or more variables. For example, a time series instance might be of type Temperature Sensor, which consists of the variables avg temperature, min temperature, and max temperature.
TimeSeriesTypeOrError

Result of a batch operation on a particular time series type. Type object is set when operation is successful and error object is set when operation is unsuccessful.
TsiError

Information about an API error.
TsiErrorBody

A particular API error with an error code and a message.
TsiErrorDetails

Additional error information.
Tsx

Time series expression (TSX) written as a single string. Examples: "$event.Status.String='Good'", "avg($event.Temperature)". Refer to the documentation on how to write time series expressions.
TypesBatchRequest

Request to perform a single operation on a batch of time series types. Exactly one of "get", "put" or "delete" must be set.
TypesBatchResponse

Response of a single operation on a batch of time series types. Exactly one of "get", "put" or "delete" will be set.
TypesRequestBatchGetOrDelete

Request to get or delete time series types by IDs or type names. Exactly one of "typeIds" or "names" must be set.

AggregateVariable

Aggregate variable represents any aggregation calculation. Aggregate Variables does not support interpolation.

Name Type Description
aggregation

Tsx

Aggregation time series expression when kind is "aggregate" is used to represent the aggregation that needs to be performed directly using event properties like "$event.Temperature". For example, aggregation for calculating range of temperature changes can be written as: "max($event.Temperature)-min($event.Temperature)".
filter

Tsx

Filter over the events that restricts the number of events being considered for computation. Example: "$event.Status.String='Good'". Optional.
kind string:

aggregate

Allowed "kind" values are - "numeric" or "aggregate". While "numeric" allows you to specify value of the reconstructed signal and the expression to aggregate them, the "aggregate" kind lets you directly aggregate on the event properties without specifying value.

Boundary

The time range to the left and right of the search span to be used for Interpolation. This is helpful in scenarios where the data points are missing close to the start or end of the input search span. Can be null.

Name Type Description
span

string

CategoricalVariable

Categorical variable represents signal that needs to be analyzed based on the count or duration of occurrence of limited set of defined values.

Name Type Description
categories

TimeSeriesAggregateCategory[]

Category used in categorical variables. A category is defined by 'label' and the 'values' that are assigned this label.
defaultCategory

TimeSeriesDefaultCategory

Represents the default category.
filter

Tsx

Filter over the events that restricts the number of events being considered for computation. Example: "$event.Status.String='Good'". Optional.
interpolation

Interpolation

Categorical variable supports only 'step' interpolation.
kind string:

categorical

Allowed "kind" values are - "numeric" or "aggregate". While "numeric" allows you to specify value of the reconstructed signal and the expression to aggregate them, the "aggregate" kind lets you directly aggregate on the event properties without specifying value.
value

Tsx

Value time series expression is used to represent the value of the signal that is going to be categorized. It can evaluate to only 'String' or 'Long' type for categorical variables.

Interpolation

The interpolation operation to be performed on the raw data points. Currently, only sampling of interpolated time series is allowed. Allowed aggregate function - eg: left($value). Can be null if no interpolation needs to be applied.

Name Type Description
boundary

Boundary

The time range to the left and right of the search span to be used for Interpolation. This is helpful in scenarios where the data points are missing close to the start or end of the input search span. Can be null.
kind

InterpolationKind

The type of interpolation technique : "Linear" or "Step".

InterpolationKind

The type of interpolation technique : "Linear" or "Step".

Name Type Description
Linear

string

Step

string

NumericVariable

Numeric variable represents a single continuous numeric signal that can be reconstructed using interpolation.

Name Type Description
aggregation

Tsx

Aggregation time series expression when kind is "numeric" is used to represent the aggregation that needs to be performed on the $value expression. This requires $value to be specified and can only use $value inside the aggregate functions. For example, aggregation for calculating minimum of the $value is written as: "min($value)".
filter

Tsx

Filter over the events that restricts the number of events being considered for computation. Example: "$event.Status.String='Good'". Optional.
interpolation

Interpolation

The interpolation operation to be performed on the raw data points. Currently, only sampling of interpolated time series is allowed. Allowed aggregate function - eg: left($value). Can be null if no interpolation needs to be applied.
kind string:

numeric

Allowed "kind" values are - "numeric" or "aggregate". While "numeric" allows you to specify value of the reconstructed signal and the expression to aggregate them, the "aggregate" kind lets you directly aggregate on the event properties without specifying value.
value

Tsx

Value time series expression is used to represent the value of the signal that is going to be aggregated or interpolated. For example, temperature values from the event is represented like this: "$event.Temperature.Double".

TimeSeriesAggregateCategory

Category used in categorical variables. A category is defined by 'label' and the 'values' that are assigned this label.

Name Type Description
label

string

The name of the category which will be used in constructing the output variable names.
values

object[]

The list of values that a category maps to. Can be either a unique list of string or list of long.

TimeSeriesDefaultCategory

Represents the default category.

Name Type Description
label

string

The name of the default category which will be assigned to the values that does not match any of those that are defined in the 'categories'.

TimeSeriesType

Time series type defines variables or formulas for doing computation on events associated with time series instances. Each time series instance is associated with exactly one type. A type can have one or more variables. For example, a time series instance might be of type Temperature Sensor, which consists of the variables avg temperature, min temperature, and max temperature.

Name Type Description
description

string

Description of the type. May be null.
id

string

Case-sensitive unique type identifier that is immutable. Can be null on create or update requests, and then server generates the ID. Not null on get and delete operations.
name

string

User-given unique name for the type. Mutable, not null.
variables

object

Different variables associated with the type. Not empty, not null.

TimeSeriesTypeOrError

Result of a batch operation on a particular time series type. Type object is set when operation is successful and error object is set when operation is unsuccessful.

Name Type Description
error

TsiErrorBody

Error object - set when the operation is unsuccessful.
timeSeriesType

TimeSeriesType

Time series type object - set when the operation is successful.

TsiError

Information about an API error.

Name Type Description
error

TsiErrorBody

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

TsiErrorDetails[]

Contains additional error information. May be null.
innerError

TsiErrorBody

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.

Tsx

Time series expression (TSX) written as a single string. Examples: "$event.Status.String='Good'", "avg($event.Temperature)". Refer to the documentation on how to write time series expressions.

Name Type Description
tsx

string

Time series expression (TSX) written as a single string. Examples: "$event.Status.String='Good'", "avg($event.Temperature)". Refer to the documentation on how to write time series expressions.

TypesBatchRequest

Request to perform a single operation on a batch of time series types. Exactly one of "get", "put" or "delete" must be set.

Name Type Description
delete

TypesRequestBatchGetOrDelete

Definition of what time series types to delete.
get

TypesRequestBatchGetOrDelete

Definition of what time series types to return.
put

TimeSeriesType[]

Definition of what time series types to update or create.

TypesBatchResponse

Response of a single operation on a batch of time series types. Exactly one of "get", "put" or "delete" will be set.

Name Type Description
delete

TsiErrorBody[]

List of error objects corresponding by position to the "delete" array in the request - null when the operation is successful.
get

TimeSeriesTypeOrError[]

List of types or error objects corresponding by position to the "get" array in the request. Type object is set when operation is successful and error object is set when operation is unsuccessful.
put

TimeSeriesTypeOrError[]

List of types or error objects corresponding by position to the "put" array in the request. Type object is set when operation is successful and error object is set when operation is unsuccessful.

TypesRequestBatchGetOrDelete

Request to get or delete time series types by IDs or type names. Exactly one of "typeIds" or "names" must be set.

Name Type Description
names

string[]

List of names of time series types to return or delete.
typeIds

string[]

List of IDs of time series types to return or delete.