Obtaining an Access Token
You must obtain an access token to use the Microsoft Translator API. The access token is passed with each API call and is used to authenticate you access to the Microsoft Translator API. It provides a secure access to the Microsoft Translator API and allows the API to associate your application’s requests to the Microsoft Translator service with your account on Azure Marketplace.
Microsoft provides methods to obtain access tokens safely, repeatedly, and easily. To obtain an access token, perform the following steps:
- Subscribe to the Microsoft Translator API on Azure Marketplace
- Register your application with Azure DataMarket
- Make an HTTP POST request to the token service
1. Subscribe to the Microsoft Translator API on Azure Marketplace
Subscribe to the Microsoft Translator API on Azure Marketplace. Basic subscriptions, up to 2 million characters a month, are free. Translating more than 2 million characters per month requires a payment. You may pick from any of the available subscription offers.
2. Register your application Azure DataMarket
To register your application with Azure DataMarket, visit
https://datamarket.azure.com/developer/applications/
using the LiveID credentials
from step 1, and click on “Register”. In the “Register your application” dialog
box, you can define your own Client ID and Name. The redirect URI is not used for
the Microsoft Translator API. However, the redirect URI field is a mandatory field,
and you must provide a URI to obtain the access code. A description is optional.
Take a note of the client ID and the client secret value. Please visit
here to learn more about how to sign up for Microsoft Translator on Azure Marketplace.
3. Make an HTTP POST request to the token service
After you register your application with Azure DataMarket, make an HTTP POST request
to the token service to obtain the access token. The parameters for the token request
are URL-encoded and passed in the HTTP request body.
The following table lists the mandatory input parameters and their descriptions.
Table 1: Token Request Input Parameters
| Parameter | Description |
|---|---|
| client_id | Required. The client ID that you specified when you registered your application with Azure DataMarket. |
| client_secret | Required. The client secret value that you obtained when you registered your application with Azure DataMarket. |
| scope | Required. Use the URL http://api.microsofttranslator.com as the scope value for the Microsoft Translator API. |
| grant_type | Required. Use "client_credentials" as the grant_type value for the Microsoft Translator API. |
The response for the token request contains the access token that you can use to access the Microsoft Translator API. The response is JSON-encoded and includes the following output properties.
Table 2: Token Request Output Properties
| Property | Description |
|---|---|
| access_token | The access token that you can use to authenticate you access to the Microsoft Translator API. |
| token_type | The format of the access token. Currently, Azure DataMarket returns http://schemas.xmlsoap.org/ws/2009/11/swt-token-profile-1.0 , which indicates that a Simple Web Token (SWT) token will be returned. |
| expires_in | The number of seconds for which the access token is valid. |
| scope | The domain for which this token is valid. For the Microsoft Translator API, the domain is http://api.microsofttranslator.com. |
Using the Access Token
Bing AppID mechanism is deprecated and is no longer supported. As mentioned above, you must obtain an access token to use the Microsoft Translator API. The access token is more secure, OAuth standard compliant, and more flexible. Users who are using Bing AppID are strongly recommended to get an access token as soon as possible.
The value of access token can be used for subsequent calls to the Microsoft Translator
API. The access token expires after 10 minutes. It is always better to check elapsed
time between time at which token issued and current time. If elapsed time exceeds
10 minute time period renew access token by following obtaining access token procedure.
Remember the following points about using the access token:
- Use the prefix "Bearer" + " " + the value of the access_token property as the Authorization header to the calls to the Microsoft Translator API.
- Leave the appid field empty. It serves only the legacy purpose.
- The access token is valid for 10 minutes. If the access token expires, you need to generate a new access token. The C sharp sample code below (AdmAuthentication class) can generate a new access token prior to exceeding to 10 minute time period.
Examples
C#PHP
Windows PowerShell
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Runtime.Serialization.Json;
using System.Runtime.Serialization;
using System.Web;
using System.ServiceModel.Channels;
using System.ServiceModel;
using System.Threading;
namespace MicrosoftTranslatorSdk.HttpSamples
{
class Program
{
static void Main(string[] args)
{
AdmAccessToken admToken;
string headerValue;
//Get Client Id and Client Secret from https://datamarket.azure.com/developer/applications/
//Refer obtaining AccessToken (http://msdn.microsoft.com/en-us/library/hh454950.aspx)
AdmAuthentication admAuth = new AdmAuthentication("clientID", "client secret");
try
{
admToken = admAuth.GetAccessToken();
// Create a header with the access_token property of the returned token
headerValue = "Bearer " + admToken.access_token;
DetectMethod(headerValue);
}
catch (WebException e)
{
ProcessWebException(e);
Console.WriteLine("Press any key to continue...");
Console.ReadKey(true);
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
Console.WriteLine("Press any key to continue...");
Console.ReadKey(true);
}
}
private static void DetectMethod(string authToken)
{
Console.WriteLine("Enter Text to detect language:");
string textToDetect = Console.ReadLine();
//Keep appId parameter blank as we are sending access token in authorization header.
string uri = "http://api.microsofttranslator.com/v2/Http.svc/Detect?text=" + textToDetect;
HttpWebRequest httpWebRequest = (HttpWebRequest)WebRequest.Create(uri);
httpWebRequest.Headers.Add("Authorization", authToken);
WebResponse response = null;
try
{
response = httpWebRequest.GetResponse();
using (Stream stream = response.GetResponseStream())
{
System.Runtime.Serialization.DataContractSerializer dcs = new System.Runtime.Serialization.DataContractSerializer(Type.GetType("System.String"));
string languageDetected = (string)dcs.ReadObject(stream);
Console.WriteLine(string.Format("Language detected:{0}", languageDetected));
Console.WriteLine("Press any key to continue...");
Console.ReadKey(true);
}
}
catch
{
throw;
}
finally
{
if (response != null)
{
response.Close();
response = null;
}
}
}
private static void ProcessWebException(WebException e)
{
Console.WriteLine("{0}", e.ToString());
// Obtain detailed error information
string strResponse = string.Empty;
using (HttpWebResponse response = (HttpWebResponse)e.Response)
{
using (Stream responseStream = response.GetResponseStream())
{
using (StreamReader sr = new StreamReader(responseStream, System.Text.Encoding.ASCII))
{
strResponse = sr.ReadToEnd();
}
}
}
Console.WriteLine("Http status code={0}, error message={1}", e.Status, strResponse);
}
}
[DataContract]
public class AdmAccessToken
{
[DataMember]
public string access_token { get; set; }
[DataMember]
public string token_type { get; set; }
[DataMember]
public string expires_in { get; set; }
[DataMember]
public string scope { get; set; }
}
public class AdmAuthentication
{
public static readonly string DatamarketAccessUri = "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13";
private string clientId;
private string clientSecret;
private string request;
private AdmAccessToken token;
private Timer accessTokenRenewer;
//Access token expires every 10 minutes. Renew it every 9 minutes only.
private const int RefreshTokenDuration = 9;
public AdmAuthentication(string clientId, string clientSecret)
{
this.clientId = clientId;
this.clientSecret = clientSecret;
//If clientid or client secret has special characters, encode before sending request
this.request = string.Format("grant_type=client_credentials&client_id={0}&client_secret={1}&scope=http://api.microsofttranslator.com", HttpUtility.UrlEncode(clientId), HttpUtility.UrlEncode(clientSecret));
this.token = HttpPost(DatamarketAccessUri, this.request);
//renew the token every specfied minutes
accessTokenRenewer = new Timer(new TimerCallback(OnTokenExpiredCallback), this, TimeSpan.FromMinutes(RefreshTokenDuration), TimeSpan.FromMilliseconds(-1));
}
public AdmAccessToken GetAccessToken()
{
return this.token;
}
private void RenewAccessToken()
{
AdmAccessToken newAccessToken = HttpPost(DatamarketAccessUri, this.request);
//swap the new token with old one
//Note: the swap is thread unsafe
this.token = newAccessToken;
Console.WriteLine(string.Format("Renewed token for user: {0} is: {1}", this.clientId, this.token.access_token));
}
private void OnTokenExpiredCallback(object stateInfo)
{
try
{
RenewAccessToken();
}
catch (Exception ex)
{
Console.WriteLine(string.Format("Failed renewing access token. Details: {0}", ex.Message));
}
finally
{
try
{
accessTokenRenewer.Change(TimeSpan.FromMinutes(RefreshTokenDuration), TimeSpan.FromMilliseconds(-1));
}
catch (Exception ex)
{
Console.WriteLine(string.Format("Failed to reschedule the timer to renew access token. Details: {0}", ex.Message));
}
}
}
private AdmAccessToken HttpPost(string DatamarketAccessUri, string requestDetails)
{
//Prepare OAuth request
WebRequest webRequest = WebRequest.Create(DatamarketAccessUri);
webRequest.ContentType = "application/x-www-form-urlencoded";
webRequest.Method = "POST";
byte[] bytes = Encoding.ASCII.GetBytes(requestDetails);
webRequest.ContentLength = bytes.Length;
using (Stream outputStream = webRequest.GetRequestStream())
{
outputStream.Write(bytes, 0, bytes.Length);
}
using (WebResponse webResponse = webRequest.GetResponse())
{
DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(AdmAccessToken));
//Get deserialized object from JSON stream
AdmAccessToken token = (AdmAccessToken)serializer.ReadObject(webResponse.GetResponseStream());
return token;
}
}
}
}
Goto Top
<?php
class AccessTokenAuthentication {
/*
* Get the access token.
*
* @param string $grantType Grant type.
* @param string $scopeUrl Application Scope URL.
* @param string $clientID Application client ID.
* @param string $clientSecret Application client ID.
* @param string $authUrl Oauth Url.
*
* @return string.
*/
function getTokens($grantType, $scopeUrl, $clientID, $clientSecret, $authUrl){
try {
//Initialize the Curl Session.
$ch = curl_init();
//Create the request Array.
$paramArr = array (
'grant_type' => $grantType,
'scope' => $scopeUrl,
'client_id' => $clientID,
'client_secret' => $clientSecret
);
//Create an Http Query.//
$paramArr = http_build_query($paramArr);
//Set the Curl URL.
curl_setopt($ch, CURLOPT_URL, $authUrl);
//Set HTTP POST Request.
curl_setopt($ch, CURLOPT_POST, TRUE);
//Set data to POST in HTTP "POST" Operation.
curl_setopt($ch, CURLOPT_POSTFIELDS, $paramArr);
//CURLOPT_RETURNTRANSFER- TRUE to return the transfer as a string of the return value of curl_exec().
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
//CURLOPT_SSL_VERIFYPEER- Set FALSE to stop cURL from verifying the peer's certificate.
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//Execute the cURL session.
$strResponse = curl_exec($ch);
//Get the Error Code returned by Curl.
$curlErrno = curl_errno($ch);
if($curlErrno){
$curlError = curl_error($ch);
throw new Exception($curlError);
}
//Close the Curl Session.
curl_close($ch);
//Decode the returned JSON string.
$objResponse = json_decode($strResponse);
if ($objResponse->error){
throw new Exception($objResponse->error_description);
}
return $objResponse->access_token;
} catch (Exception $e) {
echo "Exception-".$e->getMessage();
}
}
}
/*
* Class:HTTPTranslator
*
* Processing the translator request.
*/
Class HTTPTranslator {
/*
* Create and execute the HTTP CURL request.
*
* @param string $url HTTP Url.
* @param string $authHeader Authorization Header string.
* @param string $postData Data to post.
*
* @return string.
*
*/
function curlRequest($url, $authHeader, $postData=''){
//Initialize the Curl Session.
$ch = curl_init();
//Set the Curl url.
curl_setopt ($ch, CURLOPT_URL, $url);
//Set the HTTP HEADER Fields.
curl_setopt ($ch, CURLOPT_HTTPHEADER, array($authHeader,"Content-Type: text/xml"));
//CURLOPT_RETURNTRANSFER- TRUE to return the transfer as a string of the return value of curl_exec().
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
//CURLOPT_SSL_VERIFYPEER- Set FALSE to stop cURL from verifying the peer's certificate.
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, False);
if($postData) {
//Set HTTP POST Request.
curl_setopt($ch, CURLOPT_POST, TRUE);
//Set data to POST in HTTP "POST" Operation.
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
}
//Execute the cURL session.
$curlResponse = curl_exec($ch);
//Get the Error Code returned by Curl.
$curlErrno = curl_errno($ch);
if ($curlErrno) {
$curlError = curl_error($ch);
throw new Exception($curlError);
}
//Close a cURL session.
curl_close($ch);
return $curlResponse;
}
/*
* Create Request XML Format.
*
* @param string $languageCode Language code
*
* @return string.
*/
function createReqXML($languageCode) {
//Create the Request XML.
$requestXml = '<ArrayOfstring xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">';
if($languageCode) {
$requestXml .= "<string>$languageCode</string>";
} else {
throw new Exception('Language Code is empty.');
}
$requestXml .= '</ArrayOfstring>';
return $requestXml;
}
}
try {
//Client ID of the application.
$clientID = "clientId";
//Client Secret key of the application.
$clientSecret = "ClientSecret";
//OAuth Url.
$authUrl = "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13/";
//Application Scope Url
$scopeUrl = "http://api.microsofttranslator.com";
//Application grant type
$grantType = "client_credentials";
//Create the AccessTokenAuthentication object.
$authObj = new AccessTokenAuthentication();
//Get the Access token.
$accessToken = $authObj->getTokens($grantType, $scopeUrl, $clientID, $clientSecret, $authUrl);
//Create the authorization Header string.
$authHeader = "Authorization: Bearer ". $accessToken;
//Create the Translator Object.
$translatorObj = new HTTPTranslator();
//Input String.
$inputStr = 'This is the sample string.';
//HTTP Detect Method URL.
$detectMethodUrl = "http://api.microsofttranslator.com/V2/Http.svc/Detect?text=".urlencode($inputStr);
//Call the curlRequest.
$strResponse = $translatorObj->curlRequest($detectMethodUrl, $authHeader);
//Interprets a string of XML into an object.
$xmlObj = simplexml_load_string($strResponse);
foreach((array)$xmlObj[0] as $val){
$languageCode = $val;
}
/*
* Get the language Names from languageCodes.
*/
$locale = 'en';
$getLanguageNamesurl = "http://api.microsofttranslator.com/V2/Http.svc/GetLanguageNames?locale=$locale";
//Create the Request XML format.
$requestXml = $translatorObj->createReqXML($languageCode);
//Call the curlRequest.
$curlResponse = $translatorObj->curlRequest($getLanguageNamesurl, $authHeader, $requestXml);
//Interprets a string of XML into an object.
$xmlObj = simplexml_load_string($curlResponse);
echo "<table border=2px>";
echo "<tr>";
echo "<td><b>LanguageCodes</b></td><td><b>Language Names</b></td>";
echo "</tr>";
foreach($xmlObj->string as $language){
echo "<tr><td>".$inputStr."</td><td>". $languageCode."(".$language.")"."</td></tr>";
}
echo "</table>";
} catch (Exception $e) {
echo "Exception: " . $e->getMessage() . PHP_EOL;
}
Goto Top
#region Construct Azure Datamarket access_token #Get ClientId and Client_Secret from https://datamarket.azure.com/developer/applications/ #Refer obtaining AccessToken (http://msdn.microsoft.com/en-us/library/hh454950.aspx) $ClientID = '<Your Value Here From Registered Application>' $client_Secret = ‘<Your Registered Application client_secret>' # If ClientId or Client_Secret has special characters, UrlEncode before sending request $clientIDEncoded = [System.Web.HttpUtility]::UrlEncode($ClientID) $client_SecretEncoded = [System.Web.HttpUtility]::UrlEncode($client_Secret) #Define uri for Azure Data Market $Uri = "https://datamarket.accesscontrol.windows.net/v2/OAuth2-13" #Define the body of the request $Body = "grant_type=client_credentials&client_id=$clientIDEncoded&client_secret=$client_SecretEncoded&scope=http://api.microsofttranslator.com" #Define the content type for the request $ContentType = "application/x-www-form-urlencoded" #Invoke REST method. This handles the deserialization of the JSON result. Less effort than invoke-webrequest $admAuth=Invoke-RestMethod -Uri $Uri -Body $Body -ContentType $ContentType -Method Post #Construct the header value with the access_token just recieved $HeaderValue = "Bearer " + $admauth.access_token #endregion #region Construct and invoke REST request to Microsoft Translator Service [string] $text = "Use pixels to express measurements for padding and margins."; [string] $textEncoded = [System.Web.HttpUtility]::UrlEncode($text) [string] $from = "en"; [string] $to = "de"; [string] $uri = "http://api.microsofttranslator.com/v2/Http.svc/Translate?text=" + $text + "&from=" + $from + "&to=" + $to; $result = Invoke-RestMethod -Uri $uri -Headers @{Authorization = $HeaderValue} #endregion $result.string.'#text'
Goto Top