Summary: You can use Windows PowerShell to authenticate to the Microsoft Cognitive Services Text-to-Speech component through the Rest API.

Q: Hey, Scripting Guy!

I heard about the cool Microsoft Cognitive Services, and had heard they have a REST API. Does that mean I can use PowerShell to consume them? Could you show me how to authenticate to it?

—SH

A: Hello SH,

I just love waking up and saying “YES YOU CAN!” when people ask “Can you do that with Windows PowerShell?”

So… ahem…. “Yes you can!”

For those who didn’t know, Cognitive Services are hosted in the Azure cloud, and they allow you to many things easily. With very little work in PowerShell or any other programming language, we can moderate content visually.

We can easily use it to search the internet for content or, like we’ll do over the next series of articles, make use of the Text-to-Speech component.

First, sign up for the trial of Cognitive Services, which is part of the Azure Subscription.

If you don’t already have an Azure account, select FREE ACCOUNT to get yourself started. We’ll wait for you to finish.

Once that process is done, you’ll see some selections. Select Login to authenticate and add the trial. Then choose Speech to get a trial started with the Speech API.

Next, the most important button to select is Get API Key, beside the Bing Speech API. This will generate the application keys you’ll need to talk to the API.

IMPORTANT: If you already have an Azure subscription, and just want to get going under production (that is, not the trial), the steps are different. Please follow these instructions if you do not want to use the trial version, or you want to move to production from your trial.

“But…but Scripting Guy!” I can hear you say. “This is a PowerShell article…. Where’s the PowerShell?”

Well I was wondering when you were going to ask. I like to show both halves of the solution whenever I can.

First, you’ll need the updated AzureRM cmdlets from the PowerShell gallery to make sure you have the AzureRM.CognitiveServices module. If you haven’t done this before, just run the following cmdlet to get the complete set of cmdlets for managing Azure:

Install-Module AzureRM

If you are running an older version and need to update, just run this:

Update-Module AzureRM

You can confirm if the new module is available by running this:

Get-Module -ListAvailable AzureRM.CognitiveServices

On my system, I have a total of seven new cmdlets available to me for provisioning and managing these resources.

We would first authenticate by using the Login-AzureRMAccount cmdlet. Once connected, we can examine the properties of that newly created resource.

To list all Cognitive Service accounts we’ve created, we can run the following cmdlet. In this example, we have only the one created.

Get-AzureRMCognitiveServicesAccount

But if we’d like to re-create this, we can store and grab the properties by targeting the name of the account and the resource group it’s stored within. We will place this within the object called $Account.

$Account=Get-AzureRmCognitiveServicesAccount -Name 'HSG-CognitiveService' -ResourceGroupName 'HSG-ResourceGroup'

We’ll need some data from this object we captured, to rebuild or duplicate this process in the future.

To begin with, let’s obtain the first two: Location and the AccountType. The location should not to be mistaken with Azure datacenter locations.

We can obtain this from the object we created earlier, called $Account. It is stored within the property called Location, as seen in the preceding screenshot. Its value is global.

$Location=$Account.Location

An additional value we’ll need is the type of account we created. In our case, it was a connection to Bing.Speech. You can see this attached to the AccountType property, which we will obtain from the $Account object we created earlier.

$AccountType=$Account.AccountType

Another property we’ll need to obtain is the list of objects Azure uses to identify the pricing tiers. To find this, we can pipe the $Account object into the Get-AzureRMCognitiveServicesAccountSkus cmdlet. We will need to grab the values property specifically from this object, and expand it.

$Skus=$Account | Get-AzureRmCognitiveServicesAccountSkus | Select-Object -expandproperty Value

If you examine the newly created object, you’ll see results that don’t seem all that useful:

However, we can do a little PowerShell magic, and expand the Sku property further by doing this:

$Sku.Sku

In our case, we only need worry about the SKU used from the object we most recently created. Our goal is simply to duplicate the process. We can access the SKU directly again from the $Account object.

$Account.Sku

This will give us output similar to what we saw before (when we grabbed all the SKUs). In our case, to rebuild the resource, we only need the property called Name.

$Account.Sku.Name

To capture any of these properties, and avoid re-typing, we can just pipe to Set-Clipboard:

$Account.Sku.Name | Set-Clipboard

To re-create this resource from a new Azure subscription, we would just run the following script (after logging in of course):

# AzureRM Resource Group

$ResourceGroup='HSG-ResourceGroup'

# Azure Cognitive Services Account SKU

$Sku='F0'

# Azure Cognitive Services Account Type

$AccountType='Bing.Speech'

# Unique Name to our Azure Cognitive Services Account

$AccountName='HSG-Speech Account'

New-AzureRmCognitiveServicesAccount -ResourceGroupName 'HSG-ResourceGroup' -Name 'HSG-AzureRMSpeech' -Type Bing.Speech -SkuName F0 -Location 'global' -force

Be sure to visit again as we start to look into how to leverage this amazing resource by using the REST API!

I invite you to follow the Scripting Guys on Twitter and Facebook. If you have any questions, send email to them at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum.

Sean Kearney, Premier Field Engineer

Enterprise Services Delivery, Secure Infrastructure