Goofing around with the Cognitive Services Translator API

Recently, I was asked to get familiar with the Translator API in Azure Cognitive Services.  Not being a developer, I was a little leery of how I might approach this, but I was surprise how easy it was to tap into this functionality.  I thought I would share some of what I learned here in hopes that someone else tasked with using this or one of the other APIs in the Cognitive Services suite might find this helpful.  That said, what I've built here is in no way intended to represent a solution to a business problem; treat it as nothing more than a technical demonstration.

Deploying the API

The Translator API is part of a massive infrastructure managed by the Bing team.  In Azure, you provision a key which grants you access to this API.  This is done by logging into the Azure Portal (https://portal.azure.com), clicking +New from the left-hand navigation, entering Cognitive Services in the resulting search, and selecting Cognitive Services APIs from the results.

Clicking the Create button takes you to a form where you enter a unique Account name and select your Subscription.  When you click API type, you're presented with a list of the available APIs in the Cognitive Services suite. Choose Translator Text API from this list. For Pricing Tier, you have several options to choose from, but if you're just playing around, the Free tier gives you a lot of mileage.  For Resource Group, you can choose to Create new or Use Existing and then choose a Location for the deployment.  Clicking Create deploys the API to your tenant.

Once provisioned, access the resource from within the Azure Portal. Click on the Keys item in the left-hand navigation of its default tile.  Copy one of the two keys to your clipboard for use in next steps.

Understanding the API Methods

The Translator API you've deployed supports a wide range of methods.  These are documented at the bottom of this page.

As you explore each method, note whether it is employed via GET or POST.  When you expand the documentation of a method, notice the Response Content Type (identified just above the Parameters list) which typically indicates the method will return data as XML. In the Parameters list, take note of the various parameters, many of which are required, and their type.  Most parameters will be submitted via query string but most methods will require an Authorization parameter in the request header. (You can ignore the required appid parameter if you are submitting an Authorization parameter as shown below.)

Calling the Translate Method using PowerShell

At this point, I suspect the mechanics of the method call are a bit fuzzy.  Hopefully, jumping into some code will solve this problem.

To do this, let's use PowerShell.  Why PowerShell?  I can't imagine too many scenarios where PowerShell is the right solution for making calls to the Cognitive APIs, but I like the interactive nature of the PowerShell environment.  Instead of throwing all the demo code at you at once, I'll show it off in waves and PowerShell will allow you a bit of flexibility to play with it before moving on to the next step.

Launching PowerShell,  enter the following code:
$accountKey = "<insert the key you copied to your clipboard here>" $tokenServiceURL = "https://api.cognitive.microsoft.com/sts/v1.0/issueToken" $query = "?Subscription-Key=$accountKey" $uri = $tokenServiceUrl+$query $token = Invoke-RestMethod -Uri $uri -Method Post $token

Running this, you should see a long token value returned from the API.

With this token value, you can now assemble the header for your requests:
$auth = "Bearer "+$token $header = @{Authorization = $auth} $header

NOTE If you receive an error your token has expired, be sure to rerun the previous code to retrieve a new token and assemble a new header.  The token expires every 10 minutes.

To translate text, the Translate method requires the text you want to translate as well as a code that indicates the language you want to translate it to.  Similarly, you can tell the method the original language in the submitted text but this is optional as you can opt to have the API determine the original language for you.  There is a method to return the list of language codes but I find its easier to just look them up here.
$fromLang = "en" #English $toLang = "es"   #Spanish $text = Read-Host "Enter text to translate"

Using this information, you now can call the method.  The text submitted needs to be encoded and the method needs to be called with the GET verb:
$translationURL = "https://api.microsofttranslator.com/v2/Http.svc/Translate" $query = "?text=" + [System.Web.HttpUtility]::UrlEncode($text) $query += "&from=" + $fromLang $query += "&to=" + $toLang $query += "&contentType=text/plain" $uri = $translationUrl+$query `` $ret = Invoke-RestMethod -Uri $uri -Method Get -Headers $header
The $ret variable contains the XML output from the API service. PowerShell hands XML using the .NET System.Xml.XmlDocument class which exposes a bunch of properties and methods for extracting information from the XML document.  If you'd like to see the XML in its raw form, you can make use the OuterXML property on the variable:
$ret.OuterXml

You can see from this that the XML contains a single node named string.  To access the value assigned to this node, i.e. the translated text, you can reference it using:
$ret.string.'#text'

Conclusion

As I said at the top, this isn't supposed to represent a solution but instead provide a way to explore this API.  I hope this has been useful to those of you interested in working with Cognitive Services.