Summary: You can use Windows PowerShell to authenticate to the Text-to-Speech REST API.

Q: Hey, Scripting Guy!

I was reading up on the REST API for the Text-to-Speech component of Cognitive Services. I’m just starting to learn how to use REST and PowerShell. Could you spend a little bit of time and show me how to authenticate to the service?

—SH

A: Hello SH,

Authentication is one of the biggest pieces you’ll want to learn. Telling a system at the back end who you are, and knowing how to communicate with it, is very critical before you can do anything fun!

Talking to the Text-to-Speech API is pretty easy once you know the basics. If we were to pretend the web service was a door with a really cool VIP in the back and a bodyguard watching it, the interaction might go like this:

Knocking on the door with no credentials or invalid credentials.

“Hello, I want to walk in.”

Strange look on the bodyguard’s face, and he says “Huh?” or “Grrrr” (or roars like Chewbacca). That would be your error code.

You can keep doing this as many times as you like, and you’re still not going into that door.

But provide the correct “secret phrase” (or, in our case, key) and the interaction goes like this:

“Hello, I want to walk in. The secret phrase is ‘crustless frozen peanut butter sandwiches’.”

The bodyguard looks at the list, sees that secret phrase beside your name, and nods. He then calls up on his two-way radio and gets a new, second secret phrase, with instructions to a second door.

Now you meet the second bodyguard, who is much meaner than first one. (Missed getting coffee that morning I suppose.) This one wants your second phrase, and after validating it’s good, the second bodyguard starts a stopwatch.

You can run in and out of the door to do what you need with that new phrase, but after a certain amount of time he scratches that phrase off the list.

So, you run back to the first body guard, hand him your first passphrase, and the process repeats until you’re done for the day.

That’s pretty much what the authentication piece for the REST API does, and how it works.

We talk to a REST API, and pass it one of the keys we generated in the last article. The REST API generates a token, which is a long string of characters, and you need to use that token with the second REST API. This token is only good for a short term, and you need to go back and request a new one every so often.

Let’s get some basics together to make this happen.

This first “door” is an endpoint to the REST API that handles the authentication. The documentation on the use of this endpoint can be found under the authentication header at Bing Text-to-Speech API.

We are provided the following information immediately:

POST https://api.cognitive.microsoft.com/sts/v1.0/issueToken

Content-Length: 0

From this information, we can see we need to use a POST method, and the endpoint is https://api.cognitive.microsoft.com/sts/v1.0/issueToken.

Let’s start to build that into some Windows PowerShell variables.

 

# Rest API Method

$Method=’POST’

 

# Rest API Endpoint

$Uri=’ https://api.cognitive.microsoft.com/sts/v1.0/issueToken’

 

The next piece we need to supply is the header information. We need to pass our key to a value named Ocp-Apim-Subscription-Key.

The value of the key is one of the two authentication keys you produced last time, when you initially created the Cognitive Services account for Bing.Speech. I’m going to use a fictitious one for our example.

Here, we’ll populate the header. The header in this case is pretty simple, containing only one value.

 

# Authentication Key

$AuthenticationKey=’13775361233908722041033142028212′

 

# Headers to pass to Rest API

$Headers=@{‘Ocp-Apim-Subscription-Key’ = $AuthenticationKey }

 

We then call up the REST endpoint directly, to see if everything worked.

Invoke-RestMethod -Method $Method -Uri $Uri -Headers $Headers

 

If it worked properly, and everything was formatted the way it should be, the output would be something similar to the following. This is your token for the temporary access to the second endpoint.

We would then modify our Invoke-RestMethod to be captured to a PowerShell object, so we can reuse it later.

 

# Get Authentication Token to communicate with Text to Speech Rest API

$Token=Invoke-RestMethod -Method $Method -Uri $Uri -Headers $Headers

 

On the other hand, if you didn’t supply a valid authentication key, you would get this:

So, with this knowledge, we can even trap for this in our script.

Try

{

[string]$Token=$NULL

# Rest API Method

[string]$Method='POST'

# Rest API Endpoint

[string]Uri='https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

# Authentication Key

[string]$AuthenticationKey='13775361233908722041033142028212'

# Headers to pass to Rest API

$Headers=@{'Ocp-Apim-Subscription-Key' = $AuthenticationKey }

# Get Authentication Token to communicate with Text to Speech Rest API

[string]$Token=Invoke-RestMethod -Method $Method -Uri $Uri -Headers $Headers

}

Catch [System.Net.Webexception]

{

Write-Output 'Failed to Authenticate'

}

Now we know how to get a token to communicate with the Bing.Speech API. Pop in again next time, when we’ll show you how to start putting the building blocks together to use the service!

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, Microsoft

Frequent contributor to Hey, Scripting Guy!