Export (0) Print
Expand All

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:

  1. Subscribe to the Microsoft Translator API on Azure Marketplace
  2. Register your application with Azure DataMarket
  3. 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
Show:
© 2014 Microsoft