Retrieve Microsoft Translator API Access Tokens with XQuery and BaseX

Retrieve Microsoft Translator API Access Tokens with XQuery and BaseX

An access token is required to use the Microsoft Cognitive Services Translator application programming interface (API) with XQuery, an XML query language, and BaseX, an XML database engine and XQuery processor. This tutorial covers how to retrieve an access token from the Authentication Token API for Microsoft Cognitive Services Translator API with XQuery and BaseX.

The Authentication Token API returns an encoded access token that allows us to use Microsoft Translator APIs with XQuery and BaseX. Please note that to retrieve an access token, we first need an Azure account and a subscription to a Microsoft Translator API. Find all XQuery code for this tutorial in my GitHub repository ms-translator-api-xquery.

Retrieve access tokens

We can retrieve an access token from the Authentication Token API with XQuery via an HTTP request to the “issueToken” endpoint. To illustrate this process, we’ll use the function retrieveAccessToken() within ms-translator-api-basex.xquery. First, we build our HTTP request. Second, we send our HTTP request to the Authentication Token API. Third, we convert our access token into a string and prefix Bearer . Finally, we return our access token. The XQuery code for retrieving an access token follows:

declare function ms-translator-api:retrieveAccessToken(
  $azureKey as xs:string
) as xs:string {
  let $authenticationRequest := (
    <http:request method="post">
      <http:header name="Content-Type" value="application/json" />
      <http:header name="Accept" value="application/jwt" />
      <http:header name="Ocp-Apim-Subscription-Key" value="{$azureKey}" />
      <http:body media-type="application/json">
        <!-- a blank body returns HTTP Error 411 -->
      </http:body>
    </http:request>
  )
  let $authenticationResponse := http:send-request(
    $authenticationRequest,
    "https://api.cognitive.microsoft.com/sts/v1.0/issueToken"
  )   
  let $accessToken := fn:concat(
    "Bearer ",
    $authenticationResponse[2]
    => xs:base64Binary()
    => convert:binary-to-string()
  )
  return $accessToken
};

retrieveAccessToken() explained

In the XQuery code above, we bind our HTTP request to the variable $authenticationRequest. We use the POST request method, <http:request method="post">, required by the Authentication Token API’s “issueToken” endpoint. The HTTP header Ocp-Apim-Subscription-Key represents our subscription key, $azureKey, and its value is passed to our function ms-translator-api:retrieveAccessToken() as an argument.

We send our HTTP request using the BaseX function http:send-request() and bind the response to $authenticationResponse. The first argument of http:send-request() is our HTTP request, $authenticationRequest, and the second argument is the URI to which we send our request. A successful request yields an <http:response> element and an encoded access token.

To use our encoded access token, we must convert it to a string and prefix Bearer . We declare the variable $accessToken and assign its value using the XQuery string function fn:concat() to concatenate Bearer and the string value of our encoded access token. We use $authenticationResponse[2] to represent our encoded access token since we don’t need the <http:response> element within $authenticationResponse. Deriving the string value of our encoded access token is a two-step process: first we cast $authenticationResponse[2] as Base64 binary data by piping it to xs:base64Binary(), and second we convert it to a string by piping it to the BaseX function convert:binary-to-string().

Finally, we return $accessToken, which allows us to use Microsoft Translator APIs. Each access token can be used multiple times and is valid for ten minutes.

XQuery Microsoft Translator library module

Import ms-translator-api-basex.xquery

Calling the function ms-translator-api:retrieveAccessToken() can be done by importing the Microsoft Translator library module ms-translator-api-basex.xquery and assigning it the namespace ms-translator-api:

import module namespace ms-translator-api="ms-translator-api-basex" at "https://raw.githubusercontent.com/AdamSteffanick/ms-translator-api-xquery/master/ms-translator-api-basex.xquery";

Call retrieveAccessToken()

Using the library module, we can retrieve an access token from the Authentication Token API by calling the function ms-translator-api:retrieveAccessToken(). This function returns an access token for use in an HTTP header for future HTTP requests to Microsoft Translator APIs. In the below XQuery code, we replace myKey with an appropriate Azure subscription key and then pass it to the function as an argument. We bind the result of the function to the variable $accessToken and then return $accessToken.

Get the code

xquery version "3.1" encoding "UTF-8";

import module namespace ms-translator-api="ms-translator-api-basex" at "https://raw.githubusercontent.com/AdamSteffanick/ms-translator-api-xquery/master/ms-translator-api-basex.xquery";

(: # API credentials :)
let $azureKey := "myKey"

let $accessToken := ms-translator-api:retrieveAccessToken($azureKey)

return $accessToken

Notes

The majority of the XQuery code in the library module ms-translator-api-basex.xquery is not specific to BaseX, however I did use the BaseX Conversion and HTTP modules. Changes to the library module may be required when using a different XQuery processor.

What we learned

Thanks to this XQuery tutorial, we can now:

Thank you for reading, and have fun coding.