Environments - Create Or Update

Reference

Service:: Time Series Insights

API Version:: 2020-05-15

Create or update an environment in the specified subscription and resource group.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.TimeSeriesInsights/environments/{environmentName}?api-version=2020-05-15

URI Parameters

Name	In	Required	Type	Description
environmentName	path	True	string	Name of the environment Regex pattern: `^[-\w\._]+$`
resourceGroupName	path	True	string	Name of an Azure Resource group.
subscriptionId	path	True	string	Azure Subscription ID.
api-version	query	True	string	Version of the API to be used with the client request.

Request Body

The request body can be one of the following:

Name	Description
Gen1EnvironmentCreateOrUpdateParameters	Parameters supplied to the Create or Update Environment operation for a Gen1 environment.
Gen2EnvironmentCreateOrUpdateParameters	Parameters supplied to the Create or Update Environment operation for a Gen2 environment.

Gen1EnvironmentCreateOrUpdateParameters

Parameters supplied to the Create or Update Environment operation for a Gen1 environment.

Name	Required	Type	Description
kind	True	string: Gen1	The kind of the environment.
location	True	string	The location of the resource.
properties.dataRetentionTime	True	string	ISO8601 timespan specifying the minimum number of days the environment's events will be available for query.
sku	True	Sku	The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.
properties.partitionKeyProperties		TimeSeriesIdProperty[]	The list of event properties which will be used to partition data in the environment. Currently, only a single partition key property is supported.
properties.storageLimitExceededBehavior		StorageLimitExceededBehavior	The behavior the Time Series Insights service should take when the environment's capacity has been exceeded. If "PauseIngress" is specified, new events will not be read from the event source. If "PurgeOldData" is specified, new events will continue to be read and old events will be deleted from the environment. The default behavior is PurgeOldData.
tags		object	Key-value pairs of additional properties for the resource.

Gen2EnvironmentCreateOrUpdateParameters

Parameters supplied to the Create or Update Environment operation for a Gen2 environment.

Name	Required	Type	Description
kind	True	string: Gen2	The kind of the environment.
location	True	string	The location of the resource.
properties.storageConfiguration	True	Gen2StorageConfigurationInput	The storage configuration provides the connection details that allows the Time Series Insights service to connect to the customer storage account that is used to store the environment's data.
properties.timeSeriesIdProperties	True	TimeSeriesIdProperty[]	The list of event properties which will be used to define the environment's time series id.
sku	True	Sku	The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.
properties.warmStoreConfiguration		WarmStoreConfigurationProperties	The warm store configuration provides the details to create a warm store cache that will retain a copy of the environment's data available for faster query.
tags		object	Key-value pairs of additional properties for the resource.

Responses

Name	Type	Description
200 OK	EnvironmentResource: Gen1EnvironmentResource Gen2EnvironmentResource	The existing environment definition was successfully updated.
201 Created	EnvironmentResource: Gen1EnvironmentResource Gen2EnvironmentResource	The environment create request was accepted. Environment provisioning is an asynchronous operation. You can periodically get your environment definition and monitor progress via the provisioningState property.
404 Not Found		The subscription or resource group could not be found.
Other Status Codes	CloudError	HTTP 400 (Bad Request): The given environment request body is invalid; See the error code and message in the response for details.

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

EnvironmentsCreate

Sample Request

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.TimeSeriesInsights/environments/env1?api-version=2020-05-15

{
  "location": "West US",
  "kind": "Gen1",
  "sku": {
    "name": "S1",
    "capacity": 1
  },
  "properties": {
    "dataRetentionTime": "P31D",
    "partitionKeyProperties": [
      {
        "name": "DeviceId1",
        "type": "String"
      }
    ]
  }
}

import com.azure.resourcemanager.timeseriesinsights.models.Gen1EnvironmentCreateOrUpdateParameters;
import com.azure.resourcemanager.timeseriesinsights.models.PropertyType;
import com.azure.resourcemanager.timeseriesinsights.models.Sku;
import com.azure.resourcemanager.timeseriesinsights.models.SkuName;
import com.azure.resourcemanager.timeseriesinsights.models.TimeSeriesIdProperty;
import java.time.Duration;
import java.util.Arrays;

/** Samples for Environments CreateOrUpdate. */
public final class Main {
    /*
     * x-ms-original-file: specification/timeseriesinsights/resource-manager/Microsoft.TimeSeriesInsights/stable/2020-05-15/examples/EnvironmentsCreate.json
     */
    /**
     * Sample code: EnvironmentsCreate.
     *
     * @param manager Entry point to TimeSeriesInsightsManager.
     */
    public static void environmentsCreate(
        com.azure.resourcemanager.timeseriesinsights.TimeSeriesInsightsManager manager) {
        manager
            .environments()
            .createOrUpdate(
                "rg1",
                "env1",
                new Gen1EnvironmentCreateOrUpdateParameters()
                    .withLocation("West US")
                    .withSku(new Sku().withName(SkuName.S1).withCapacity(1))
                    .withDataRetentionTime(Duration.parse("P31D"))
                    .withPartitionKeyProperties(
                        Arrays.asList(new TimeSeriesIdProperty().withName("DeviceId1").withType(PropertyType.STRING))),
                com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

package armtimeseriesinsights_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/timeseriesinsights/armtimeseriesinsights"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/163e27c0ca7570bc39e00a46f255740d9b3ba3cb/specification/timeseriesinsights/resource-manager/Microsoft.TimeSeriesInsights/stable/2020-05-15/examples/EnvironmentsCreate.json
func ExampleEnvironmentsClient_BeginCreateOrUpdate() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armtimeseriesinsights.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	poller, err := clientFactory.NewEnvironmentsClient().BeginCreateOrUpdate(ctx, "rg1", "env1", &armtimeseriesinsights.Gen1EnvironmentCreateOrUpdateParameters{
		Location: to.Ptr("West US"),
		Kind:     to.Ptr(armtimeseriesinsights.EnvironmentKindGen1),
		SKU: &armtimeseriesinsights.SKU{
			Name:     to.Ptr(armtimeseriesinsights.SKUNameS1),
			Capacity: to.Ptr[int32](1),
		},
		Properties: &armtimeseriesinsights.Gen1EnvironmentCreationProperties{
			DataRetentionTime: to.Ptr("P31D"),
			PartitionKeyProperties: []*armtimeseriesinsights.TimeSeriesIDProperty{
				{
					Name: to.Ptr("DeviceId1"),
					Type: to.Ptr(armtimeseriesinsights.PropertyTypeString),
				}},
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	res, err := poller.PollUntilDone(ctx, nil)
	if err != nil {
		log.Fatalf("failed to pull the result: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res = armtimeseriesinsights.EnvironmentsClientCreateOrUpdateResponse{
	// 	                            EnvironmentResourceClassification: &armtimeseriesinsights.Gen1EnvironmentResource{
	// 		Name: to.Ptr("env1"),
	// 		Type: to.Ptr("Microsoft.TimeSeriesInsights/Environments"),
	// 		ID: to.Ptr("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.TimeSeriesInsights/Environments/env1"),
	// 		Location: to.Ptr("West US"),
	// 		Tags: map[string]*string{
	// 		},
	// 		Kind: to.Ptr(armtimeseriesinsights.EnvironmentResourceKindGen1),
	// 		SKU: &armtimeseriesinsights.SKU{
	// 			Name: to.Ptr(armtimeseriesinsights.SKUNameS1),
	// 			Capacity: to.Ptr[int32](1),
	// 		},
	// 		Properties: &armtimeseriesinsights.Gen1EnvironmentResourceProperties{
	// 			CreationTime: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2017-04-18T19:20:33.228Z"); return t}()),
	// 			ProvisioningState: to.Ptr(armtimeseriesinsights.ProvisioningStateSucceeded),
	// 			DataRetentionTime: to.Ptr("P31D"),
	// 		},
	// 	},
	// 	                        }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample Response

Status code:: 201

{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.TimeSeriesInsights/Environments/env1",
  "location": "West US",
  "name": "env1",
  "type": "Microsoft.TimeSeriesInsights/Environments",
  "kind": "Gen1",
  "tags": {},
  "properties": {
    "dataRetentionTime": "P31D",
    "provisioningState": "Creating",
    "creationTime": "2017-04-18T19:20:33.2288820Z"
  },
  "sku": {
    "name": "S1",
    "capacity": 1
  }
}

Status code:: 200

{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.TimeSeriesInsights/Environments/env1",
  "location": "West US",
  "name": "env1",
  "type": "Microsoft.TimeSeriesInsights/Environments",
  "kind": "Gen1",
  "tags": {},
  "properties": {
    "dataRetentionTime": "P31D",
    "provisioningState": "Succeeded",
    "creationTime": "2017-04-18T19:20:33.2288820Z"
  },
  "sku": {
    "name": "S1",
    "capacity": 1
  }
}

Status code:: 404

Definitions

Name	Description
CloudError	Contains information about an API error.
CloudErrorBody	Describes a particular API error with an error code and a message.
EnvironmentStateDetails	An object that contains the details about an environment's state.
EnvironmentStatus	An object that represents the status of the environment, and its internal state in the Time Series Insights service.
Gen1EnvironmentCreateOrUpdateParameters	Parameters supplied to the Create or Update Environment operation for a Gen1 environment.
Gen1EnvironmentResource	An environment is a set of time-series data available for query, and is the top level Azure Time Series Insights resource. Gen1 environments have data retention limits.
Gen2EnvironmentCreateOrUpdateParameters	Parameters supplied to the Create or Update Environment operation for a Gen2 environment.
Gen2EnvironmentResource	An environment is a set of time-series data available for query, and is the top level Azure Time Series Insights resource. Gen2 environments do not have set data retention limits.
Gen2StorageConfigurationInput	The storage configuration provides the connection details that allows the Time Series Insights service to connect to the customer storage account that is used to store the environment's data.
Gen2StorageConfigurationOutput	The storage configuration provides the non-secret connection details about the customer storage account that is used to store the environment's data.
IngressEnvironmentStatus	An object that represents the status of ingress on an environment.
IngressState	This string represents the state of ingress operations on an environment. It can be "Disabled", "Ready", "Running", "Paused" or "Unknown"
PropertyType	The type of the property.
ProvisioningState	Provisioning state of the resource.
Sku	The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.
SkuName	The name of this SKU.
StorageLimitExceededBehavior	The behavior the Time Series Insights service should take when the environment's capacity has been exceeded. If "PauseIngress" is specified, new events will not be read from the event source. If "PurgeOldData" is specified, new events will continue to be read and old events will be deleted from the environment. The default behavior is PurgeOldData.
TimeSeriesIdProperty	The structure of the property that a time series id can have. An environment can have multiple such properties.
WarmStorageEnvironmentStatus	An object that represents the status of warm storage on an environment.
WarmStoragePropertiesState	This string represents the state of warm storage properties usage. It can be "Ok", "Error", "Unknown".
WarmStoreConfigurationProperties	The warm store configuration provides the details to create a warm store cache that will retain a copy of the environment's data available for faster query.

CloudError

Contains information about an API error.

Name	Type	Description
error	CloudErrorBody	Describes a particular API error with an error code and a message.

CloudErrorBody

Describes a particular API error with an error code and a message.

Name	Type	Description
code	string	An error code that describes the error condition more precisely than an HTTP status code. Can be used to programmatically handle specific error cases.
details	CloudErrorBody[]	Contains nested errors that are related to this error.
message	string	A message that describes the error in detail and provides debugging information.
target	string	The target of the particular error (for example, the name of the property in error).

EnvironmentStateDetails

An object that contains the details about an environment's state.

Name	Type	Description
code	string	Contains the code that represents the reason of an environment being in a particular state. Can be used to programmatically handle specific cases.
message	string	A message that describes the state in detail.

EnvironmentStatus

An object that represents the status of the environment, and its internal state in the Time Series Insights service.

Name	Type	Description
ingress	IngressEnvironmentStatus	An object that represents the status of ingress on an environment.
warmStorage	WarmStorageEnvironmentStatus	An object that represents the status of warm storage on an environment.

Gen1EnvironmentCreateOrUpdateParameters

Parameters supplied to the Create or Update Environment operation for a Gen1 environment.

Name	Type	Description
kind	string: Gen1	The kind of the environment.
location	string	The location of the resource.
properties.dataRetentionTime	string	ISO8601 timespan specifying the minimum number of days the environment's events will be available for query.
properties.partitionKeyProperties	TimeSeriesIdProperty[]	The list of event properties which will be used to partition data in the environment. Currently, only a single partition key property is supported.
properties.storageLimitExceededBehavior	StorageLimitExceededBehavior	The behavior the Time Series Insights service should take when the environment's capacity has been exceeded. If "PauseIngress" is specified, new events will not be read from the event source. If "PurgeOldData" is specified, new events will continue to be read and old events will be deleted from the environment. The default behavior is PurgeOldData.
sku	Sku	The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.
tags	object	Key-value pairs of additional properties for the resource.

Gen1EnvironmentResource

An environment is a set of time-series data available for query, and is the top level Azure Time Series Insights resource. Gen1 environments have data retention limits.

Name	Type	Description
creationTime	string	The time the resource was created.
id	string	Resource Id
kind	string: Gen1	The kind of the environment.
location	string	Resource location
name	string	Resource name
properties.dataAccessFqdn	string	The fully qualified domain name used to access the environment data, e.g. to query the environment's events or upload reference data for the environment.
properties.dataAccessId	string	An id used to access the environment data, e.g. to query the environment's events or upload reference data for the environment.
properties.dataRetentionTime	string	ISO8601 timespan specifying the minimum number of days the environment's events will be available for query.
properties.partitionKeyProperties	TimeSeriesIdProperty[]	The list of event properties which will be used to partition data in the environment. Currently, only a single partition key property is supported.
properties.status	EnvironmentStatus	An object that represents the status of the environment, and its internal state in the Time Series Insights service.
properties.storageLimitExceededBehavior	StorageLimitExceededBehavior	The behavior the Time Series Insights service should take when the environment's capacity has been exceeded. If "PauseIngress" is specified, new events will not be read from the event source. If "PurgeOldData" is specified, new events will continue to be read and old events will be deleted from the environment. The default behavior is PurgeOldData.
provisioningState	ProvisioningState	Provisioning state of the resource.
sku	Sku	The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.
tags	object	Resource tags
type	string	Resource type

Gen2EnvironmentCreateOrUpdateParameters

Parameters supplied to the Create or Update Environment operation for a Gen2 environment.

Name	Type	Description
kind	string: Gen2	The kind of the environment.
location	string	The location of the resource.
properties.storageConfiguration	Gen2StorageConfigurationInput	The storage configuration provides the connection details that allows the Time Series Insights service to connect to the customer storage account that is used to store the environment's data.
properties.timeSeriesIdProperties	TimeSeriesIdProperty[]	The list of event properties which will be used to define the environment's time series id.
properties.warmStoreConfiguration	WarmStoreConfigurationProperties	The warm store configuration provides the details to create a warm store cache that will retain a copy of the environment's data available for faster query.
sku	Sku	The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.
tags	object	Key-value pairs of additional properties for the resource.

Gen2EnvironmentResource

An environment is a set of time-series data available for query, and is the top level Azure Time Series Insights resource. Gen2 environments do not have set data retention limits.

Name	Type	Description
creationTime	string	The time the resource was created.
id	string	Resource Id
kind	string: Gen2	The kind of the environment.
location	string	Resource location
name	string	Resource name
properties.dataAccessFqdn	string	The fully qualified domain name used to access the environment data, e.g. to query the environment's events or upload reference data for the environment.
properties.dataAccessId	string	An id used to access the environment data, e.g. to query the environment's events or upload reference data for the environment.
properties.status	EnvironmentStatus	An object that represents the status of the environment, and its internal state in the Time Series Insights service.
properties.storageConfiguration	Gen2StorageConfigurationOutput	The storage configuration provides the connection details that allows the Time Series Insights service to connect to the customer storage account that is used to store the environment's data.
properties.timeSeriesIdProperties	TimeSeriesIdProperty[]	The list of event properties which will be used to define the environment's time series id.
properties.warmStoreConfiguration	WarmStoreConfigurationProperties	The warm store configuration provides the details to create a warm store cache that will retain a copy of the environment's data available for faster query.
provisioningState	ProvisioningState	Provisioning state of the resource.
sku	Sku	The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.
tags	object	Resource tags
type	string	Resource type

Gen2StorageConfigurationInput

The storage configuration provides the connection details that allows the Time Series Insights service to connect to the customer storage account that is used to store the environment's data.

Name	Type	Description
accountName	string	The name of the storage account that will hold the environment's Gen2 data.
managementKey	string	The value of the management key that grants the Time Series Insights service write access to the storage account. This property is not shown in environment responses.

Gen2StorageConfigurationOutput

The storage configuration provides the non-secret connection details about the customer storage account that is used to store the environment's data.

Name	Type	Description
accountName	string	The name of the storage account that will hold the environment's Gen2 data.

IngressEnvironmentStatus

An object that represents the status of ingress on an environment.

Name	Type	Description
state	IngressState	This string represents the state of ingress operations on an environment. It can be "Disabled", "Ready", "Running", "Paused" or "Unknown"
stateDetails	EnvironmentStateDetails	An object that contains the details about an environment's state.

IngressState

This string represents the state of ingress operations on an environment. It can be "Disabled", "Ready", "Running", "Paused" or "Unknown"

Name	Type	Description
Disabled	string
Paused	string
Ready	string
Running	string
Unknown	string

PropertyType

The type of the property.

Name	Type	Description
String	string

ProvisioningState

Provisioning state of the resource.

Name	Type	Description
Accepted	string
Creating	string
Deleting	string
Failed	string
Succeeded	string
Updating	string

Sku

The sku determines the type of environment, either Gen1 (S1 or S2) or Gen2 (L1). For Gen1 environments the sku determines the capacity of the environment, the ingress rate, and the billing rate.

Name	Type	Description
capacity	integer	The capacity of the sku. For Gen1 environments, this value can be changed to support scale out of environments after they have been created.
name	SkuName	The name of this SKU.

SkuName

The name of this SKU.

Name	Type	Description
L1	string
P1	string
S1	string
S2	string

StorageLimitExceededBehavior

The behavior the Time Series Insights service should take when the environment's capacity has been exceeded. If "PauseIngress" is specified, new events will not be read from the event source. If "PurgeOldData" is specified, new events will continue to be read and old events will be deleted from the environment. The default behavior is PurgeOldData.

Name	Type	Description
PauseIngress	string
PurgeOldData	string

TimeSeriesIdProperty

The structure of the property that a time series id can have. An environment can have multiple such properties.

Name	Type	Description
name	string	The name of the property.
type	PropertyType	The type of the property.

WarmStorageEnvironmentStatus

An object that represents the status of warm storage on an environment.

Name	Type	Description
propertiesUsage.state	WarmStoragePropertiesState	This string represents the state of warm storage properties usage. It can be "Ok", "Error", "Unknown".
propertiesUsage.stateDetails.currentCount	integer	A value that represents the number of properties used by the environment for S1/S2 SKU and number of properties used by Warm Store for PAYG SKU
propertiesUsage.stateDetails.maxCount	integer	A value that represents the maximum number of properties used allowed by the environment for S1/S2 SKU and maximum number of properties allowed by Warm Store for PAYG SKU.

WarmStoragePropertiesState

This string represents the state of warm storage properties usage. It can be "Ok", "Error", "Unknown".

Name	Type	Description
Error	string
Ok	string
Unknown	string

WarmStoreConfigurationProperties

The warm store configuration provides the details to create a warm store cache that will retain a copy of the environment's data available for faster query.

Name	Type	Description
dataRetention	string	ISO8601 timespan specifying the number of days the environment's events will be available for query from the warm store.

Environments - Create Or Update

URI Parameters

Request Body

Gen1EnvironmentCreateOrUpdateParameters

Gen2EnvironmentCreateOrUpdateParameters

Responses

Security

azure_auth

Scopes

Examples

EnvironmentsCreate

Sample Request

Sample Response

Definitions

CloudError

CloudErrorBody

EnvironmentStateDetails

EnvironmentStatus

Gen1EnvironmentCreateOrUpdateParameters

Gen1EnvironmentResource

Gen2EnvironmentCreateOrUpdateParameters

Gen2EnvironmentResource

Gen2StorageConfigurationInput

Gen2StorageConfigurationOutput

IngressEnvironmentStatus

IngressState

PropertyType

ProvisioningState

Sku

SkuName

StorageLimitExceededBehavior

TimeSeriesIdProperty

WarmStorageEnvironmentStatus

WarmStoragePropertiesState

WarmStoreConfigurationProperties

Additional resources