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
in every subsequent HTTP request. So our first step needs to be signing in and grabbing the token for reuse.
What do you need to sign-in? At a basic level:
- server location
- site name: This is the “ContentUrl” i.e. the name as it appears in the browser URL
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:
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.
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: