Create Azure Time Series Insights Gen 1 resources using Azure Resource Manager templates

  • Article

Note

The Time Series Insights service will be retired on 7 July 2024. Consider migrating existing environments to alternative solutions as soon as possible. For more information on the deprecation and migration, visit our documentation.

Caution

This is a Gen1 article.

This article describes how to create and deploy Azure Time Series Insights resources using Azure Resource Manager templates, PowerShell, and the Azure Time Series Insights resource provider.

Azure Time Series Insights supports the following resources:

Resource Description
Environment An Azure Time Series Insights environment is a logical grouping of events that are read from event brokers, stored, and made available for query. For more information, read Plan your Azure Time Series Insights environment
Event Source An event source is a connection to an event broker from which Azure Time Series Insights reads and ingests events into the environment. Currently supported event sources are IoT Hub and Event Hub.
Reference Data Set Reference data sets provide metadata about the events in the environment. Metadata in the reference data sets will be joined with events during ingress. Reference data sets are defined as resources by their event key properties. The actual metadata that makes up the reference data set is uploaded or modified through data plane APIs.
Access Policy Access policies grant permissions to issue data queries, manipulate reference data in the environment, and share saved queries and perspectives associated with the environment. For more information, read Grant data access to an Azure Time Series Insights environment using Azure portal

A Resource Manager template is a JSON file that defines the infrastructure and configuration of resources in a resource group. The following documents describe template files in greater detail:

The timeseriesinsights-environment-with-eventhub quickstart template is published on GitHub. This template creates an Azure Time Series Insights environment, a child event source configured to consume events from an Event Hub, and access policies that grant access to the environment's data. If an existing Event Hub isn't specified, one will be created with the deployment.

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. See Install Azure PowerShell to get started. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Specify deployment template and parameters

The following procedure describes how to use PowerShell to deploy an Azure Resource Manager template that creates an Azure Time Series Insights environment, a child event source configured to consume events from an Event Hub, and access policies that grant access to the environment's data. If an existing Event Hub isn't specified, one will be created with the deployment.

  1. Install Azure PowerShell by following the instructions in Getting started with Azure PowerShell.

  2. Clone or copy the timeseriesinsights-environment-with-eventhub template from GitHub.

    • Create a parameters file

      To create a parameters file, copy the timeseriesinsights-environment-with-eventhub file.

      {
   "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
   "contentVersion": "1.0.0.0",
   "parameters": {
       "eventHubNamespaceName": {
           "value": "GEN-UNIQUE"
       },
       "eventHubName": {
           "value": "GEN-UNIQUE"
       },
       "consumerGroupName": {
           "value": "GEN-UNIQUE"
       },
       "environmentName": {
         "value": "GEN-UNIQUE"
       },
       "eventSourceName": {
         "value": "GEN-UNIQUE"
       }
   }
}

    • Required Parameters

      Parameter Description
      eventHubNamespaceName The namespace of the source event hub.
      eventHubName The name of the source event hub.
      consumerGroupName The name of the consumer group that the Azure Time Series Insights service will use to read the data from the event hub. NOTE: To avoid resource contention, this consumer group must be dedicated to the Azure Time Series Insights service and not shared with other readers.
      environmentName The name of the environment. The name cannot include: <, >, %, &, :, \\, ?, /, and any control characters. All other characters are allowed.
      eventSourceName The name of the event source child resource. The name cannot include: <, >, %, &, :, \\, ?, /, and any control characters. All other characters are allowed.

    • Optional Parameters

      Parameter Description
      existingEventHubResourceId An optional resource ID of an existing Event Hub that will be connected to the Azure Time Series Insights environment through the event source. NOTE: The user deploying the template must have privileges to perform the listkeys operation on the Event Hub. If no value is passed, a new event hub will be created by the template.
      environmentDisplayName An optional friendly name to show in tooling or user interfaces instead of the environment name.
      environmentSkuName The name of the sku. For more information, read the Azure Time Series Insights Pricing page.
      environmentSkuCapacity The unit capacity of the Sku. For more information, read the Azure Time Series Insights Pricing page.
      environmentDataRetentionTime The minimum timespan the environment's events will be available for query. The value must be specified in the ISO 8601 format, for example P30D for a retention policy of 30 days.
      eventSourceDisplayName An optional friendly name to show in tooling or user interfaces instead of the event source name.
      eventSourceTimestampPropertyName The event property that will be used as the event source's timestamp. If a value isn't specified for timestampPropertyName, or if null or empty-string is specified, the event creation time will be used.
      eventSourceKeyName The name of the shared access key that the Azure Time Series Insights service will use to connect to the event hub.
      accessPolicyReaderObjectIds A list of object IDs of the users or applications in Microsoft Entra ID that should have Reader access to the environment. The service principal objectId can be obtained by calling the Get-AzADUser or the Get-AzADServicePrincipal cmdlets. Creating an access policy for Microsoft Entra groups is not yet supported.
      accessPolicyContributorObjectIds A list of object IDs of the users or applications in Microsoft Entra ID that should have Contributor access to the environment. The service principal objectId can be obtained by calling the Get-AzADUser or the Get-AzADServicePrincipal cmdlets. Creating an access policy for Microsoft Entra groups is not yet supported.

    • As an example, the following parameters file would be used to create an environment and an event source that reads events from an existing event hub. It also creates two access policies that grant Contributor access to the environment.

      {
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "eventHubNamespaceName": {
            "value": "tsiTemplateTestNamespace"
        },
        "eventHubName": {
            "value": "tsiTemplateTestEventHub"
        },
        "consumerGroupName": {
            "value": "tsiTemplateTestConsumerGroup"
        },
        "environmentName": {
            "value": "tsiTemplateTestEnvironment"
        },
        "eventSourceName": {
            "value": "tsiTemplateTestEventSource"
        },
        "existingEventHubResourceId": {
            "value": "/subscriptions/{yourSubscription}/resourceGroups/MyDemoRG/providers/Microsoft.EventHub/namespaces/tsiTemplateTestNamespace/eventhubs/tsiTemplateTestEventHub"
        },
        "accessPolicyContributorObjectIds": {
            "value": [
                "AGUID001-0000-0000-0000-000000000000",
                "AGUID002-0000-0000-0000-000000000000"
            ]
        }
    }
}

    • For more information, read the Parameters article.

Deploy the quickstart template locally using PowerShell

Important

The command-line operations displayed below describe the Az PowerShell module.

  1. In PowerShell, log in to your Azure account.

    • From a PowerShell prompt, run the following command:

      Connect-AzAccount -Environment AzureChinaCloud

    • You are prompted to log on to your Azure account. After logging on, run the following command to view your available subscriptions:

      Get-AzSubscription

    • This command returns a list of available Azure subscriptions. Choose a subscription for the current session by running the following command. Replace <YourSubscriptionId> with the GUID for the Azure subscription you want to use:

      Set-AzContext -SubscriptionID <YourSubscriptionId>

  2. Create a new resource group if one does not exist.

    • If you do not have an existing resource group, create a new resource group with the New-AzResourceGroup command. Provide the name of the resource group and location you want to use. For example:

      New-AzResourceGroup -Name MyDemoRG -Location "China East 2"

    • If successful, a summary of the new resource group is displayed.

      ResourceGroupName : MyDemoRG
Location          : chinaeast2
ProvisioningState : Succeeded
Tags              :
ResourceId        : /subscriptions/<GUID>/resourceGroups/MyDemoRG

  3. Test the deployment.

    • Validate your deployment by running the Test-AzResourceGroupDeployment cmdlet. When testing the deployment, provide parameters exactly as you would when executing the deployment.

      Test-AzResourceGroupDeployment -ResourceGroupName MyDemoRG -TemplateFile <path to template file>\azuredeploy.json -TemplateParameterFile <path to parameters file>\azuredeploy.parameters.json

  4. Create the deployment

    • To create the new deployment, run the New-AzResourceGroupDeployment cmdlet, and provide the necessary parameters when prompted. The parameters include a name for your deployment, the name of your resource group, and the path or URL to the template file. If the Mode parameter is not specified, the default value of Incremental is used. For more information, read Incremental and complete deployments.

    • The following command prompts you for the five required parameters in the PowerShell window:

      New-AzResourceGroupDeployment -Name MyDemoDeployment -ResourceGroupName MyDemoRG -TemplateFile <path to template file>\azuredeploy.json

    • To specify a parameters file instead, use the following command:

      New-AzResourceGroupDeployment -Name MyDemoDeployment -ResourceGroupName MyDemoRG -TemplateFile <path to template file>\azuredeploy.json -TemplateParameterFile <path to parameters file>\azuredeploy.parameters.json

    • You can also use inline parameters when you run the deployment cmdlet. The command is as follows:

      New-AzResourceGroupDeployment -Name MyDemoDeployment -ResourceGroupName MyDemoRG -TemplateFile <path to template file>\azuredeploy.json -parameterName "parameterValue"

    • To run a complete deployment, set the Mode parameter to Complete:

      New-AzResourceGroupDeployment -Name MyDemoDeployment -Mode Complete -ResourceGroupName MyDemoRG -TemplateFile <path to template file>\azuredeploy.json

  5. Verify the deployment

    • If the resources are deployed successfully, a summary of the deployment is displayed in the PowerShell window:

       DeploymentName          : MyDemoDeployment
 ResourceGroupName       : MyDemoRG
 ProvisioningState       : Succeeded
 Timestamp               : 10/11/2019 3:20:37 AM
 Mode                    : Incremental
 TemplateLink            :
 Parameters              :
                           Name                                Type                       Value
                           ==================================  =========================  ==========
                           eventHubNewOrExisting               String                     new
                           eventHubResourceGroup               String                     MyDemoRG
                           eventHubNamespaceName               String                     tsiquickstartns
                           eventHubName                        String                     tsiquickstarteh
                           consumerGroupName                   String                     tsiquickstart
                           environmentName                     String                     tsiquickstart
                           environmentDisplayName              String                     tsiquickstart
                           environmentSkuName                  String                     S1
                           environmentSkuCapacity              Int                        1
                           environmentDataRetentionTime        String                     P30D
                           eventSourceName                     String                     tsiquickstart
                           eventSourceDisplayName              String                     tsiquickstart
                           eventSourceTimestampPropertyName    String
                           eventSourceKeyName                  String                     manage
                           accessPolicyReaderObjectIds         Array                      []
                           accessPolicyContributorObjectIds    Array                      []
                           location                            String                     chinaeast2

 Outputs                 :
                            Name              Type                       Value
                            ================  =========================  ==========
                            dataAccessFQDN    String
                            11aa1aa1-a1aa-1a1a-a11a-aa111a111a11.env.timeseries.azure.com

 DeploymentDebugLogLevel :

  6. Deploy the quickstart template through the Azure portal

    • The quickstart template's home page on GitHub also includes a Deploy to Azure button. Clicking it opens a Custom Deployment page in the Azure portal. From this page, you can enter or select values for each of the parameters from the required parameters or optional parameters tables. After filling out the settings, clicking the Purchase button will initiate the template deployment.

Deploy to Azure Button

Next steps