diff --git a/docs/_includes/analytics.html b/docs/_includes/analytics.html new file mode 100644 index 000000000..0cdbad25d --- /dev/null +++ b/docs/_includes/analytics.html @@ -0,0 +1,7 @@ + + + diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 80ae0323a..e4d432e12 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -13,3 +13,5 @@ + +{% if jekyll.environment == "production" %}{% include analytics.html %}{% endif %} diff --git a/docs/docs/sign-in-out.md b/docs/docs/sign-in-out.md index f619aaeab..77cb78108 100644 --- a/docs/docs/sign-in-out.md +++ b/docs/docs/sign-in-out.md @@ -2,7 +2,7 @@ title: Sign In and Out layout: docs --- - +## Signing in and out To sign in and out of Tableau Server, call the `Auth.sign_in` and `Auth.sign_out` functions like so: ```py @@ -18,22 +18,53 @@ server.auth.sign_in(tableau_auth) server.auth.sign_out() ``` +Alternatively, for short programs, consider using a `with` block: + +```py +import tableauserverclient as TSC + +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('http://SERVER_URL') + +with server.auth.sign_in(tableau_auth): + # Do awesome things here! + +# No need to call auth.sign_out() as the Auth context manager will handle that on exiting the with block +``` +
Note: When you sign in, the TSC library manages the authenticated session for you, however it is still limited by the maximum session length (of four hours) on Tableau Server.
- -Alternatively, for short programs, consider using a `with` block: +### Disabling certificate verification and warnings +Certain environments may throw errors related to SSL configuration, such as self-signed certificates or expired certificates. These errors can be avoided by disabling certificate verification with ```add_http_options```: ```py import tableauserverclient as TSC tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') server = TSC.Server('http://SERVER_URL') +server.add_http_options({'verify': False}) +``` -with server.auth.sign_in(tableau_auth): - # Do awesome things here! +However, each subsequent REST API call will print an ```InsecureRequestWarning```: +``` +InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/security.html +InsecureRequestWarning) +``` + +These warnings can be disabled by adding the following lines to your script: +```py +import requests +from requests.packages.urllib3.exceptions import InsecureRequestWarning +requests.packages.urllib3.disable_warnings(InsecureRequestWarning) ``` -The TSC library signs you out of Tableau Server when you exit out of the `with` block. +### A better way to avoid certificate warnings +Instead of disabling warnings and certificate verification to workaround issues with untrusted certificates, the best practice is to use a certificate signed by a Certificate Authority. + +If you have the ability to do so, we recommend the following Certificate Authorities: +* [GlobalSign](https://www.globalsign.com/en/) +* [Let's Encrypt](https://letsencrypt.org/) - a free, automated, and open Certificate Authority +* [SSL.com](https://www.ssl.com/)