Implementing the Tableau 9.0 REST API — Part 2 — Tokens, Sign-In and LUIDs

Tokens

One distinct feature of the Tableau 9.0 REST API is that you must be logged in to a site on the Tableau Server to perform any action other than sign-in or sign-out. When you sign-in successfully to a site, you receive a token, which then must be passed as a header in the format

X-tableau-auth: token

in every subsequent HTTP request. So our first step needs to be signing in and grabbing the token for reuse.

Sign-in

What do you need to sign-in? At a basic level:

  • server location
  • username
  • password
  • site name: This is the “ContentUrl” i.e. the name as it appears in the browser URL

http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_In%3FTocPath%3DAPI%2520Reference|_____51

This is the XML request we need to make to log in:


<tsRequest>
<credentials name="username" password="password" >
<site contentUrl="site-name" />
</credentials>
</tsRequest>

And then we will send this as an HTTP POST (remember Part 1?) to the following URI:

https://$servername/api/2.0/auth/signin

If successful, we’ll receive back an XML response with two essential pieces of information

  • login token
  • site id / site luid
<pre>

<?xml version="1.0" encoding="UTF-8"?>
<tsResponse version-and-namespace-settings>
<credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
<site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
contentUrl="MarketingSite"/>
</credentials>
</tsResponse>

</pre>

You can see both of these items in the XML response. To do anything useful with them, we’re going to have to parse the XML to pull out the info we need. Before we touch on that, let’s talk about the format of the ‘id’ attribute and what an LUID is.

LUIDS

The ‘id’ attribute of the <site> tag is not the text of the site name (that is referred to as the ContentUrl). It isn’t really human readable at all. Most referencing in the Tableau REST API is done via these “locally unique identifiers” (LUIDs), which are 32-character hexadecimal strings that always identify a given resource. This is useful because many things can be changed about an object in Tableau Server — you can change a group’s name, or the full name of a user, etc. Most of the code library is devoted to finding and translating names into LUIDs so they can be referenced in the API calls.

Anywhere you see the “id” property in the REST API XML or a URI description, it is an LUID and not a name, even if the name never changes. From the sign-on process then, we want to grab the LUID of the site rather than the ContentUrl, because we will reuse it with every subsequent call, because the format for every call that affects something on a site must begin with the site luid, like:

https://$servername/api/2.0/sites/$side_luid/

http://onlinehelp.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_luid.htm

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s