Share via


Time Series Database Connections - Create Or Update

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

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

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"
    }
  }
}
{
  "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

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

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"
  }
}
{
  "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

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

The type of identity that created the resource.

Value Description
Application
Key
ManagedIdentity
User

ErrorDefinition

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

Error response.

Name Type Description
error

ErrorDefinition

Error description

IdentityType

The type of managed identity used.

Value Description
SystemAssigned
UserAssigned

ManagedIdentityReference

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

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

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.

TimeSeriesDatabaseConnection

Describes a time series database connection resource.

Name Type Description
id

string

The resource identifier.

name

string

Extension resource name.

properties TimeSeriesDatabaseConnectionProperties:

AzureDataExplorerConnectionProperties

Properties of a specific time series database connection.

systemData

SystemData

Metadata pertaining to creation and last modification of the resource.

type

string

The resource type.

TimeSeriesDatabaseConnectionState

The provisioning state.

Value Description
Canceled
Deleted
Deleting
Disabled
Failed
Moving
Provisioning
Restoring
Succeeded
Suspending
Updating
Warning