Time Series Database Connections - Create Or Update

Service:: Reference

API Version:: 2023-01-31

Create or update a time series database connection.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DigitalTwins/digitalTwinsInstances/{resourceName}/timeSeriesDatabaseConnections/{timeSeriesDatabaseConnectionName}?api-version=2023-01-31

URI Parameters

Name	In	Required	Type	Description
resourceGroupName	path	True	string	The name of the resource group that contains the DigitalTwinsInstance.
resourceName	path	True	string	The name of the DigitalTwinsInstance.
subscriptionId	path	True	string	The subscription identifier.
timeSeriesDatabaseConnectionName	path	True	string	Name of time series database connection.
api-version	query	True	string	Version of the DigitalTwinsInstance Management API.

Request Body

Name	Type	Description
properties	TimeSeriesDatabaseConnectionProperties: AzureDataExplorerConnectionProperties	Properties of a specific time series database connection.

Responses

Name	Type	Description
200 OK	TimeSeriesDatabaseConnection	This is returned as a response to the status polling request for the create or update operation. The body contains the resource representation that indicates a transitional provisioning state.
201 Created	TimeSeriesDatabaseConnection	Created - Put request accepted; the operation will complete asynchronously.
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

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

Create or replace a time series database connection for a DigitalTwins instance with user assigned identity.

Create or replace a time series database connection for a DigitalTwins instance.

Create or replace a time series database connection for a DigitalTwins instance with user assigned identity.

Sample request

HTTP

PUT https://management.azure.com/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourceGroups/resRg/providers/Microsoft.DigitalTwins/digitalTwinsInstances/myDigitalTwinsService/timeSeriesDatabaseConnections/myConnection?api-version=2023-01-31

{
  "properties": {
    "connectionType": "AzureDataExplorer",
    "adxEndpointUri": "https://mycluster.kusto.windows.net",
    "adxResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.Kusto/clusters/mycluster",
    "adxDatabaseName": "myDatabase",
    "adxTableName": "myTable",
    "eventHubEndpointUri": "sb://myeh.servicebus.windows.net/",
    "eventHubNamespaceResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.EventHub/namespaces/myeh",
    "eventHubEntityPath": "myeh",
    "identity": {
      "type": "UserAssigned",
      "userAssignedIdentity": "/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourceGroups/testrg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testidentity"
    }
  }
}

Sample response

Status code:: 201

azure-asyncoperation: https://management.azure.com/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/providers/Microsoft.DigitalTwins/locations/westus2/operationStatuses/12345678-1234-1234-123456789012
location: https://management.azure.com/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/providers/Microsoft.DigitalTwins/locations/westus2/operationResults/12345678-1234-1234-123456789012
retry-after: 10

{
  "id": "/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourcegroups/resRg/providers/Microsoft.DigitalTwins/digitalTwinsInstances/myDigitalTwinsService/timeSeriesDatabaseConnections/myConnection",
  "type": "Microsoft.DigitalTwins/digitalTwinsInstances/timeSeriesDatabaseConnections",
  "name": "myConnection",
  "properties": {
    "connectionType": "AzureDataExplorer",
    "provisioningState": "Provisioning",
    "adxEndpointUri": "https://mycluster.kusto.windows.net",
    "adxResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.Kusto/clusters/mycluster",
    "adxDatabaseName": "myDatabase",
    "adxTableName": "myTable",
    "eventHubEndpointUri": "sb://myeh.servicebus.windows.net/",
    "eventHubNamespaceResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.EventHub/namespaces/myeh",
    "eventHubEntityPath": "myeh",
    "eventHubConsumerGroup": "$Default",
    "recordPropertyAndItemRemovals": "false",
    "identity": {
      "type": "UserAssigned",
      "userAssignedIdentity": "/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourceGroups/testrg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testidentity"
    }
  }
}

Status code:: 200

{
  "id": "/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourcegroups/resRg/providers/Microsoft.DigitalTwins/digitalTwinsInstances/myDigitalTwinsService/timeSeriesDatabaseConnections/myConnection",
  "type": "Microsoft.DigitalTwins/digitalTwinsInstances/timeSeriesDatabaseConnections",
  "name": "myConnection",
  "properties": {
    "connectionType": "AzureDataExplorer",
    "provisioningState": "Succeeded",
    "adxEndpointUri": "https://mycluster.kusto.windows.net",
    "adxResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.Kusto/clusters/mycluster",
    "adxDatabaseName": "myDatabase",
    "adxTableName": "myTable",
    "eventHubEndpointUri": "sb://myeh.servicebus.windows.net/",
    "eventHubEntityPath": "myeh",
    "eventHubConsumerGroup": "$Default",
    "recordPropertyAndItemRemovals": "false",
    "eventHubNamespaceResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.EventHub/namespaces/myeh",
    "identity": {
      "type": "UserAssigned",
      "userAssignedIdentity": "/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourceGroups/testrg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testidentity"
    }
  }
}

Create or replace a time series database connection for a DigitalTwins instance.

Sample request

HTTP

PUT https://management.azure.com/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourceGroups/resRg/providers/Microsoft.DigitalTwins/digitalTwinsInstances/myDigitalTwinsService/timeSeriesDatabaseConnections/myConnection?api-version=2023-01-31

{
  "properties": {
    "connectionType": "AzureDataExplorer",
    "adxEndpointUri": "https://mycluster.kusto.windows.net",
    "adxResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.Kusto/clusters/mycluster",
    "adxDatabaseName": "myDatabase",
    "adxTableName": "myPropertyUpdatesTable",
    "adxTwinLifecycleEventsTableName": "myTwinLifecycleEventsTable",
    "adxRelationshipLifecycleEventsTableName": "myRelationshipLifecycleEventsTable",
    "eventHubEndpointUri": "sb://myeh.servicebus.windows.net/",
    "eventHubNamespaceResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.EventHub/namespaces/myeh",
    "eventHubEntityPath": "myeh",
    "recordPropertyAndItemRemovals": "true"
  }
}

Sample response

Status code:: 201

azure-asyncoperation: https://management.azure.com/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/providers/Microsoft.DigitalTwins/locations/westus2/operationStatuses/12345678-1234-1234-123456789012
location: https://management.azure.com/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/providers/Microsoft.DigitalTwins/locations/westus2/operationResults/12345678-1234-1234-123456789012
retry-after: 10

{
  "id": "/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourcegroups/resRg/providers/Microsoft.DigitalTwins/digitalTwinsInstances/myDigitalTwinsService/timeSeriesDatabaseConnections/myConnection",
  "type": "Microsoft.DigitalTwins/digitalTwinsInstances/timeSeriesDatabaseConnections",
  "name": "myConnection",
  "properties": {
    "connectionType": "AzureDataExplorer",
    "provisioningState": "Provisioning",
    "adxEndpointUri": "https://mycluster.kusto.windows.net",
    "adxResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.Kusto/clusters/mycluster",
    "adxDatabaseName": "myDatabase",
    "adxTableName": "myPropertyUpdatesTable",
    "adxTwinLifecycleEventsTableName": "myTwinLifecycleEventsTable",
    "adxRelationshipLifecycleEventsTableName": "myRelationshipLifecycleEventsTable",
    "eventHubEndpointUri": "sb://myeh.servicebus.windows.net/",
    "eventHubNamespaceResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.EventHub/namespaces/myeh",
    "eventHubEntityPath": "myeh",
    "eventHubConsumerGroup": "$Default",
    "recordPropertyAndItemRemovals": "true"
  }
}

Status code:: 200

{
  "id": "/subscriptions/50016170-c839-41ba-a724-51e9df440b9e/resourcegroups/resRg/providers/Microsoft.DigitalTwins/digitalTwinsInstances/myDigitalTwinsService/timeSeriesDatabaseConnections/myConnection",
  "type": "Microsoft.DigitalTwins/digitalTwinsInstances/timeSeriesDatabaseConnections",
  "name": "myConnection",
  "properties": {
    "connectionType": "AzureDataExplorer",
    "provisioningState": "Succeeded",
    "adxEndpointUri": "https://mycluster.kusto.windows.net",
    "adxResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.Kusto/clusters/mycluster",
    "adxDatabaseName": "myDatabase",
    "adxTableName": "myPropertyUpdatesTable",
    "adxTwinLifecycleEventsTableName": "myTwinLifecycleEventsTable",
    "adxRelationshipLifecycleEventsTableName": "myRelationshipLifecycleEventsTable",
    "eventHubEndpointUri": "sb://myeh.servicebus.windows.net/",
    "eventHubNamespaceResourceId": "/subscriptions/c493073e-2460-45ba-a403-f3e0df1e9feg/resourceGroups/testrg/providers/Microsoft.EventHub/namespaces/myeh",
    "eventHubEntityPath": "myeh",
    "eventHubConsumerGroup": "$Default",
    "recordPropertyAndItemRemovals": "true"
  }
}

Definitions

Name	Description
AzureDataExplorerConnectionProperties	Properties of a time series database connection to Azure Data Explorer with data being sent via an EventHub.
createdByType	The type of identity that created the resource.
ErrorDefinition	Error definition.
ErrorResponse	Error response.
IdentityType	The type of managed identity used.
ManagedIdentityReference	The properties of the Managed Identity.
recordPropertyAndItemRemovals	Specifies whether or not to record twin / relationship property and item removals, including removals of indexed or keyed values (such as map entries, array elements, etc.). This feature is de-activated unless explicitly set to 'true'. Setting this property to 'true' will generate an additional column in the property events table in ADX.
SystemData	Metadata pertaining to creation and last modification of the resource.
TimeSeriesDatabaseConnection	Describes a time series database connection resource.
TimeSeriesDatabaseConnectionState	The provisioning state.

AzureDataExplorerConnectionProperties

Object

Properties of a time series database connection to Azure Data Explorer with data being sent via an EventHub.

Name	Type	Default value	Description
adxDatabaseName	string		The name of the Azure Data Explorer database.
adxEndpointUri	string		The URI of the Azure Data Explorer endpoint.
adxRelationshipLifecycleEventsTableName	string		The name of the Azure Data Explorer table used for recording relationship lifecycle events. The table will not be created if this property is left unspecified.
adxResourceId	string		The resource ID of the Azure Data Explorer cluster.
adxTableName	string	AdtPropertyEvents	The name of the Azure Data Explorer table used for storing updates to properties of twins and relationships. Defaults to AdtPropertyEvents.
adxTwinLifecycleEventsTableName	string		The name of the Azure Data Explorer table used for recording twin lifecycle events. The table will not be created if this property is left unspecified.
connectionType	string: AzureDataExplorer		The type of time series connection resource.
eventHubConsumerGroup	string	$Default	The EventHub consumer group to use when ADX reads from EventHub. Defaults to $Default.
eventHubEndpointUri	string		The URL of the EventHub namespace for identity-based authentication. It must include the protocol sb://
eventHubEntityPath	string		The EventHub name in the EventHub namespace for identity-based authentication.
eventHubNamespaceResourceId	string		The resource ID of the EventHub namespace.
identity	ManagedIdentityReference		Managed identity properties for the time series database connection resource.
provisioningState	TimeSeriesDatabaseConnectionState		The provisioning state.
recordPropertyAndItemRemovals	recordPropertyAndItemRemovals	false	Specifies whether or not to record twin / relationship property and item removals, including removals of indexed or keyed values (such as map entries, array elements, etc.). This feature is de-activated unless explicitly set to 'true'. Setting this property to 'true' will generate an additional column in the property events table in ADX.

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
Application
Key
ManagedIdentity
User

ErrorDefinition

Object

Error definition.

Name	Type	Description
code	string	Service specific error code which serves as the substatus for the HTTP error code.
details	ErrorDefinition[]	Internal error details.
message	string	Description of the error.

ErrorResponse

Object

Error response.

Name	Type	Description
error	ErrorDefinition	Error description

IdentityType

Enumeration

The type of managed identity used.

Value	Description
SystemAssigned
UserAssigned

ManagedIdentityReference

Object

The properties of the Managed Identity.

Name	Type	Description
type	IdentityType	The type of managed identity used.
userAssignedIdentity	string	The user identity ARM resource id if the managed identity type is 'UserAssigned'.

recordPropertyAndItemRemovals

Enumeration

Specifies whether or not to record twin / relationship property and item removals, including removals of indexed or keyed values (such as map entries, array elements, etc.). This feature is de-activated unless explicitly set to 'true'. Setting this property to 'true' will generate an additional column in the property events table in ADX.

Value	Description
false
true

SystemData

Object

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.