You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add troubleshooting guide, rewrite sign in page, general improvements
- Add troubleshooting guide for capturing REST API traffic
- Add docs for site_switch() added in #655
- Rewrite sign in/out page to be more clear
- Add docs for PersonalAccessTokenAuth added in #465
- Some general edits and wordsmithing
1. Install the project dependencies (which includes Jekyll) by running `bundle install`. (In the future you can run `bundle update` to catch any new dependencies.)
161
164
162
-
1. Run the Jekyll site locally with `bundle exec jekyll serve`
165
+
1. Run the Jekyll site locally with `bundle exec jekyll serve`.
163
166
164
-
1. In your browser, connect to <http://127.0.0.1:4000/server-client-python/>
167
+
1. In your browser, connect to <http://127.0.0.1:4000/server-client-python/> to preview the changes. As long as the Jekyll serve process is running, it will rebuild any new file changes automatically.
165
168
166
-
For more details on the steps, see the GitHub Pages topic on
Copy file name to clipboardExpand all lines: docs/sign-in-out.md
+92-21Lines changed: 92 additions & 21 deletions
Original file line number
Diff line number
Diff line change
@@ -3,46 +3,117 @@ title: Sign In and Out
3
3
layout: docs
4
4
---
5
5
6
-
To sign in and out of Tableau Server, call the server's `.auth.signin` method in a `with` block.
6
+
The first step to using the TSC library is to sign in to your Tableau Server (or Tableau Online). This page explains how to sign in, sign out, and switch sites, with examples for both Tableau Server and Tableau Online.
7
+
8
+
* TOC
9
+
{:toc}
10
+
11
+
## Sign In
12
+
13
+
Signing in can be done two different ways:
14
+
15
+
* Personal Access Tokens - In most cases this is the preferred method because it improves security by avoiding the need to use or store passwords directly. Access tokens also expire by default if not used after 15 consecutive days. This option is available for Tableau Server 2019.4 and newer. Refer to [Personal Access Tokens](https://help.tableau.com/current/server/en-us/security_personal_access_tokens.htm) for more details.
16
+
* Username and Password - Direct sign in with account username and password.
17
+
18
+
Examples showing both of these cases are included below.
19
+
20
+
**Note:** When you sign in, the TSC library manages the authenticated session for you. However, the validity of the underlying credentials token is limited by the maximum session length set on your Tableau Server (2 hours by default).
21
+
22
+
### Sign in with Personal Access Token
23
+
24
+
To sign in to Tableau Server or Tableau Online with a personal access token, you'll need the following values:
25
+
26
+
Name | Description
27
+
:--- | :---
28
+
TOKEN_NAME | The personal access token name (from the My Account settings page)
29
+
TOKEN_VALUE | The personal access token value (from the My Account settings page)
30
+
**Tableau Server** |
31
+
SITENAME | The Tableau Server site you are authenticating with; for example in the site URL http://MyServer/#/site/MarketingTeam/projects, the site name is MarketingTeam; in the REST API documentation this field is also referred to as contentUrl; this value can be omitted to connect with the Default site on the server
32
+
SERVER_URL | The Tableau Server you are authenticating with; if your server has SSL enabled, this should be an HTTPS link
33
+
**Tableau Online** |
34
+
SITENAME | The Tableau Online site you are authenticating with; for example in the site URL https://10ay.online.tableau.com/#/site/umbrellacorp816664/workbooks, the site name is umbrellacorp816664; in the REST API documentation this field is also referred to as contentUrl; this value is always required when connecting to Tableau Online
35
+
SERVER_URL | The Tableau Online instance you are authenticating with; in the example above the server URL would be https://10ay.online.tableau.com; this will always be an an HTTPS link
36
+
37
+
This example illustrates using the above values to sign in with a personal access token, do some operations, and then sign out:
server =TSC.Server('https://SERVER_URL', use_server_version=True)
69
+
server.auth.sign_in(tableau_auth)
15
70
16
-
with server.auth.sign_in(tableau_auth):
17
-
# Do awesome things here!
71
+
# Do awesome things here!
72
+
73
+
server.auth.sign_out()
18
74
```
19
75
20
-
`SERVER_URL` is the URL of your Tableau server without subpaths. For local Tableau servers, an example would be: `https://www.MY_SERVER.com`. For Tableau Online, an example would be: `https://10ax.online.tableau.com/`.
76
+
## Sign Out
21
77
22
-
`SITENAME` is the subpath of your full site URL (also called `contentURL` in the REST API). `MYSITE` would be the site name of `https://10ax.online.tableau.com/MYSITE`. This parameter can be omitted when signing in to the Default site of an on-premise Tableau server.
78
+
Signing out cleans up the current session and invalidates the authentication token being held by the TSC library.
23
79
24
-
`TOKEN_NAME` and `TOKEN_VALUE` are your [Personal Access Token](https://help.tableau.com/current/server/en-us/security_personal_access_tokens.htm) values, generated in your Account Settings.
80
+
As shown in the examples above, the sign out call is simply:
25
81
26
-
Optionally, you can override the version of Tableau API you are authorizing against by adding `server.version = '<VERSION_NUMBER>'` before the `auth.signin` call.
82
+
```py
83
+
server.auth.sign_out()
84
+
```
27
85
28
-
The TSC library signs you out of Tableau Server when you exit out of the `with` block.
86
+
## Simplify by using Python with block
29
87
30
-
<divclass="alert alert-info">
31
-
**Note:** When you sign in, the TSC library manages the authenticated session for you, however the validity of the underlying
32
-
credentials token is limited by the maximum session length set on your Tableau Server (2 hours by default).
33
-
</div>
88
+
The sign in/out flow can be simplified (and handled in a more Python way) by using the built-in support for the `with` block. After the block execution completes, the sign out is called automatically.
34
89
35
-
An alternative to using a `with` block is to call the `Auth.sign_in` and `Auth.sign_out` functions explicitly:
90
+
For example:
36
91
37
92
```py
38
93
import tableauserverclient asTSC
39
94
40
-
tableau_auth =TSC.TableauAuth('USERNAME', 'PASSWORD') # with no site name, this will use the Default site
print("\nThere are {} workbooks on site: ".format(pagination_item.total_available))
101
+
for wb in all_wb:
102
+
print(wb.id, wb.name)
103
+
```
42
104
43
-
server.auth.sign_in(tableau_auth)
105
+
All of the samples provided in TSC library use this technique.
44
106
45
-
# Do awesome things here!
107
+
## Switch Site
46
108
47
-
server.auth.sign_out()
109
+
Tableau Server has a feature which enables switching to another site without having to authenticate again. (The user must have access permissions for the new site as well.)
110
+
111
+
**Note:** This method is not available on Tableau Online.
112
+
113
+
The following example will switch the authenticated user to the NEW_SITENAME site on the same server:
114
+
115
+
```py
116
+
# assume we already have an authenticated server object
This page covers some common troubleshooting tips for using the TSC library.
7
+
8
+
<divclass="alert alert-warning">
9
+
<spanclass="glyphicon glyphicon-warning-sign"aria-hidden="true"></span> Warning: Do not post any debug logs or REST API request/response contents anywhere on GitHub. The contents may include sensitive data or authentication secrets. Instead you can post just edited snippets of relevant content after sanitizing (removing any sensitive values).
10
+
</div>
11
+
12
+
* TOC
13
+
{:toc}
14
+
15
+
## Logging REST API communication with Tableau Server
16
+
17
+
There may be cases where it's helpful to inspect the REST API calls the TSC library is making and the responses coming back from Tableau Server. Some examples might be:
18
+
19
+
* The TSC library is throwing an error or the results are not coming through as expected
20
+
* The TSC library or the REST backend may have a bug which needs to be tracked down
21
+
22
+
To enable logging, add the following to your Python script ahead of making any TSC calls:
Now when your script executes, you'll see a set of debug messages in the `tsc.log` file. Each API call to the REST API will be included along with the XML responses. Depending on the problem being investigated, you can compare these requests/responses to the [REST API documentation](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm) to track down the issue.
31
+
32
+
## Capture REST API communication with local proxy
33
+
34
+
Another approach for inspecting REST API traffic is to use a local debugging proxy server like [Fiddler Everywhere](https://www.telerik.com/fiddler). Fiddler Everywhere is free for basic use and has versions for Mac, Windows and Linux.
35
+
36
+
These are the steps to send the API traffic through to a local proxy like Fiddler:
37
+
38
+
1. Install Fiddler Everywhere and create a free account if needed
39
+
2. Launch the Fiddler app and click the settings (gear) icon to enable Capture HTTPS traffic. (Do not click Trust root certificate.)
40
+
3. Before running your script, set the following environment variables (on Windows, use SET commands instead):
The sample screenshot below shows the results of running a simple sign in/out sequence. The Capture pane includes one row for each HTTP request. Select the request to see the details on the right side: Request and Response.
Proxy server applications other than Fiddler can be used as well. Just adjust the HTTP_PROXY and HTTPS_PROXY environment variables to use the proper IP address and port number.
Copy file name to clipboardExpand all lines: docs/versions.md
+6-3Lines changed: 6 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,8 @@ layout: docs
6
6
Because the TSC library is a client for the Tableau Server REST API, you need to confirm that the version of the TSC
7
7
library that you use is compatible with the version of the REST API used by your installation of Tableau Server.
8
8
9
+
For reference, the [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm) page has more details about versions.
10
+
9
11
* TOC
10
12
{:toc}
11
13
@@ -21,11 +23,11 @@ server = TSC.Server('http://SERVER_URL')
21
23
print(server.version)
22
24
```
23
25
24
-
For example, the code might display version `2.3`.
26
+
For example, the code might display version `2.3`.
25
27
26
28
## Use the REST API version supported by the server
27
29
28
-
There are two options for always using the the latest version of the REST API that is supported by the instance of Tableau Server you are connecting to.
30
+
There are two options for always using the the latest version of the REST API that is supported by the instance of Tableau Server you are connecting to. This could be necessary in cases where you're using an API feature that is only supported in a newer REST API version.
29
31
30
32
The first method is to specify `use_server_version=True` as one of the arguments, for example:
31
33
@@ -52,7 +54,7 @@ To use a specific version of the REST API, set the version like so:
52
54
import tableauserverclient asTSC
53
55
54
56
server =TSC.Server('http://SERVER_URL')
55
-
server.version ='2.6'
57
+
server.version ='3.6'
56
58
57
59
```
58
60
@@ -62,6 +64,7 @@ The current version of TSC only supports the following REST API and Tableau Serv
0 commit comments