Get Started with Azure AI Services

In this exercise, you’ll get started with Azure AI Services by creating an Azure AI Services resource in your Azure subscription and using it from a client application. The goal of the exercise is not to gain expertise in any particular service, but rather to become familiar with a general pattern for provisioning and working with Azure AI services as a developer.

Provision an Azure AI Services resource

Azure AI Services are cloud-based services that encapsulate artificial intelligence capabilities you can incorporate into your applications. You can provision individual Azure AI services resources for specific APIs (for example, Language or Vision), or you can provision a single Azure AI Services resource that provides access to multiple Azure AI services APIs through a single endpoint and key. In this case, you’ll use a single Azure AI Services resource.

Open the Azure portal at https://portal.azure.com, and sign in using the Microsoft account associated with your Azure subscription.
In the top search bar, search for Azure AI services, select Azure AI services multi-service account, and create a resource with the following settings:
- Subscription: Your Azure subscription
- Resource group: Choose or create a resource group (if you are using a restricted subscription, you may not have permission to create a new resource group - use the one provided)
- Region: Choose any available region
- Name: Enter a unique name
- Pricing tier: Standard S0
Select the required checkboxes and create the resource.
Wait for deployment to complete, and then view the deployment details.
Go to the resource and view its Keys and Endpoint page. This page contains the information that you will need to connect to your resource and use it from applications you develop. Specifically:
- An HTTP endpoint to which client applications can send requests.
- Two keys that can be used for authentication (client applications can use either key to authenticate).
- The location where the resource is hosted. This is required for requests to some (but not all) APIs.

Clone the repository in Cloud Shell

You’ll develop your code using Cloud Shell from the Azure Portal. The code files for your app have been provided in a GitHub repo.

Tip: If you have already cloned the mslearn-ai-services repo recently, you can skip this task. Otherwise, follow these steps to clone it to your development environment.

In the Azure Portal, use the [>_] button to the right of the search bar at the top of the page to create a new Cloud Shell in the Azure portal, selecting a PowerShell environment. The cloud shell provides a command line interface in a pane at the bottom of the Azure portal.

Note: If you have previously created a cloud shell that uses a Bash environment, switch it to PowerShell.
In the cloud shell toolbar, in the Settings menu, select Go to Classic version (this is required to use the code editor).

Tip: As you paste commands into the cloudshell, the ouput may take up a large amount of the screen buffer. You can clear the screen by entering the cls command to make it easier to focus on each task.

In the PowerShell pane, enter the following commands to clone the GitHub repo for this exercise:

 rm -r mslearn-ai-services -f
 git clone https://github.com/microsoftlearning/mslearn-ai-services mslearn-ai-services

After the repo has been cloned, navigate to the folder containing the application code files:
```
cd mslearn-ai-services/Labfiles/01-use-azure-ai-services
```

Use a REST Interface

The Azure AI services APIs are REST-based, so you can consume them by submitting JSON requests over HTTP. In this example, you’ll explore a console application that uses the Language REST API to perform language detection; but the basic principle is the same for all of the APIs supported by the Azure AI Services resource.

Note: In this exercise, you can choose to use the REST API from either C# or Python. In the steps below, perform the actions appropriate for your preferred language.

Navigate to the folder containing the application code files for your preferred language:

Python
```
cd Python/rest-client
```
C#
```
cd C-Sharp/rest-client
```
Using the ls command, you can view the contents of the rest-client folder. Note that it contains a file for configuration settings:
- Python: .env
- C#: appsettings.json
Enter the following command to edit the configuration file that has been provided:

Python
```
code .env
```
C#
```
code appsettings.json
```
The file is opened in a code editor.
In the code file, update the configuration values it contains to reflect the endpoint and an authentication key for your Azure AI services resource.
After you’ve replaced the placeholders, use the CTRL+S command to save your changes and then use the CTRL+Q command to close the code editor while keeping the cloud shell command line open.
Enter the following command to open the code file for the client application:

Python
```
code rest-client.py
```
C#
```
code Program.cs
```
Review the code it contains, noting the following details:
- Various namespaces are imported to enable HTTP communication
- Code in the Main function retrieves the endpoint and key for your Azure AI services resource - these will be used to send REST requests to the Text Analytics service.
- The program accepts user input, and uses the GetLanguage function to call the Text Analytics language detection REST API for your Azure AI services endpoint to detect the language of the text that was entered.
- The request sent to the API consists of a JSON object containing the input data - in this case, a collection of document objects, each of which has an id and text.
- The key for your service is included in the request header to authenticate your client application.
- The response from the service is a JSON object, which the client application can parse.
Use the CTRL+Q command to close the code editor while keeping the cloud shell command line open and run the following command:

Python
```
 pip install python-dotenv
 python rest-client.py
```
C#
```
 dotnet run
```
When prompted, enter some text and review the language that is detected by the service, which is returned in the JSON response. For example, try entering “Hello”, “Bonjour”, and “Gracias”.
When you have finished testing the application, enter “quit” to stop the program.

Use an SDK

You can write code that consumes Azure AI services REST APIs directly, but there are software development kits (SDKs) for many popular programming languages, including Microsoft C#, Python, Java, and Node.js. Using an SDK can greatly simplify development of applications that consume Azure AI services.

Navigate to the folder containing the SDK application code files by running cd ../sdk-client.
Install the Text Analytics SDK package by running the appropriate command for your language preference:

Python
```
 pip install azure-ai-textanalytics==5.3.0
```
C#
```
 dotnet add package Azure.AI.TextAnalytics --version 5.3.0
```
Enter the following command to edit the configuration file that has been provided:

Python
```
code .env
```
C#
```
code appsettings.json
```
In the code file, update the configuration values it contains to reflect the endpoint and an authentication key for your Azure AI services resource.
After you’ve replaced the placeholders, use the CTRL+S command to save your changes and then use the CTRL+Q command to close the code editor while keeping the cloud shell command line open.
Enter the following command to open the code file for the client application:

Python
```
code sdk-client.py
```
C#
```
code Program.cs
```
Review the code it contains, noting the following details:
- The namespace for the SDK you installed is imported
- Code in the Main function retrieves the endpoint and key for your Azure AI services resource - these will be used with the SDK to create a client for the Text Analytics service.
- The GetLanguage function uses the SDK to create a client for the service, and then uses the client to detect the language of the text that was entered.
Use the CTRL+Q command to close the code editor and run the following command:

Python
```
 python sdk-client.py
```
C#
```
 dotnet run
```
When prompted, enter some text and review the language that is detected by the service. For example, try entering “Goodbye”, “Au revoir”, and “Hasta la vista”.
When you have finished testing the application, enter “quit” to stop the program.

Note: Some languages that require Unicode character sets may not be recognized in this simple console application.

Clean up resources

If you’re not using the Azure resources created in this lab for other training modules, you can delete them to avoid incurring further charges.

Open the Azure portal at https://portal.azure.com, and in the top search bar, search for the resources you created in this lab.
On the resource page, select Delete and follow the instructions to delete the resource. Alternatively, you can delete the entire resource group to clean up all resources at the same time.

More information

For more information about Azure AI Services, see the Azure AI Services documentation.