Azure Authoring client library for .NET - version 1.0.0-beta.1
Azure Text Authoring is part of the Azure Cognitive Service for Language, a cloud-based service that provides tools for creating, managing, and deploying text processing and AI solutions. This client library offers the following features:
- Creating and managing text analysis projects
- Importing and exporting text analysis projects
- Training models for text processing and analysis
- Evaluating trained models
- Deploying text processing models
- Swapping deployments for active models
- Canceling active training jobs
- Managing project snapshots
- Deleting trained models and deployments
Source code | Package (NuGet) | API reference documentation | Product documentation | Samples
Getting started
This section should include everything a developer needs to do to install and create their first client connection very quickly.
Install the package
Install the client library for .NET with NuGet:
dotnet add package Azure.AI.Language.Text.Authoring --prerelease
SDK version | Supported API version of service |
---|---|
1.0.0-beta.1 | 2022-05-01, 2023-04-01, 2023-11-15-preview, 2024-11-15-preview (default) |
Prerequisites
- An Azure subscription.
- An existing Cognitive Services or Language service resource.
Authenticate the client
In order to interact with the Text Authoring service, you'll need to create an instance of the TextAnalysisAuthoringClient
class. You will need an endpoint, and an API key to instantiate a client object. For more information regarding authenticating with Cognitive Services, see Authenticate requests to Azure Cognitive Services.
Get an API key
You can get the endpoint
and API key
from the Cognitive Services resource or Language service resource information in the Azure Portal.
Alternatively, use the Azure CLI snippet below to get the API key from the Language service resource.
az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>
Create a TextAnalysisAuthoringClient
To use the TextAnalysisAuthoringClient, include the following namespace in your project:
using Azure.AI.Language.Text.Authoring;
With your endpoint and API key, you can instantiate a TextAnalysisAuthoringClient using specific service options:
Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new("your apikey");
TextAnalysisAuthoringClientOptions options = new TextAnalysisAuthoringClientOptions(TextAnalysisAuthoringClientOptions.ServiceVersion.V2024_11_15_Preview);
TextAnalysisAuthoringClient client = new TextAnalysisAuthoringClient(endpoint, credential, options);
Create a client using Azure Active Directory authentication
You can also create a TextAnalysisAuthoringClient
using Azure Active Directory (AAD) authentication. Your user or service principal must be assigned the "Cognitive Services Language Reader" role.
Using the DefaultAzureCredential, you can authenticate a service using Managed Identity or a service principal, authenticate as a developer working on an application, and more, all without changing code.
Before you can use the DefaultAzureCredential
, or any credential type from Azure.Identity, you'll first need to install the Azure.Identity package.
To use DefaultAzureCredential with a client ID and secret, you'll need to set the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET environment variables; alternatively, you can pass those values to the ClientSecretCredential also in Azure.Identity.
Make sure you use the right namespace for DefaultAzureCredential at the top of your source file:
using Azure.Identity;
using Azure.Core;
using Microsoft.Extensions.Options;
Then you can create an instance of DefaultAzureCredential and pass it to a new instance of your client:
Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
DefaultAzureCredential credential = new DefaultAzureCredential();
TextAnalysisAuthoringClient client = new TextAnalysisAuthoringClient(endpoint, credential);
Note that regional endpoints do not support AAD authentication. Instead, create a custom domain name for your resource to use AAD authentication.
Service API versions
The client library targets the latest service API version by default. A client instance accepts an optional service API version parameter from its options to specify which API version service to communicate.
Select a service API version
You have the flexibility to explicitly select a supported service API version when instantiating a client by configuring its associated options. This ensures that the client can communicate with services using the specified API version.
For example:
Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new("your apikey");
TextAnalysisAuthoringClientOptions options = new TextAnalysisAuthoringClientOptions(TextAnalysisAuthoringClientOptions.ServiceVersion.V2024_11_15_Preview);
TextAnalysisAuthoringClient client = new TextAnalysisAuthoringClient(endpoint, credential, options);
When selecting an API version, it's important to verify that there are no breaking changes compared to the latest API version. If there are significant differences, API calls may fail due to incompatibility.
Always ensure that the chosen API version is fully supported and operational for your specific use case and that it aligns with the service's versioning policy.
If you do not select an API version, we will default to the latest version available, which has the possibility of being a preview version.
Key concepts
TextAuthoringClientlet
The TextAuthoringProject, TextAuthoringDeployment, TextAuthoringExportedModel and TextAuthoringTrainedModel are the clientlets for developers using the Azure AI Text Authoring client library. It provides both synchronous and asynchronous operations to access a specific use of text authoring, such as creating and managing text analysis projects.
Thread safety
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.
Additional concepts
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
Examples
You can familiarize yourself with different APIs using Samples.
- Get Project Details (Sync)
- Get Project Details (Async)
- Import a Project (Sync)
- Import a Project (Async)
- Create a New Project (Sync)
- Create a New Project (Async)
- Delete a Project (Sync)
- Delete a Project (Async)
- Train a Model (Sync)
- Train a Model (Async)
- Cancel Training Job (Sync)
- Cancel Training Job (Async)
- Get Model Evaluation Summary (Sync)
- Get Model Evaluation Summary (Async)
- Load Snapshot (Sync)
- Load Snapshot (Async)
- Delete a Trained Model (Sync)
- Delete a Trained Model (Async)
- Deploy a project (Sync)
- Deploy a project (Async)
- Swap Deployments (Sync)
- Swap Deployments (Async)
- Delete a Deployment (Sync)
- Delete a Deployment (Async)
Troubleshooting
General
When you interact with the Cognitive Language Services Text Authoring client library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.
For example, if you attempt to create a project with an invalid configuration, a 400 error is returned indicating "Bad Request".
try
{
string invalidProjectName = "InvalidProject";
TextAuthoringProject projectClient = client.GetProject(invalidProjectName);
var projectData = new TextAuthoringCreateProjectDetails(
projectKind: "Text",
storageInputContainerName: "e2e0test0data",
language: "invalid-lang" // Invalid language code
)
{
Description = "This is a test for invalid configuration."
};
Response response = projectClient.CreateProject(projectData);
}
catch (RequestFailedException ex)
{
Console.WriteLine(ex.ToString());
}
You will notice that additional information is logged, like the client request ID of the operation.
Azure.RequestFailedException: The input parameter is invalid.
Status: 400 (Bad Request)
ErrorCode: InvalidArgument
Content:
Azure.RequestFailedException: Invalid Request.
Status: 400 (Bad Request)
ErrorCode: InvalidRequest
Content:
{"error":{"code":"InvalidRequest","message":"Invalid Request.","innererror":{"code":"LanguageCodeInvalid","message":"The language code is invalid. Possible values are: en, es, fr, ..."}}}
Headers:
Transfer-Encoding: chunked
x-envoy-upstream-service-time: REDACTED
apim-request-id: REDACTED
Strict-Transport-Security: REDACTED
X-Content-Type-Options: REDACTED
x-ms-region: REDACTED
Date: Wed, 24 Jul 2024 13:39:00 GMT
Content-Type: application/json; charset=utf-8
Setting up console logging
The simplest way to see the logs is to enable the console logging. To create an Azure SDK log listener that outputs messages to the console, use AzureEventSourceListener.CreateConsoleLogger method.
// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
To learn more about other logging mechanisms, see here.
Next steps
View our samples. Read about the different features of the Text Authoring.
Contributing
See the CONTRIBUTING.md for details on building, testing, and contributing to this library.
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 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.
Azure SDK for .NET