Azure IoT Time Series Insights client library for .NET - version 1.0.0-beta.1

Article
10/11/2022

This library provides access to the Azure Time Series Insights service.

Getting started

The complete Microsoft Azure SDK can be downloaded from the Microsoft Azure downloads page, and it ships with support for building deployment packages, integrating with tooling, rich command line tooling, and more.

For the best development experience, developers should use the official Microsoft NuGet packages for libraries. NuGet packages are regularly updated with new functionality and hotfixes.

Install the package

No package has been published for this client library yet.

Prerequisites

A Microsoft Azure Subscription
- To call Microsoft Azure services, create an Azure subscription.

Authenticate the Client

In order to interact with the Azure Time Series Insights service, you will need to create an instance of a TokenCredential class and pass it to the constructor of your TimeSeriesInsightsClient.

Key concepts

The main concepts of Time Series Insights client include:

Instances client: To perform operations such as creating, listing, replacing and deleting Time Series instances.
Types client: To perform operations such as creating, listing, replacing and deleting Time Series types.
Hierarchies client: To perform operations such as creating, listing, replacing and deleting Time Series hierarchies.
Model Settings client: To perform operations such as getting and updating Time Series Model configuration settings.
Query client: To query for events, series and aggregate series on Time Series Insights.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that reusing client instances is always safe, even across threads.

Additional concepts

Examples

You can familiarize yourself with different APIs using samples for Time Series Insights.

Source code folder structure

/src

The Time Series Insights public client, TimeSeriesInsightsClient, and the additional configuration options, TimeSeriesInsightsClientOptions, that can be sent to the Time Series Insights service.

/src/Generated

The code generated by autorest using the swagger file defined in the autorest config file.

To regenerate the code, run the powershell script generate.ps1.

Any time the client library code is updated, the following scripts need to be run:

Export-AdtApis.ps1, which will update the API surface document.
Update-Snippets.ps1, which will update all the code snippets in the readme files and in the client documentation comments.

/src/Customized

The customzied code written to override the following behavior of auto-generated code:

Declare some of the generated types as internal, instead of the autorest default of public.

/src/Models

Model classes useful for use with the Time Series Insights client operations.

/src/Properties

Assembly properties required for running unit tests.

Troubleshooting

Time Series Insights service operation failures are usually returned to the user as TimeSeriesOperationError. The TimeSeriesOperationError response is either returned directly by the client library API, or as a nested property within the actual response for the client library API. For example, the DeleteByName API that is part of the hierarchies client returns a TimeSeriesOperationError directly. Whereas, the Replace API that is part of the instances client returns a InstancesOperationResult, which has a TimeSeriesOperationError property nested within it.

Example below shows use of TimeSeriesInsightsSampleGetTypeById operation, iterate through response error to find out if a type does not exist.

// Code snippet below shows getting a default Type using Id
// The default type Id can be obtained programmatically by using the ModelSettings client.

TimeSeriesInsightsModelSettings modelSettingsClient = client.GetModelSettingsClient();
TimeSeriesModelSettings modelSettings = await modelSettingsClient.GetAsync();
Response<TimeSeriesTypeOperationResult[]> getTypeByIdResults = await typesClient
    .GetByIdAsync(new string[] { modelSettings.DefaultTypeId });

// The response of calling the API contains a list of type or error objects corresponding by position to the input parameter array in the request.
// If the error object is set to null, this means the operation was a success.
for (int i = 0; i < getTypeByIdResults.Value.Length; i++)
{
    if (getTypeByIdResults.Value[i].Error == null)
    {
        Console.WriteLine($"Retrieved Time Series type with Id: '{getTypeByIdResults.Value[i].TimeSeriesType.Id}'.");
    }
    else
    {
        Console.WriteLine($"Failed to retrieve a Time Series type due to '{getTypeByIdResults.Value[i].Error.Message}'.");
    }
}

Next steps

See implementation examples with our code samples.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Share via