From 7901ae4ac6277260502c2563f3ad738c72008baf Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Wed, 22 Mar 2017 16:10:29 -0700 Subject: [PATCH 01/17] adding to ref pages; saving progress so far --- docs/docs/api-ref.md | 407 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 395 insertions(+), 12 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index ac1d5f949..27fd27a2b 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -10,6 +10,7 @@ layout: docs * TOC {:toc} +{:toc_levels(1,2,3)} ## Authentication @@ -31,6 +32,40 @@ Signs you out of Tableau Server. Auth.sign_out() ``` +## Connection + +### ConnectionItem class + +```py +class ConnectionItem(object) +``` + +**Attributes** + +`datasource_id` : + +`datasource_name` : + +`id` : + +`connection_type` : + +`embed_password` : + +`password` : + +`server_address` : + +`server_port` : + +`username` : + + +Source file: models/connection_item.py + +
+
+ ## Sites Source files: server/endpoint/sites_endpoint.py, models/site_item.py @@ -104,20 +139,34 @@ self.server.projects.create(new_project) ### Get Projects -Get the first 100 projects on the server. To get all projects, use the Pager. - ```py Projects.get() ``` -### Update Project +Get the first 100 projects on the server. To get all projects, use the Pager. -Modifies a project. The project item object must include the project ID and overrides all other settings. +### Update Project ```py -Projects.update(project_item_object) +Projects.update(project_item) ``` +Modify a project. + +You can use this method to update the project name, the project description, or the project permissions. + +##### Parameters + +`project_item` + + The project item object must include the project ID. The values in the project item override the current project settings. + +##### Returns + +Returns the updated project information. + +See ProjectItem + ### Delete Project Deletes a project by ID. @@ -128,7 +177,7 @@ Projects.delete(id) ## Workbooks -Source files: server/endpoint/workbooks.py, models/workbook_item.py +Source files: server/endpoint/workbooks_endpoint.py, models/workbook_item.py ### Get Workbooks @@ -219,43 +268,377 @@ Populates a preview image for a given workbook. You must populate the image befo connections. ```py -Workbooks.populate_connections(workbook_obj) +Workbooks.populate_preview_image(workbook_obj) ``` ### Get Views for a Workbook Returns a list of views for a workbook. Before you get views, you must call populate_views. -``` -workbook_obj.views +```py +Workbooks.views ``` ### Get Connections for a Workbook Returns a list of connections for a workbook. Before you get connections, you must call populate_connections. -``` +```py workbook_obj.connections ``` ## Views +Get all the views on a site, or get the views for a specific workbook, or populate the preview image for a view. +The methods are based upon the ViewItem class. + +### ViewItem class + +``` +class ViewItem(object) + +``` + +The ViewItem class contains the members or attributes for the view resources on Tableau Server. The ViewItem class defines the information you can request or query from Tableau Server. The class members correspontd to the attributes of a server request or response payload. + +Source file: models/view_item.py + +**Attributes** + + +`id` : The identifier of the view item. + +`name` : The name of the view. + +`owner_id` : The id for the owner of the view. + +`preview_image` : The thumbnail image for the view. + +`total_views` : The usage statistics for the view. Indicates the total number of times the view has been looked at. + +`workbook_id` : The id of the workbook associated with the view. + + + + + +### View methods -Source files: server/endpoint/views_endpoint.py, models/view_item.py +The Tableau Server Client provides two methods for interacting with view resources, or endpoints. These methods correspond to the [Query Views for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Site%3FTocPath%3DAPI%2520Reference%7C_____64) and [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69) endpoints in the Tableau Server REST API. +Source file: server/endpoint/views_endpoint.py +#### get() +``` +Views.get(req_option=None) +``` + +Returns the list of views items for a site. + +**Parameters** + +`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific view, you could specify the name of the view or its id. + + +**Returns** + +Returns a list of all `ViewItem` objects and a `PaginationItem`. Use these values to iterate through the results. + +**Example** + +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('username', 'password') +server = TSC.Server('http://servername') + +with server.auth.sign_in(tableau_auth): + all_views, pagination_item = server.views.get() + print([view.name for view in all_views]) + +```` + +See [ViewItem class](#viewitem-class) + +#### populate_preview_image(*view_item*) + +```py + Views.populate_preview_image(view_item) + +``` + +Populates a preview image for a given view. + +This method gets the preview image (thumbnail) for the specified view item. The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `view.preview_image` for the view. + + +**Parameters** + +`view_item` : The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. + +**Exceptions** + +`View item missing ID or workbook ID` : Raises an error if the id for the view item or workbook is missing. + +**Returns** +None. The preview image is added to the view. + +See [ViewItem class](#viewitem-class) + + ## Data sources +Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project. +The data source resources for Tableau Server are defined in the DatasourceItem class. The class corresponds to the data source resources you can access using the Tableau Server REST API, for example, information about the name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the DatasourceItem class. + +### DatasourceItem class + +```py +class DatasourceItem(object) +``` +The `DatasourceItem` represents the data source resources on Tableau Server. This is the information returned in the response to a REST API request for data sources. + +**Attributes** + +`connections` : The list of data connections (`ConnectionItem`) for the specified data source. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class). + +`content_url` : The name of the data source as it would appear in a URL. + +`created_at` : The date and time when the data source was created. + +`datasource_type` : The type of data source, for example, `sqlserver` or `excel-direct`. + +`id` : The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. + +`project_id` : The identifer of the project associated with the data source. + +`project_name` : The name of the project associated with the data source. + +`tags` : The tags that have been added to the data source. + +`updated_at` : The date and time when the data source was last updated. + +Source file: models/datasource_item.py + +
+
+ +### Datasource methods + +The Tableau Server Client provides several methods for interacting with data source resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. + +
+
+ +#### delete(*datasource_id*) + +```py +datasources.delete(datasource_id) +``` + +Removes the specified data source from Tableau Server. + + +**Parameters** + +`datasource_id` : The identifier (`id`) for the the `DatasourceItem` that you want to delete from the server. + + +**Exceptions** + +`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. + + +REST API: [Delete Datasource](http://onlinehelp.tableau.com/v0.0/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Datasource%3FTocPath%3DAPI%2520Reference%7C_____19){:target="_blank"} + +
+
+ + +#### download(*datasource_id*, *filepath=None*) + +```py +datasources.download(datasource_id, filepath=None) + +``` +Downloads the specified data source in `.tdsx` format. + + +**Parameters** + +`datasource_id` : The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. + +`filepath` : (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. + + +**Exceptions** + +`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. + + +**Returns** + +The data source in `.tdsx` format. + + +REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Datasource%3FTocPath%3DAPI%2520Reference%7C_____34){:target="_blank"} + +
+
+ +#### get() + +```py +datasources.get(req_options=None) +``` + +Returns all the data sources for the site. + +To get the connection information for each data source, you must first populate the `DatasourceItem` with connection information using the [populate_connections(*datasource_item*)](#populate-connections-datasource) method. For more information, see [Populate Connections and Views](populate-connections-views#populate-connections-for-data-sources) + +REST API: [Query Datasources](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasources%3FTocPath%3DAPI%2520Reference%7C_____49) + +**Parameters** + +`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific data source, you could specify the name of the project or its id. + + +**Returns** + +Returns a list of `DatasourceItem` objects and a `PaginationItem` object. Use these values to iterate through the results. + + + + +**Example** + +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('http://SERVERURL') + +with server.auth.sign_in(tableau_auth): + all_datasources, pagination_item = server.datasources.get() + print("\nThere are {} datasources on site: ".format(pagination_item.total_available)) + print([datasource.name for datasource in all_datasources]) +```` + + + +
+
+ + +#### get_by_id(*datasource_id*) + +```py +datasources.get_by_id(datasource_id) +``` + +Returns the specified data source item. + +REST API: [Query Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource%3FTocPath%3DAPI%2520Reference%7C_____46) + + +**Parameters** + +`datasource_id` : The `datasource_id` specifies the data source to query. + + +**Exceptions** + +`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. + + +**Returns** + +The `DatasourceItem`. See [DatasourceItem class](#datasourceitem-class) + + +**Example** + +```py +datasource = server.datasources.get_by_id(server.datasources[1].id) +print(datasource.name) + +``` + + +
+
+ + + +#### populate_connections(*datasource_item*) + +Populates the connections for the specified data source. + + + + +This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (`datasource_item.connections`) populates the data source with the list of `ConnectionItem`. + +REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47) + +**Parameters** + +`datasource_item` : The `datasource_item` specifies the data source to populate with connection information. + + + + +**Exceptions** + +`Datasource item missing ID. Datasource must be retrieved from server first.` : Raises an errror if the datasource_item is unspecified. + + +**Returns** + +None. A list of `ConnectionItem` objects are added to the data source (`datasource_item.connections`). + + +**Example** + +```py +datasource = server.datasources.get_by_id(server.datasources[1].id) +print(datasource.name) + +server.datasources.populate_connections(datasource) +print([connection.datasource_name for connection in datasource.connections]) +``` + + +
+
+ +#### publish(*datasource_item*) + + +
+
+ +#### update(*datasource_item*) + Source files: server/endpoint/datasources_endpoint.py, models/datasource_item.py +
+
## Users Source files: server/endpoint/users_endpoint.py, models/user_item.py + +
+
+ ## Groups -Source files: server/endpoint/groups_endpoint.py, models/group_item.py, +Source files: server/endpoint/groups_endpoint.py, models/group_item.py + + + +
+
From c6d0a25eb6afac8a63a2202a5999f0a74e83525a Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Thu, 23 Mar 2017 20:04:28 -0700 Subject: [PATCH 02/17] Check in to save progress-o --- docs/docs/api-ref.md | 171 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 158 insertions(+), 13 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 27fd27a2b..5cbb9dd85 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -287,11 +287,16 @@ Returns a list of connections for a workbook. Before you get connections, you mu workbook_obj.connections ``` - +
+
## Views -Get all the views on a site, or get the views for a specific workbook, or populate the preview image for a view. -The methods are based upon the ViewItem class. + +Using the TSC library, you can get all the views on a site, or get the views for a workbook, or populate a view with preview images. +The view resources for Tableau Server are defined in the ViewItem class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, information about the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the `ViewItem` class. + + +
### ViewItem class @@ -320,15 +325,19 @@ Source file: models/view_item.py `workbook_id` : The id of the workbook associated with the view. - +
+
### View methods -The Tableau Server Client provides two methods for interacting with view resources, or endpoints. These methods correspond to the [Query Views for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Site%3FTocPath%3DAPI%2520Reference%7C_____64) and [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69) endpoints in the Tableau Server REST API. +The Tableau Server Client provides two methods for interacting with view resources, or endpoints. These methods correspond to the endpoints for views in the Tableau Server REST API. Source file: server/endpoint/views_endpoint.py +
+
+ #### get() ``` Views.get(req_option=None) @@ -336,6 +345,9 @@ Views.get(req_option=None) Returns the list of views items for a site. + +REST API: [Query Views for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Site%3FTocPath%3DAPI%2520Reference%7C_____64){:target="_blank"} + **Parameters** `req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific view, you could specify the name of the view or its id. @@ -360,6 +372,10 @@ with server.auth.sign_in(tableau_auth): See [ViewItem class](#viewitem-class) + +
+
+ #### populate_preview_image(*view_item*) ```py @@ -371,6 +387,7 @@ Populates a preview image for a given view. This method gets the preview image (thumbnail) for the specified view item. The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `view.preview_image` for the view. +REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69){:target="_blank"} **Parameters** @@ -386,18 +403,23 @@ None. The preview image is added to the view. See [ViewItem class](#viewitem-class) - +
+
+ ## Data sources Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project. The data source resources for Tableau Server are defined in the DatasourceItem class. The class corresponds to the data source resources you can access using the Tableau Server REST API, for example, information about the name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the DatasourceItem class. +
+ ### DatasourceItem class ```py -class DatasourceItem(object) +DatasourceItem(project_id, name=None) ``` -The `DatasourceItem` represents the data source resources on Tableau Server. This is the information returned in the response to a REST API request for data sources. + +The `DatasourceItem` represents the data source resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for data sources. When you create a new `DatasourceItem` instance, you must specify the `project_id` that the data source is associated with. **Attributes** @@ -411,7 +433,9 @@ The `DatasourceItem` represents the data source resources on Tableau Server. Thi `id` : The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. -`project_id` : The identifer of the project associated with the data source. +`name` : The name of the data source. If not specified, the name of the published data source file is used. + +`project_id` : The identifer of the project associated with the data source. When you must provide this identifier when create an instance of a `DatasourceItem` `project_name` : The name of the project associated with the data source. @@ -419,6 +443,18 @@ The `DatasourceItem` represents the data source resources on Tableau Server. Thi `updated_at` : The date and time when the data source was last updated. + +**Example** + +```py + import tableauserverclient as TSC + + # Create new datasource_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39' + + new_datasource = TSC.DatasourceItem('3a8b6148-493c-11e6-a621-6f3499394a39') +``` + + Source file: models/datasource_item.py
@@ -428,6 +464,8 @@ Source file: models/datasource_item.py The Tableau Server Client provides several methods for interacting with data source resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. +Source file: server/endpoint/datasources_endpoint.py +

@@ -497,7 +535,7 @@ Returns all the data sources for the site. To get the connection information for each data source, you must first populate the `DatasourceItem` with connection information using the [populate_connections(*datasource_item*)](#populate-connections-datasource) method. For more information, see [Populate Connections and Views](populate-connections-views#populate-connections-for-data-sources) -REST API: [Query Datasources](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasources%3FTocPath%3DAPI%2520Reference%7C_____49) +REST API: [Query Datasources](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasources%3FTocPath%3DAPI%2520Reference%7C_____49){:target="_blank"} **Parameters** @@ -538,7 +576,7 @@ datasources.get_by_id(datasource_id) Returns the specified data source item. -REST API: [Query Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource%3FTocPath%3DAPI%2520Reference%7C_____46) +REST API: [Query Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource%3FTocPath%3DAPI%2520Reference%7C_____46){:target="_blank"} **Parameters** @@ -572,6 +610,10 @@ print(datasource.name) #### populate_connections(*datasource_item*) +```py +datasources.populate_connections(datasource_item) +``` + Populates the connections for the specified data source. @@ -579,7 +621,7 @@ Populates the connections for the specified data source. This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (`datasource_item.connections`) populates the data source with the list of `ConnectionItem`. -REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47) +REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47){:target="_blank"} **Parameters** @@ -612,16 +654,119 @@ print([connection.datasource_name for connection in datasource.connections])

-#### publish(*datasource_item*) +#### publish(*datasource_item*, *file_path*, *mode*, *connection_credentials=None*) + +```py +datasources.publish(datasource_item, file_path, mode, connection_credentials=None) +``` + +Publishes a data source to a server, or appends data to an existing data source. + +This method checks the size of the data source and automatically determines whether the publish the data source in multiple parts or in one opeation. + +REST API: [Publish Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Datasource%3FTocPath%3DAPI%2520Reference%7C_____44){:target="_blank"} + +**Parameters** +`datasource_item` : The `datasource_item` specifies the new data source you are adding, or the data source you are appending to. If you are adding a new data source, you need to create a new `datasource_item` with a `project_id` of an existing project. The name of the data source will be the name of the file, unless you also specify a name for the new data source when you create the instance. See [DatasourceItem](#datasourceitem-class). + +`file_path` : The path and name of the data source to publish. + +`mode` : Specifies whether you are publishing a new data source (`CreateNew`), overwriting an existing data source (`Overwrite`), or appending data to a data source (`Append`). If you are appending to a data source, the data source on the server and the data source you are publishing must be be extracts (.tde files) and they must share the same schema. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. + +`connection_credentials` : (Optional) The credentials required to connect to the data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). + + + +**Exceptions** + +`File path does not lead to an existing file.` : Raises an error of the file path is incorrect or if the file is missing. + +`Invalid mode defined.` : Raises an error if the publish mode is not one of the defined options. + +`Only .tds, tdsx, or .tde files can be published as datasources.` : Raises an error if the type of file specified is not supported. + + +**Returns** + +The `DatasourceItem` for the data source that was added or appened to. + + +**Example** + +```py + import tableauserverclient as TSC + # server = TSC.Server('server') + # project_id = '3a8b6148-493c-11e6-a621-6f3499394a39' + # file_path = 'C:\\temp\\WorldIndicators.tde' + + ... + + # Use the default project id to create new datsource_item + new_datasource = TSC.DatasourceItem(project_id) + + # publish data source + new_datasource = server.datasources.publish( + new_datasource, file_path, 'CreateNew') + + ... +```

#### update(*datasource_item*) +```py +datasource.update(datasource_item) +``` + +Updates the owner, or project of the specified data source. + +REST API: [Update Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Datasource%3FTocPath%3DAPI%2520Reference%7C_____79){:target="_blank"} + +**Parameters** + +`datasource_item` : The `datasource_item` specifies the data source to update. + + + +**Exceptions** + +`Datasource item missing ID. Datasource must be retrieved from server first.` : Raises an errror if the datasource_item is unspecified. Use the `Datasources.get()` method to retrieve that identifies for the data sources on the server. + + +**Returns** + +An updated `DatasourceItem`. + + +**Example** + +```py +# from server-client-python/test/test_datasource.py + + ... + + single_datasource = TSC.DatasourceItem('test', '1d0304cd-3796-429f-b815-7258370b9b74') + single_datasource._id = '9dbd2263-16b5-46e1-9c43-a76bb8ab65fb' + single_datasource._tags = ['a', 'b', 'c'] + single_datasource._project_name = 'Tester' + updated_datasource = self.server.datasources.update(single_datasource) + + ... + +``` + Source files: server/endpoint/datasources_endpoint.py, models/datasource_item.py + + + + + + +

From 5ae1a3cdc9284a14805db143d366dc09c652f745 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Fri, 24 Mar 2017 16:30:02 -0700 Subject: [PATCH 03/17] Another chekin' for the cause --- docs/docs/api-ref.md | 77 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 5cbb9dd85..6363ca017 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -293,7 +293,7 @@ workbook_obj.connections ## Views Using the TSC library, you can get all the views on a site, or get the views for a workbook, or populate a view with preview images. -The view resources for Tableau Server are defined in the ViewItem class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, information about the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the `ViewItem` class. +The view resources for Tableau Server are defined in the ViewItem class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, you can find the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the `ViewItem` class.
@@ -409,7 +409,7 @@ See [ViewItem class](#viewitem-class) ## Data sources Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project. -The data source resources for Tableau Server are defined in the DatasourceItem class. The class corresponds to the data source resources you can access using the Tableau Server REST API, for example, information about the name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the DatasourceItem class. +The data source resources for Tableau Server are defined in the `DatasourceItem` class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the `DatasourceItem` class.
@@ -772,7 +772,78 @@ Source files: server/endpoint/datasources_endpoint.py, models/datasource_item.py ## Users -Source files: server/endpoint/users_endpoint.py, models/user_item.py +Using the TSC library, you can get information about all the users on a site, and you can add or remove users, or update user information. + +The user resources for Tableau Server are defined in the `UserItem` class. The class corresponds to the user resources you can access using the Tableau Server REST API. The user methods are based upon the endpoints for users in the REST API and operate on the `UserItem` class. + + +### UserItem class + +```py +UserItem(name, site_role, auth_setting=None) +``` + +**Attributes** + +`auth_setting` : This attribute is only returned for Tableau Online. +`domain_name` : +`external_auth_user_id` : +`id` : +`last_login` : +`workbooks` : The workbooks +`email` : The email address of the user. +`fullname` : The full name of the user. +`name` : The name of the user. This attribute is required when you are creating a `UserItem` instance. +`site_role` : The role the user has on the site. This attribute is required with you are creating a `UserItem` instance. The `site_role` can be one of the following: `Interactor`, `Publisher`, `ServerAdministrator`, `SiteAdministrator`, `Unlicensed`, `UnlicensedWithPublish`, `Viewer`, `ViewerWithPublish`, `Guest` + + +Source file: models/user_item.py + +
+
+ + +### User Methods + +The Tableau Server Client provides several methods for interacting with user resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. + +
+
+ +#### add() + +```py +users.get(req_options=None) +``` + +Returns all the users for the site. + +**Parameters** + +`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. + + +**Returns** + +Returns a list of `UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. + + + + +**Example** + +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('http://SERVERURL') + +with server.auth.sign_in(tableau_auth): + all_users, pagination_item = server.users.get() + print("\nThere are {} user on site: ".format(pagination_item.total_available)) + print([user.name for user in all_users]) +```` + +Source file: server/endpoint/users_endpoint.py
From f0c5d513367eabe22a68ea733e6f93794f0f18d1 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Mon, 27 Mar 2017 19:25:22 -0700 Subject: [PATCH 04/17] Check in more stuff; added api buckets in docs menu --- docs/_includes/docs_menu.html | 34 ++++- docs/docs/api-ref.md | 274 +++++++++++++++++++++++++++++----- 2 files changed, 268 insertions(+), 40 deletions(-) diff --git a/docs/_includes/docs_menu.html b/docs/_includes/docs_menu.html index 13679b6fe..c73eb128d 100644 --- a/docs/_includes/docs_menu.html +++ b/docs/_includes/docs_menu.html @@ -22,8 +22,38 @@ Samples
  • - API Reference -
    • + API Reference + + +
  • Developer Guide
    • diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 6363ca017..68dd6fb8d 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -338,9 +338,9 @@ Source file: server/endpoint/views_endpoint.py

    -#### get() +#### views.get() ``` -Views.get(req_option=None) +views.get(req_option=None) ``` Returns the list of views items for a site. @@ -376,10 +376,10 @@ See [ViewItem class](#viewitem-class)

    -#### populate_preview_image(*view_item*) +#### views.populate_preview_image(*view_item*) ```py - Views.populate_preview_image(view_item) + views.populate_preview_image(view_item) ``` @@ -469,7 +469,7 @@ Source file: server/endpoint/datasources_endpoint.py

    -#### delete(*datasource_id*) +#### ds.delete(*datasource_id*) ```py datasources.delete(datasource_id) @@ -494,7 +494,7 @@ REST API: [Delete Datasource](http://onlinehelp.tableau.com/v0.0/api/rest_api/en
    -#### download(*datasource_id*, *filepath=None*) +#### ds.download(*datasource_id*, *filepath=None*) ```py datasources.download(datasource_id, filepath=None) @@ -525,7 +525,7 @@ REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_a

    -#### get() +#### ds.get() ```py datasources.get(req_options=None) @@ -568,7 +568,7 @@ with server.auth.sign_in(tableau_auth):
    -#### get_by_id(*datasource_id*) +#### ds.get_by_id(*datasource_id*) ```py datasources.get_by_id(datasource_id) @@ -597,7 +597,8 @@ The `DatasourceItem`. See [DatasourceItem class](#datasourceitem-class) **Example** ```py -datasource = server.datasources.get_by_id(server.datasources[1].id) + +datasource = server.datasources.get_by_id('59a57c0f-3905-4022-9e87-424fb05e9c0e') print(datasource.name) ``` @@ -608,7 +609,7 @@ print(datasource.name) -#### populate_connections(*datasource_item*) +#### ds.populate_connections(*datasource_item*) ```py datasources.populate_connections(datasource_item) @@ -643,18 +644,29 @@ None. A list of `ConnectionItem` objects are added to the data source (`datasour **Example** ```py -datasource = server.datasources.get_by_id(server.datasources[1].id) -print(datasource.name) +# import tableauserverclient as TSC +# server = TSC.Server('http://SERVERURL') +# + ... + + all_datasources, pagination_item = server.datasources.get() + datasource = server.datasources.get_by_id(all_datasources[1].id) + print(datasource.name) + + server.datasources.populate_connections(datasource) + print(datasource.connections[0].connection_type) + print(datasource.connections[0].id) + print(datasource.connections[0].server_address) + + ... -server.datasources.populate_connections(datasource) -print([connection.datasource_name for connection in datasource.connections]) ```

    -#### publish(*datasource_item*, *file_path*, *mode*, *connection_credentials=None*) +#### ds.publish(*datasource_item*, *file_path*, *mode*, *connection_credentials=None*) ```py datasources.publish(datasource_item, file_path, mode, connection_credentials=None) @@ -695,18 +707,20 @@ The `DatasourceItem` for the data source that was added or appened to. **Example** ```py - import tableauserverclient as TSC - # server = TSC.Server('server') - # project_id = '3a8b6148-493c-11e6-a621-6f3499394a39' - # file_path = 'C:\\temp\\WorldIndicators.tde' - ... + import tableauserverclient as TSC + server = TSC.Server('http://SERVERURL') + + ... - # Use the default project id to create new datsource_item - new_datasource = TSC.DatasourceItem(project_id) + project_id = '3a8b6148-493c-11e6-a621-6f3499394a39' + file_path = 'C:\\temp\\WorldIndicators.tde' - # publish data source - new_datasource = server.datasources.publish( + # Use the project id to create new datsource_item + new_datasource = TSC.DatasourceItem(project_id) + + # publish data source (specifed in file_path) + new_datasource = server.datasources.publish( new_datasource, file_path, 'CreateNew') ... @@ -715,7 +729,7 @@ The `DatasourceItem` for the data source that was added or appened to.

    -#### update(*datasource_item*) +#### ds.update(*datasource_item*) ```py datasource.update(datasource_item) @@ -785,18 +799,33 @@ UserItem(name, site_role, auth_setting=None) **Attributes** -`auth_setting` : This attribute is only returned for Tableau Online. -`domain_name` : -`external_auth_user_id` : -`id` : -`last_login` : -`workbooks` : The workbooks -`email` : The email address of the user. -`fullname` : The full name of the user. +`auth_setting` : (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for this attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. + +`domain_name` : The name of the site. +`external_auth_user_id` : Represents ID stored in Tableau's single sign-on (SSO) system. The `externalAuthUserId` value is returned for Tableau Online. For other server configurations, this field contains null. +`id` : The id of the user on the site. +`last_login` : The date and time the user last logged in. +`workbooks` : The workbooks the user owns. You must run the populate_workbooks method to add the workbooks to the `UserItem`. + +`email` : The email address of the user. +`fullname` : The full name of the user. `name` : The name of the user. This attribute is required when you are creating a `UserItem` instance. `site_role` : The role the user has on the site. This attribute is required with you are creating a `UserItem` instance. The `site_role` can be one of the following: `Interactor`, `Publisher`, `ServerAdministrator`, `SiteAdministrator`, `Unlicensed`, `UnlicensedWithPublish`, `Viewer`, `ViewerWithPublish`, `Guest` +**Example** + +```py +# import tableauserverclient as TSC +# server = TSC.Server('server') + +# create a new UserItem object. + newU = TSC.UserItem('Monty', 'Publisher') + + print(newU.name, newU.site_role) + +``` + Source file: models/user_item.py
    @@ -810,28 +839,72 @@ The Tableau Server Client provides several methods for interacting with user res

    -#### add() +#### users.add(*user_item*) ```py -users.get(req_options=None) +users.add(user_item) ``` -Returns all the users for the site. +Adds the user to the site. + +To add a new user to the site you need to first create a new `user_item` (from `UserItem` class). When you create a new user, you specify the name of the user and their site role. For Tableau Online, you also specify the `auth_setting` attribute in your request. When you add user to Tableau Online, the name of the user must be the email address that is used to sign in to Tableau Online. After you add a user, Tableau Online sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password. + +REST API: [Add User to Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Add_User_to_Site%3FTocPath%3DAPI%2520Reference%7C_____9){:target="_blank"} **Parameters** -`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. +`user_item` : You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. **Returns** -Returns a list of `UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. +Returns the new `UserItem` object. + + + + +**Example** + +```py +# import tableauserverclient as TSC +# server = TSC.Server('server') +# login, etc. + +# create a new UserItem object. + newU = TSC.UserItem('Monty', 'Publisher') + +# add the new user to the site + newU = server.users.add(newU) + print(newU.name, newU.site_role) + +``` + +### users.get() + +```py +users.get(req_options=None) +``` + +Returns information about the users on the specified site. + +To get information about the workbooks a user owns or has view permission for, you must first populate the `UserItem` with workbook information using the [populate_workbooks(*user_item*)](#populate-workbooks-user) method. + + +REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} + +**Parameters** + +``req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. +**Returns** + +Returns a list of UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. **Example** + ```py import tableauserverclient as TSC tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') @@ -843,6 +916,131 @@ with server.auth.sign_in(tableau_auth): print([user.name for user in all_users]) ```` + +#### users.get_by_id(*user_id*) + + +```py +users.get_by_id(user_id) +``` + +Returns information about the specified user. + +REST API: [Query User On Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_User_On_Site%3FTocPath%3DAPI%2520Reference%7C_____61){:target="_blank"} + + +**Parameters** + +`user_id` : The `user_id` specifies the user to query. + + +**Exceptions** + +`User ID undefined.` : Raises an exception if a valid `user_id` is not provided. + + +**Returns** + +The `UserItem`. See [UserItem class](#useritem-class) + + +**Example** + +```py +user1 = server.users.get_by_id('6de21c06-c936-47a1-8f92-ed2e9512e6ab') +print(user1.name) + +``` + +
    +
    + + +#### users.populate_favorites_ + +```py +users.populate_favorites(user_item) +``` + +Returns the list of favorites (views, workbooks, and data sources) for a user. + +*Not currently implemented* + +
    +
    + + +#### users.populate_workbooks(*user_item*, *req_options=None*) + +```py +users.populate_workbooks(user_item, req_options=None): +``` + +Returns information about the workbooks that the specified user owns and has Read (view) permissions for. + + +This method retrieves the workbook information for the specified user. The REST API is designed to return only the information you ask for explicitly. When you query for all the users, the workbook information for each user is not included. Use this method to retrieve information about the workbooks that the user owns or has Read (view) permissions. The method adds the list of workbooks to the user item object (`user_item.workbooks`). + +REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47){:target="_blank"} + +**Parameters** + +`user_item` : The `user_item` specifies the user to populate with workbook information. + + + + +**Exceptions** + +`User item missing ID.` : Raises an errror if the `user_item` is unspecified. + + +**Returns** + +A list of `WorkbookItem` + +A `PaginationItem` that points (`user_item.workbooks`). See [UserItem class](#useritem-class) + + +**Example** + +```py + pagn = server.users.populate_workbooks(all_users[0]) + print("\nUser {0} owns or has READ permissions for {1} workbooks".format(all_users[0].name, pagn.total_available)) + print("\nThe workbooks are:") + for workbook in all_users[0].workbooks : + print(workbook.name) +``` + + + + +
    +
    + +#### users.remove(*user_id*) + +```py +users.remove(user_id): + if not user_id: + error = "User ID undefined." +``` + + + + +
    +
    + + +#### users.update + +```py +users.update(user_item, password=None) +``` + + + Source file: server/endpoint/users_endpoint.py From f52429a9cfd276a3807a6c5cea82ee584eaf5cc1 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Tue, 28 Mar 2017 20:39:08 -0700 Subject: [PATCH 05/17] Updated with users, groups; snapshot --- docs/docs/api-ref.md | 477 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 452 insertions(+), 25 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 68dd6fb8d..a6e8e1265 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -293,7 +293,7 @@ workbook_obj.connections ## Views Using the TSC library, you can get all the views on a site, or get the views for a workbook, or populate a view with preview images. -The view resources for Tableau Server are defined in the ViewItem class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, you can find the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the `ViewItem` class. +The view resources for Tableau Server are defined in the `ViewItem` class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, you can find the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the `ViewItem` class.
    @@ -305,7 +305,7 @@ class ViewItem(object) ``` -The ViewItem class contains the members or attributes for the view resources on Tableau Server. The ViewItem class defines the information you can request or query from Tableau Server. The class members correspontd to the attributes of a server request or response payload. +The `ViewItem` class contains the members or attributes for the view resources on Tableau Server. The `ViewItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. Source file: models/view_item.py @@ -329,7 +329,7 @@ Source file: models/view_item.py
    -### View methods +### Views methods The Tableau Server Client provides two methods for interacting with view resources, or endpoints. These methods correspond to the endpoints for views in the Tableau Server REST API. @@ -460,7 +460,7 @@ Source file: models/datasource_item.py

    -### Datasource methods +### Datasources methods The Tableau Server Client provides several methods for interacting with data source resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. @@ -502,6 +502,7 @@ datasources.download(datasource_id, filepath=None) ``` Downloads the specified data source in `.tdsx` format. +REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Datasource%3FTocPath%3DAPI%2520Reference%7C_____34){:target="_blank"} **Parameters** @@ -520,7 +521,7 @@ Downloads the specified data source in `.tdsx` format. The data source in `.tdsx` format. -REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Datasource%3FTocPath%3DAPI%2520Reference%7C_____34){:target="_blank"} +

    @@ -645,15 +646,19 @@ None. A list of `ConnectionItem` objects are added to the data source (`datasour ```py # import tableauserverclient as TSC + # server = TSC.Server('http://SERVERURL') # ... - all_datasources, pagination_item = server.datasources.get() - datasource = server.datasources.get_by_id(all_datasources[1].id) - print(datasource.name) +# get the data source + datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') + +# get the connection information server.datasources.populate_connections(datasource) + +# print the information about the first connection item print(datasource.connections[0].connection_type) print(datasource.connections[0].id) print(datasource.connections[0].server_address) @@ -797,6 +802,8 @@ The user resources for Tableau Server are defined in the `UserItem` class. The c UserItem(name, site_role, auth_setting=None) ``` +The `UserItem` class contains the members or attributes for the view resources on Tableau Server. The `UserItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. + **Attributes** `auth_setting` : (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for this attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. @@ -832,10 +839,11 @@ Source file: models/user_item.py
    -### User Methods +### Users Methods The Tableau Server Client provides several methods for interacting with user resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. +Source file: server/endpoint/users_endpoint.py

    @@ -871,7 +879,7 @@ Returns the new `UserItem` object. # login, etc. # create a new UserItem object. - newU = TSC.UserItem('Monty', 'Publisher') + newU = TSC.UserItem('Heather', 'Publisher') # add the new user to the site newU = server.users.add(newU) @@ -879,7 +887,7 @@ Returns the new `UserItem` object. ``` -### users.get() +### users.get ```py users.get(req_options=None) @@ -899,7 +907,7 @@ REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/ **Returns** -Returns a list of UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. +Returns a list of `UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. **Example** @@ -916,6 +924,8 @@ with server.auth.sign_in(tableau_auth): print([user.name for user in all_users]) ```` +
    +
    #### users.get_by_id(*user_id*) @@ -947,8 +957,8 @@ The `UserItem`. See [UserItem class](#useritem-class) **Example** ```py -user1 = server.users.get_by_id('6de21c06-c936-47a1-8f92-ed2e9512e6ab') -print(user1.name) + user1 = server.users.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + print(user1.name) ``` @@ -956,7 +966,7 @@ print(user1.name)
    -#### users.populate_favorites_ +#### users.populate_favorites ```py users.populate_favorites(user_item) @@ -1005,11 +1015,17 @@ A `PaginationItem` that points (`user_item.workbooks`). See [UserItem class](#us **Example** ```py - pagn = server.users.populate_workbooks(all_users[0]) - print("\nUser {0} owns or has READ permissions for {1} workbooks".format(all_users[0].name, pagn.total_available)) +# first get all users, call server.users.get() +# get workbooks for user[0] + ... + + page_n = server.users.populate_workbooks(all_users[0]) + print("\nUser {0} owns or has READ permissions for {1} workbooks".format(all_users[0].name, page_n.total_available)) print("\nThe workbooks are:") for workbook in all_users[0].workbooks : - print(workbook.name) + print(workbook.name) + + ... ``` @@ -1021,27 +1037,107 @@ A `PaginationItem` that points (`user_item.workbooks`). See [UserItem class](#us #### users.remove(*user_id*) ```py -users.remove(user_id): - if not user_id: - error = "User ID undefined." +users.remove(user_id) ``` +Removes the specified user from the site. -
    +REST API: [Remove User from Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Site%3FTocPath%3DAPI%2520Reference%7C_____74){:target="_blank"} + + +**Parameters** + +`user_id` : The identifier (`id`) for the the user that you want to remove from the server. + + +**Exceptions** + +`User ID undefined` : Raises an exception if a valid `user_id` is not provided. + + +**Example** + +```py +# Remove a user from the site + +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + with server.auth.sign_in(tableau_auth): + server.users.remove('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + +``` +

    -#### users.update + + +#### users.update(*user_item*, *password=None*) ```py users.update(user_item, password=None) ``` +Updates information about the specified user. +The information you can modify depends upon whether you are using Tableau Server or Tableau Online, and whether you have configured Tableau Server to use local authentication or Active Directory. For more information, see [Update User](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_User%3FTocPath%3DAPI%2520Reference%7C_____86){:target="_blank"}. + + + +REST API: [Update User](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_User%3FTocPath%3DAPI%2520Reference%7C_____86){:target="_blank"} + +**Parameters** + +`user_item` : The `user_item` specifies the user to update. + +`password` : (Optional) The new password for the user. + + + +**Exceptions** + +`User item missing ID.` : Raises an errror if the `user_item` is unspecified. + + +**Returns** + +An updated `UserItem`. See [UserItem class](#useritem-class) + + +**Example** + +```py + +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + with server.auth.sign_in(tableau_auth): + + # create a new user_item + user1 = TSC.UserItem('temp', 'Viewer') + + # add new user + user1 = server.users.add(user1) + print(user1.name, user1.site_role, user1.id) + + # modify user info + user1.name = 'Laura' + user1.fullname = 'Laura Rodriguez' + user1.email = 'laura@example.com' + + # update user + user1 = server.users.update(user1) + print("\Updated user info:") + print(user1.name, user1.fullname, user1.email, user1.id) + + +``` -Source file: server/endpoint/users_endpoint.py
    @@ -1049,10 +1145,341 @@ Source file: server/endpoint/users_endpoint.py ## Groups -Source files: server/endpoint/groups_endpoint.py, models/group_item.py +Using the TSC library, you can get information about all the groups on a site, you can add or remove groups, or add or remove users in a group. + +The group resources for Tableau Server are defined in the `GroupItem` class. The class corresponds to the user resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the `GroupItem` class. + +
    +
    + +### GroupItem class + +```py +GroupItem(name) +``` + +The `GroupItem` class contains the members or attributes for the view resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. + +Source file: models/group_item.py + +**Attributes** + +`domain_name` : The name of the Active Directory domain (`local` if local authentication is used). +`id` : The id of the group. +`users` : The list of users (`UserItem`). +`name` : The name of the group. The `name` is required when you create an instance of a group. + + + +**Example** + +```py + newgroup = TSC.GroupItem('My Group') +``` + + + + +
    +
    + +### Groups methods + +The Tableau Server Client provides several methods for interacting with group resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. + + + +Source file: server/endpoint/groups_endpoint.py + +
    +
    + +#### groups.add_user + +```py +groups.add_user(group_item, user_id): +``` + +Adds a user to the specified group. + + +REST API [Add User to Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Add_User_to_Group%3FTocPath%3DAPI%2520Reference%7C_____8){:target="_blank"} + +**Parameters** + +`group_item` : The `group_item` specifies the group to update. + +`user_id` : The id of the user. + + + + +**Returns** + +None. + + +**Example** + +```py +# Adding a user to a group +# Using the second group on the site, aleady have all_groups +# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba' + +# add Ian to the second group + server.groups.add_user(all_groups[1], '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba') + +# populate the GroupItem with the users + pagination_item = server.groups.populate_users(all_groups[1]) + + for user in all_groups[1].users : + print(user.name) + +``` + +
    +
    + +#### groups.create + +```py +create(group_item) +``` + +Creates a new group in Tableau Server. + + +REST API: [Create Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Group%3FTocPath%3DAPI%2520Reference%7C_____14){:target="_blank"} + + +**Parameters** + +`group_item` : The `group_item` specifies the group to add. You first create a new instance of a `GroupItem` and pass that to this method. + + + + +**Returns** +Adds new `GroupItem`. + + +**Example** + +```py + +# Create a new group + +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + +# create a new instance with the group name + newgroup = TSC.GroupItem('My Group') + +# call the create method + newgroup = server.groups.create(newgroup) + +# print the names of the groups on the server + all_groups, pagination_item = server.groups.get() + for group in all_groups : + print(group.name, group.id) +``` + +
    +
    + +#### groups.delete + +```py +groups.delete(group_id) +``` + +Deletes the group on the site. + +REST API: [Delete Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Site%3FTocPath%3DAPI%2520Reference%7C_____74){:target="_blank"} + + +**Parameters** + +`group_id` : The identifier (`id`) for the the group that you want to remove from the server. + + +**Exceptions** + +`Group ID undefined` : Raises an exception if a valid `group_id` is not provided. + + +**Example** + +```py +# Delete a group from the site + +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + with server.auth.sign_in(tableau_auth): + server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') + +``` +
    +
    + +#### groups.get + +```py +groups.get(req_options=None) +``` + +Returns information about the groups on the site. + +To get information about the users in a group, you must first populate the `GroupItem` with user information using the [groups.populate_users](api-ref#groupspopulateusers) method. + + +REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} + +**Parameters** + +`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific groups, you could specify the name of the group or the group id. + + +**Returns** + +Returns a list of `GroupItem` objects and a `PaginationItem` object. Use these values to iterate through the results. + + +**Example** + + +```py +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + with server.auth.sign_in(tableau_auth): + + # get the groups on the server + all_groups, pagination_item = server.groups.get() + + # print the names of the groups + for group in all_groups : + print(group.name, group.id) +````

    +#### groups.populate_users + +```py +groups.populate_users(group_item, req_options=None) +``` + +Populates the `group_item` with the list of users. + + +REST API: [Get Users in Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_in_Group){:target="_blank"} + +**Parameters** + +`group_item` : The `group_item` specifies the group to populate with user information. + +`req_options` : (Optional) Additional request options to send to the endpoint. + + + +**Exceptions** + +`Group item missing ID. Group must be retrieved from server first.` : Raises an errror if the `group_item` is unspecified. + + +**Returns** + +None. A list of `UserItem` objects are added to the group (`group_item.users`). + + +**Example** + +```py +# import tableauserverclient as TSC + +# server = TSC.Server('http://SERVERURL') +# + ... + +# get the group + mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') + + +# get the user information + pagination_item = server.groups.populate_users(mygroup) + + +# print the information about the first connection item + for user in mygroup.users : + print(user.name) + + + + +``` + +
    +
    + +#### groups.remove_user + +```py +groups.remove_user(group_item, user_id) +``` + +Removes a user from a group. + + + + +REST API: [Remove User from Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Group%3FTocPath%3DAPI%2520Reference%7C_____73){:target="_blank"} + + +**Parameters** + +`group_item` : The `group_item` specifies the group to remove the user from. + +`user_id` : The id for the user. + + + +**Exceptions** + +`Group must be populated with users first.` : Raises an errror if the `group_item` is unpopulated. + + +**Returns** + +None. The user is removed from the group. + + +**Example** + +```py +# Remove a user from the group + +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + with server.auth.sign_in(tableau_auth): + + # get the group + mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') + + # remove user '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d' + server.groups.remove_user(mygroup, '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + +``` + +
    +
    From fef93e458383ee8aca1ec74a7e9ce15c74799bd6 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Thu, 6 Apr 2017 18:10:01 -0700 Subject: [PATCH 06/17] Check in more changes to ref pages, minor fix for docs menu --- docs/_includes/docs_menu.html | 72 +++-- docs/docs/api-ref.md | 583 +++++++++++++++++++++++++++++++--- 2 files changed, 581 insertions(+), 74 deletions(-) diff --git a/docs/_includes/docs_menu.html b/docs/_includes/docs_menu.html index c73eb128d..222b86e6b 100644 --- a/docs/_includes/docs_menu.html +++ b/docs/_includes/docs_menu.html @@ -22,40 +22,42 @@ Samples
  • - API Reference -
    • - - -
  • - Developer Guide -
    • + API Reference + + +
  • + Developer Guide +
    • diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index a6e8e1265..6b138729c 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -14,109 +14,614 @@ layout: docs ## Authentication -Source files: server/endpoint/auth_endpoint.py, models/tableau_auth.py +You can use the TSC library to manage authentication, so you can sign in and sign out of Tableau Server and Tableau Online. The authentication resources for Tableau Server are defined in the `TableauAuth` class and they correspond to the authentication attributes you can access using the Tableau Server REST API. -### Sign In +
    +
    + +### TableauAuth class + +```py +TableauAuth(username, password, site=None, site_id='', user_id_to_impersonate=None) +``` +The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method. + +**Attributes** +`username` : The name of the user whose credentials will be used to sign in. +`password` : The password of the user. +`site` : (Deprecated) Use `site_id` instead. +`site_id` : This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string **""**. For Tableau Online, you must provide a value for the `site_id`. +`user_id_to_impersonate` : Specifies the id (not the name) of the user to sign in as. + +Source file: models/tableau_auth.py + +**Example** + +```py +import tableauserverclient as TSC +# create a new instance of a TableauAuth object for authentication + +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') + +# create a server instance +# pass the "tableau_auth" request object to server.auth.sign_in() +``` + +
    +
    + +### Auth methods +The Tableau Server Client provides two methods for interacting with authentication resources. These methods correspond to the sign in and sign out endpoints in the Tableau Server REST API. + + +Source file: server/endpoint/auth_endpoint.py + +
    +
    + +#### auth.sign in + +```py +auth.sign_in(auth_req) +``` Signs you in to Tableau Server. + +The method signs into Tableau Server or Tableau Online and manages the authentication token. You call this method from the server object you create. For information about the server object, see [Server](#server). The authentication token keeps you signed in for 240 minutes, or until you call the `auth.sign_out` method. Before you use this method, you first need to create the sign-in request (`auth_req`) by creating an instance of the `TableauAuth`. To call this method, create a server object for your server. For more information, see [Sign in and Out](sign-in-out). + +REST API: [Sign In](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_In%3FTocPath%3DAPI%2520Reference%7C_____77){:target="_blank"} + +**Parameters** + +`auth_req` : The `TableauAuth` object that holds the sign-in credentials for the site. + + +**Example** + +```py +import tableauserverclient as TSC + +# create a auth request +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') + +# create an instance for your server +server = TSC.Server('http://SERVER_URL') + +# call the sign-in method with the request +server.auth.sign_in(tableau_auth) + +``` + + +**See Also** +[Sign in and Out](sign-in-out) +[Server](#server) + +
    +
    + + +#### auth.sign out + ```py -Auth.sign_in(authentication_object) +auth.sign_out() ``` +Signs you out of the current session. -### Sign Out +The method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out). -Signs you out of Tableau Server. +REST API: [Sign Out](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_Out%3FTocPath%3DAPI%2520Reference%7C_____78){:target="_blank"} + +**Example** ```py -Auth.sign_out() + +server.auth.sign_out() + + ``` -## Connection + + + +**See Also** +[Sign in and Out](sign-in-out) +[Server](#server) + +
    +
    + + + + +## Connections + +The connections for Tableau Server data sources and workbooks are represented by a `ConnectionItem` class. You can call data source and view methods to query or update the connection information. The `ConnectionCredentials` class represents the connection information you can update. ### ConnectionItem class ```py -class ConnectionItem(object) +ConnectionItem(object) +``` + +**Attributes** + +`datasource_id` : The identifier of the data source. + +`datasource_name` : The name of the data source. + +`id` : The identifer of the connection. + +`connection_type` : The type of connection. + + +Source file: models/connection_item.py + +
    +
    + + + +### ConnectionCredentials class + +```py +ConnectionCredentials(name, password, embed=True, oauth=False) ``` + +The `ConnectionCredentials` class corresponds to workbook and data source connections. + +In the Tableau Server REST API, there are separate endopoints to query and update workbook and data source connections. + **Attributes** -`datasource_id` : +Attribute | Description +:--- | :--- +`name` | The username for the connection. +`embed_password` | (Boolean) Determines whether to embed the passowrd (`True`) for the workbook or data source connection or not (`False`). +`password` | The password used for the connection. +`server_address` | The server address for the connection. +`server_port` | The port used by the server. +`ouath` | (Boolean) Specifies whether OAuth is used for the data source of workbook connection. For more information, see [OAuth Connections](https://onlinehelp.tableau.com/current/server/en-us/protected_auth.htm?Highlight=oauth%20connections){:target="_blank"}. + + +Source file: models/connection_credentials.py + +
    +
    + +## Server + +In the Tableau REST API, the server (`http://MY-SERVER/`) is the base or core of the URI that makes up the various endpoints or methods for accessing resources on the server (views, workbooks, sites, users, data sources, etc.) +The TSC library provides a `Server` class that represents the server. You create a server instance to sign in to the server and to call the various methods for accessing resources. + + +
    +
    + + +### Server class + +```py +Server(server_address) +``` +The `Server` class contains the attributes that represent the server on Tableau Server. After you create an instance of the `Server` class, you can sign in to the server and call methods to access all of the resources on the server. + +**Attributes** + +`server_address` : Specifies the address of the Tableau Server or Tableau Online (for example, `http://MY-SERVER/`). + +`version` : Specifies the version of the REST API to use (for example, `2.5`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to 2.3, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_versions.htm){:target="_blank"} + + + +**Example** + +```py +import tableauserverclient as TSC + +# create a instance of server +server = TSC.Server('http://MY-SERVER') + + +# change the REST API version to 2.5 +server.version = 2.5 + + +``` + +#### Server.*Resources* (Objects) + +When you create an instance of the `Server` class, you have access to the resources on the server after you sign in. You can select these resources and their methods as members of the class, for example: `server.views.get()` -`datasource_name` : -`id` : -`connection_type` : +Resource | Description | + --- | ---| +*server*.auth | Sets authentication for sign in and sign out. See [Auth](#auththentication) | +*server*.views | Access the server views and methods. See [Views](#views) +*server*.users | Access the user resources and methods. See [Users](#users) +*server*.sites | Access the sites. See [Sites](#sites) +*server*.groups | Access the groups resources and methods. See [Groups](#groups) +*server*.workbooks | Access the resources and methods for workbooks. See [Workbooks](#workbooks) +*server*.datasources | Access the resources and methods for data sources. See [Data Sources](#data-sources) +*server*.projects | Access the resources and methods for projects. See [Projects](#projets) +*server*.schedules | Access the resources and methods for schedules. See [Schedules](#Schedules) +*server*.server_info | Access the resources and methods for server information. See [ServerInfo class](#serverinfo-class) + +
    +
    -`embed_password` : +#### Server.PublishMode -`password` : +The `Server` class has `PublishMode` class that enumerates the options that specify what happens when you publish a workbook or data source. The options are `Overwrite`, `Append`, or `CreateNew`. -`server_address` : -`server_port` : +**Properties** -`username` : +`PublishMode.Overwrite` : The `Server` class has `PublishMode` class that you can set to specify what happens when you publish a workbook or data source. The options are `Overwrite`, `Append`, or `CreateNew`. +**Example** + +```py + + print(TSC.Server.PublishMode.Overwrite) + # prints 'Overwrite' + + overwrite_true = TSC.Server.PublishMode.Overwrite + + ... + + # pass the PublishMode to the publish workbooks method + new_workbook = server.workbooks.publish(new_workbook, args.filepath, overwrite_true) + + +``` -Source file: models/connection_item.py

    + +### ServerInfoItem class + +```py +ServerInfoItem(product_version, build_number, rest_api_version) +``` +The `ServerInfoItem` class contains the builid and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class. + +**Attributes** + +`product_version` : Shows the version of the Tableau Server or Tableau Online (for example, 10.2.0). +`build_number` : Shows the specific build number (for example, 10200.17.0329.1446). +`rest_api_version` : Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the `Server.version` attribute. To take advantage of new features, you should query the server and set the `Server.version` to match the supported REST API version number. + + +
    +
    + + +### ServerInfo methods + +The TSC library provides a method to access the build and version information from Tableau Server. + +
    + +#### server_info.get + +```py +server_info.get() + +``` +Retrieve the build and version information for the server. + +This method makes an unauthenticated call, so no sign in or authentication token is required. + +REST API: [Server Info](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Server_Info%3FTocPath%3DAPI%2520Reference%7C_____76){:target="_blank"} + +**Parameters** + None + +**Exceptions** + +`404003 UNKNOWN_RESOURCE` : Raises an exception if the server info endpoint is not found. + +**Example** + +```py +import tableauserverclient as TSC + +# create a instance of server +server = TSC.Server('http://MY-SERVER') + +# set the version number > 2.3 +# the server_info.get() method works in 2.4 and later +server.version = '2.5' + +s_info = server.server_info.get() +print("\nServer info:") +print("\tProduct version: {0}".format(s_info.product_version)) +print("\tREST API version: {0}".format(s_info.rest_api_version)) +print("\tBuild number: {0}".format(s_info.build_number)) + +``` + + +
    +
    + + ## Sites +Using the TSC library, you can query a site or sites on a server, or create or delete a site on the server. + +The site resources for Tableau Server and Tableau Online are defined in the `SiteItem` class. The class corresponds to the site resources you can access using the Tableau Server REST API. The site methods are based upon the endpoints for sites in the REST API and operate on the `SiteItem` class. + +
    +
    + +### SiteItem class + +```py +SiteItem(name, content_url, admin_mode=None, user_quota=None, storage_quota=None, + disable_subscriptions=False, subscribe_others_enabled=True, revision_history_enabled=False) +``` + +The `SiteItem` class contains the members or attributes for the site resources on Tableau Server or Tableau Online. The `SiteItem` class defines the information you can request or query from Tableau Server or Tableau Online. The class members correspond to the attributes of a server request or response payload. + +**Attributes** + +Attribute | Description +:--- | :--- +`name` | The name of the site. The name of the default site is "". +`content_url` | The path to the site. +`admin_mode` | (Optional) For Tableau Server only. Specify `ContentAndUsers` to allow site administrators to use the server interface and **tabcmd** commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify `ContentOnly` to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.) +`user_quota`| (Optional) Specifies the maximum number of users for the site. If you do not specify this value, the limit depends on the type of licensing configured for the server. For user-based license, the maximum number of users is set by the license. For core-based licensing, there is no limit to the number of users. If you specify a maximum value, only licensed users are counted and server administrators are excluded. +`storage_quota` | (Optional) Specifes the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again. +`disable_subscriptions` | (Optional) Specify `true` to prevent users from being able to subscribe to workbooks on the specified site. The default is `false`. +`subscribe_others_enabled` | (Optional) Specify `false` to prevent server administrators, site administrators, and project or content owners from being able to subscribe other users to workbooks on the specified site. The default is `true`. +`revision_history_enabled` | (Optional) Specify `true` to enable revision history for content resources (workbooks and datasources). The default is `false`. +`revision_limit` | (Optional) Specifies the number of revisions of a content source (workbook or data source) to allow. On Tableau Server, the default is 25. +`state` | Shows the current state of the site (`Active` or `Suspended`). + + +**Example** + +```py + +# create a new instance of a SiteItem + +new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode='ContentAndUsers', user_quota=15, storage_quota=1000, disable_subscriptions=True) + +``` + Source files: server/endpoint/sites_endpoint.py, models/site_item.py -### Create Site +### sites.create + +```py +sites.create(site_item) +``` + +Creates a new site on the server for the specified site item object. + +Tableau Server only. + + +REST API: [Create Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Site%3FTocPath%3DAPI%2520Reference%7C_____17){:target="_blank"} + -Creates a new site for the given site item object. + +**Parameters** + +`site_item` : The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass the the `create` method. + + +**Returns** + +Returns a new instance of `SiteItem`. + + +**Example** ```py -Sites.create(new_site_item) +import tableauserverclient as TSC + +# create an instance of server +server = TSC.Server('http://MY-SERVER') + +# create shortcut for admin mode +content_users=TSC.SiteItem.AdminMode.ContentAndUsers + +# create a new SiteItem +new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode=content_users, user_quota=15, storage_quota=1000, disable_subscriptions=True) + +# call the sites create method with the SiteItem +new_site = server.sites.create(new_site) ``` +
    +
    -Example: + +### sites.get_by_id ```py -new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode=TSC.SiteItem.AdminMode.ContentAndUsers, user_quota=15, storage_quota=1000, disable_subscriptions=True) -self.server.sites.create(new_site) +sites.get_by_id(site_id) ``` -### Get Site by ID +Queries the site with the given ID. + + +REST API: [Query Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Site){:target="_blank"} + +**Parameters** + +`site_id` | The id for the site you want to query. + + +**Exceptions** + +`Site ID undefined.` | Raises an error if an id is not specified. -Gets the site with the given ID. + +**Returns** + +Returns the `SiteItem`. + + +**Example** ```py -Sites.get_by_id(id) + +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. + + a_site = server.sites.get_by_id('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d') + print("\nThe site with id '9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d' is: {0}".format(a_site.name)) + ``` -### Get Sites +
    +
    -Gets the first 100 sites on the server. To get all the sites, use the Pager. +### sites.get ```py -Sites.get() +sites.get() ``` -### Update Site +Queries all the sites on the server. + + +REST API: [Query Sites](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Sites%3FTocPath%3DAPI%2520Reference%7C_____58){:target="_blank"} + + +**Parameters** -Modifies a site. The site item object must include the site ID and overrides all other settings. + None. + +**Returns** + +Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these values to iterate through the results. + + +**Example** ```py -Sites.update(site_item_object) +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. + + # query the sites + all_sites, pagination_item = server.sites.get() + + # print all the site names and ids + for site in TSC.Pager(server.sites): + print(site.id, site.name, site.content_url, site.state) + + ``` -### Delete Site +
    +
    -Deletes the site with the given ID. + +### sites.update ```py -Sites.delete(id) +sites.update(site_item) ``` +Modifies the settings for site. + + +The site item object must include the site ID and overrides all other settings. + + +REST API: [Update Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Site%3FTocPath%3DAPI%2520Reference%7C_____84){:target="_blank"} + + +**Parameters** + +`site_item` | The site item that you want to update. The settings specified in the site item override the current site settings. + + +**Exceptions** + +Error | Description +:--- | :--- +`Site item missing ID.` | The site id must be present and must match the id of the site you are updating. +`You cannot set admin_mode to ContentOnly and also set a user quota` | To set the `user_quota`, the `AdminMode` must be set to `ContentAndUsers` + + +**Returns** + +Returns the updated `site_item`. + + +**Example** + +```py +... + +# make some updates to an existing site_item +site_item.name ="New name" + +# call update +site_item = server.sites.update(site_item) + +... +``` + +
    +
    + + + + +### sites.delete + + +```py +Sites.delete(site_id) +``` + +Deletes the specified site. + + +REST API: [Delete Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Site%3FTocPath%3DAPI%2520Reference%7C_____27){:target="_name"} + + +**Parameters** + + +`site_id` | The id of the site that you want to delete. + + + +**Exceptions** + +Error | Description +:--- | :--- +`Site ID Undefined.` | The site id must be present and must match the id of the site you are deleting. + +**Example** +```py + +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. + +server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d') + +``` + +
    +
    + + ## Projects Source files: server/endpoint/projects_endpoint.py @@ -338,7 +843,7 @@ Source file: server/endpoint/views_endpoint.py

    -#### views.get() +#### views.get ``` views.get(req_option=None) ``` @@ -376,7 +881,7 @@ See [ViewItem class](#viewitem-class)

    -#### views.populate_preview_image(*view_item*) +#### views.populate_preview_image ```py views.populate_preview_image(view_item) @@ -1147,7 +1652,7 @@ An updated `UserItem`. See [UserItem class](#useritem-class) Using the TSC library, you can get information about all the groups on a site, you can add or remove groups, or add or remove users in a group. -The group resources for Tableau Server are defined in the `GroupItem` class. The class corresponds to the user resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the `GroupItem` class. +The group resources for Tableau Server are defined in the `GroupItem` class. The class corresponds to the group resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the `GroupItem` class.

    From f9a19719e7ae9ae28b157927998b55ea25dba52e Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Mon, 10 Apr 2017 18:56:48 -0700 Subject: [PATCH 07/17] more updates; formatting fixes, etc. --- docs/docs/api-ref.md | 442 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 351 insertions(+), 91 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 6b138729c..b91ec8d2e 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -27,11 +27,14 @@ TableauAuth(username, password, site=None, site_id='', user_id_to_impersonate=No The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method. **Attributes** -`username` : The name of the user whose credentials will be used to sign in. -`password` : The password of the user. -`site` : (Deprecated) Use `site_id` instead. -`site_id` : This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string **""**. For Tableau Online, you must provide a value for the `site_id`. -`user_id_to_impersonate` : Specifies the id (not the name) of the user to sign in as. + +Name | Description +:--- | :--- +`username` | The name of the user whose credentials will be used to sign in. +`password` | The password of the user. +`site` | (Deprecated) Use `site_id` instead. +`site_id` | This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string **" "**. For Tableau Online, you must provide a value for the `site_id`. +`user_id_to_impersonate` | Specifies the id (not the name) of the user to sign in as. Source file: models/tableau_auth.py @@ -41,7 +44,7 @@ Source file: models/tableau_auth.py import tableauserverclient as TSC # create a new instance of a TableauAuth object for authentication -tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL') # create a server instance # pass the "tableau_auth" request object to server.auth.sign_in() @@ -396,9 +399,23 @@ new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode='Conte ``` -Source files: server/endpoint/sites_endpoint.py, models/site_item.py +Source file: models/site_item.py + +
    +
    + + +### Sites methods -### sites.create +The TSC library provides methods that operate on sites for Tableau Server and Tableau Online. These methods correspond to endpoints or methods for sites in the Tableau REST API. + + +Source file: server/endpoint/sites_endpoint.py + +
    + + +#### sites.create ```py sites.create(site_item) @@ -444,7 +461,7 @@ new_site = server.sites.create(new_site)
    -### sites.get_by_id +#### sites.get_by_id ```py sites.get_by_id(site_id) @@ -486,7 +503,7 @@ Returns the `SiteItem`.

    -### sites.get +#### sites.get ```py sites.get() @@ -528,7 +545,7 @@ Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these value
    -### sites.update +#### sites.update ```py sites.update(site_item) @@ -581,7 +598,7 @@ site_item = server.sites.update(site_item) -### sites.delete +#### sites.delete ```py @@ -607,7 +624,8 @@ Error | Description :--- | :--- `Site ID Undefined.` | The site id must be present and must match the id of the site you are deleting. -**Example** +**Example** + ```py # import tableauserverclient as TSC @@ -621,77 +639,333 @@ server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d')

    + ## Projects -Source files: server/endpoint/projects_endpoint.py +Using the TSC library, you can get information about all the projects on a site, or you can create, update projects, or remove projects. + +The project resources for Tableau are defined in the `ProjectItem` class. The class corresponds to the project resources you can access using the Tableau Server REST API. The project methods are based upon the endpoints for projects in the REST API and operate on the `ProjectItem` class. + + + -### Create Project -Creates a project for the given project item object. +
    + +### ProjectItem class ```py -Projects.create(project_item_object) + +ProjectItem(name, description=None, content_permissions=None) + ``` +The project resources for Tableau are defined in the `ProjectItem` class. The class corresponds to the project resources you can access using the Tableau Server REST API. + +**Attributes** + +Name | Description +:--- | :--- +`content_permissions` | Sets or shows the permissions for the content in the project. The options are either `LockedToProject` or `ManagedByOwner`. +`name` | Name of the project. +`description` | The description of the project. +`id` | The project id. + + + +Source file: models/project_item.py + + +#### ProjectItem.ContentPermissions + +The `ProjectItem` class has a sub-class that defines the permissions for the project (`ProjectItem.ContentPermissions`). The options are `LockedToProject` and `ManagedByOwner`. For information on these content permissions, see [Lock Content Permissions to the Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Project%3FTocPath%3DAPI%2520Reference%7C_____15){:target="_blank"} + +Name | Description +:--- | :--- +`ProjectItem.ContentPermissions.LockedToProject` | Locks all content permissions to the project. +`ProjectItem.ContentPermissions.ManagedByOwner` | Users can manage permissions for content that they own. This is the default. + +**Example** + +```py + +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc + + +locked_true = TSC.ProjectItem.ContentPermissions.LockedToProject +print(locked_true) +# prints 'LockedToProject' + +by_owner = TSC.ProjectItem.ContentPermissions.ManagedByOwner +print(by_owner) +# prints 'ManagedByOwner' + + +# pass the content_permissions to new instance of the project item. +new_project = TSC.ProjectItem(name='My Project', content_permissions=by_owner, description='Project example') + +``` + +
    +
    + +### Projects methods + -Example: + + +Source files: server/endpoint/projects_endpoint.py + +
    +
    + + +#### projects.create ```py -new_project = TSC.ProjectItem(name='Test Project', description='Project created for testing') -new_project.content_permissions = 'ManagedByOwner' -self.server.projects.create(new_project) +projects.create(project_item) +``` + + +Creates a project on the specified site. + +To create a project, you first create a new instance of a `ProjectItem` and pass it to the create method. To specify the site to create the new project, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). + + +REST API: [Create Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Project%3FTocPath%3DAPI%2520Reference%7C_____15){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`project_item` | Specifies the properties for the project. The `project_item` is the request package. To create the request package, create a new instance of `ProjectItem`. + + +**Returns** +Returns the new project item. + + + +**Example** + +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL') +server = TSC.Server('http://SERVER') + +with server.auth.sign_in(tableau_auth): + # create project item + new_project = TSC.ProjectItem(name='Example Project', content_permissions='LockedToProject', description='Project created for testing') + # create the project + new_project = server.projects.create(new_project) + ``` -### Get Projects +
    +
    + + +#### projects.get ```py -Projects.get() +projects.get() + ``` -Get the first 100 projects on the server. To get all projects, use the Pager. +Return a list of project items for a site. + + +To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). + +REST API: [Query Projects](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Projects%3FTocPath%3DAPI%2520Reference%7C_____55){:target="_blank"} + + +**Parameters** + +None. + +**Returns** + +Returns a list of all `ProjectItem` objects and a `PaginationItem`. Use these values to iterate through the results. + + + + **Example** + +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL') +server = TSC.Server('http://SERVER') + +with server.auth.sign_in(tableau_auth): + # get all projects on site + all_project_items, pagination_item = server.projects.get() + print([proj.name for proj in all_project_items]) + +``` + +
    +
    + -### Update Project +#### projects.update ```py -Projects.update(project_item) +projects.update(project_item) ``` -Modify a project. +Modify the project settings. -You can use this method to update the project name, the project description, or the project permissions. +You can use this method to update the project name, the project description, or the project permissions. To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). -##### Parameters +REST API: [Update Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Project%3FTocPath%3DAPI%2520Reference%7C_____82){:target="_blank"} + +**Parameters** `project_item` The project item object must include the project ID. The values in the project item override the current project settings. -##### Returns + +**Exceptions** + +`Project item missing ID.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. + + +**Returns** Returns the updated project information. -See ProjectItem +See [ProjectItem class]() -### Delete Project +```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc -Deletes a project by ID. + ... + + all_project_items, pagination_item = server.projects.get() + print([prj.name for prj in all_project_items]) + + # update project item #7 with new name, etc. + all_projects[7].name ='New name' + all_projects[7].description = 'New description' + + # call method to update project + updated_proj = server.projects.update(all_projects[7]) + + + + +``` +
    +
    + + +#### projects.delete ```py -Projects.delete(id) +projects.delete(project_id) ``` +Deletes a project by ID. + + +To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). + + +REST API: [Delete Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Project%3FTocPath%3DAPI%2520Reference%7C_____24){:target="_blank"} + + +**Parameters** + +`project_id` | The ID of the project to delete. + +**Exceptions** + +`Project ID undefined.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. + + +**Example** + +```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. + + server.projects.delete('1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e') + +``` + + +
    +
    + + + ## Workbooks -Source files: server/endpoint/workbooks_endpoint.py, models/workbook_item.py +Using the TSC library, you can get information about a specific workbook or all the workbooks on a site, and you can publish, update, or delete workbooks. + +The project resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. The workbook methods are based upon the endpoints for projects in the REST API and operate on the `WorkbookItem` class. + + -### Get Workbooks -Get the first 100 workbooks on the server. To get all workbooks, use the Pager. + +
    +
    + +### WorkbookItem class + +```py + + WorkbookItem(project_id, name=None, show_tabs=False) + +``` +The workbook resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. + + +**Attributes** + +Name | Description +:--- | :--- +`content_permissions` | Sets or shows the permissions for the content in the project. The options are either `LockedToProject` or `ManagedByOwner`. +`name` | Name of the project. +`description` | The description of the project. +`id` | The project id. + + + +Source file: models/workbook_item.py + +
    +
    + +### Workbooks methods + + + + + + +Source files: server/endpoint/workbooks_endpoint.py + + + +#### workbooks.get ```py Workbooks.get() ``` +Get the first 100 workbooks on the server. To get all workbooks, use the Pager. + + + ### Get Workbook by ID Gets a workbook with a given ID. @@ -926,27 +1200,20 @@ DatasourceItem(project_id, name=None) The `DatasourceItem` represents the data source resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for data sources. When you create a new `DatasourceItem` instance, you must specify the `project_id` that the data source is associated with. -**Attributes** - -`connections` : The list of data connections (`ConnectionItem`) for the specified data source. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class). - -`content_url` : The name of the data source as it would appear in a URL. - -`created_at` : The date and time when the data source was created. - -`datasource_type` : The type of data source, for example, `sqlserver` or `excel-direct`. - -`id` : The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. - -`name` : The name of the data source. If not specified, the name of the published data source file is used. - -`project_id` : The identifer of the project associated with the data source. When you must provide this identifier when create an instance of a `DatasourceItem` - -`project_name` : The name of the project associated with the data source. - -`tags` : The tags that have been added to the data source. +**Attributes** -`updated_at` : The date and time when the data source was last updated. +Name | Description +:--- | :--- +`connections` | The list of data connections (`ConnectionItem`) for the specified data source. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class). +`content_url` | The name of the data source as it would appear in a URL. +`created_at` | The date and time when the data source was created. +`datasource_type` | The type of data source, for example, `sqlserver` or `excel-direct`. +`id` | The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. +`name` | The name of the data source. If not specified, the name of the published data source file is used. +`project_id` | The identifer of the project associated with the data source. When you must provide this identifier when create an instance of a `DatasourceItem` +`project_name` | The name of the project associated with the data source. +`tags` | The tags that have been added to the data source. +`updated_at` | The date and time when the data source was last updated. **Example** @@ -974,7 +1241,7 @@ Source file: server/endpoint/datasources_endpoint.py

    -#### ds.delete(*datasource_id*) +#### datasources.delete ```py datasources.delete(datasource_id) @@ -999,7 +1266,7 @@ REST API: [Delete Datasource](http://onlinehelp.tableau.com/v0.0/api/rest_api/en
    -#### ds.download(*datasource_id*, *filepath=None*) +#### datasources.download ```py datasources.download(datasource_id, filepath=None) @@ -1031,7 +1298,7 @@ The data source in `.tdsx` format.

    -#### ds.get() +#### datasources.get ```py datasources.get(req_options=None) @@ -1074,7 +1341,7 @@ with server.auth.sign_in(tableau_auth):
    -#### ds.get_by_id(*datasource_id*) +#### datasources.get_by_id ```py datasources.get_by_id(datasource_id) @@ -1115,7 +1382,7 @@ print(datasource.name) -#### ds.populate_connections(*datasource_item*) +#### datasources.populate_connections ```py datasources.populate_connections(datasource_item) @@ -1176,7 +1443,7 @@ None. A list of `ConnectionItem` objects are added to the data source (`datasour

    -#### ds.publish(*datasource_item*, *file_path*, *mode*, *connection_credentials=None*) +#### datasources.publish ```py datasources.publish(datasource_item, file_path, mode, connection_credentials=None) @@ -1239,7 +1506,7 @@ The `DatasourceItem` for the data source that was added or appened to.

    -#### ds.update(*datasource_item*) +#### datasources.update ```py datasource.update(datasource_item) @@ -1273,6 +1540,7 @@ An updated `DatasourceItem`. ... single_datasource = TSC.DatasourceItem('test', '1d0304cd-3796-429f-b815-7258370b9b74') + # need to specify the ID - this is a workaround. single_datasource._id = '9dbd2263-16b5-46e1-9c43-a76bb8ab65fb' single_datasource._tags = ['a', 'b', 'c'] single_datasource._project_name = 'Tester' @@ -1282,13 +1550,6 @@ An updated `DatasourceItem`. ``` -Source files: server/endpoint/datasources_endpoint.py, models/datasource_item.py - - - - - -
    @@ -1311,18 +1572,18 @@ The `UserItem` class contains the members or attributes for the view resources o **Attributes** -`auth_setting` : (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for this attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. - -`domain_name` : The name of the site. -`external_auth_user_id` : Represents ID stored in Tableau's single sign-on (SSO) system. The `externalAuthUserId` value is returned for Tableau Online. For other server configurations, this field contains null. -`id` : The id of the user on the site. -`last_login` : The date and time the user last logged in. -`workbooks` : The workbooks the user owns. You must run the populate_workbooks method to add the workbooks to the `UserItem`. - -`email` : The email address of the user. -`fullname` : The full name of the user. -`name` : The name of the user. This attribute is required when you are creating a `UserItem` instance. -`site_role` : The role the user has on the site. This attribute is required with you are creating a `UserItem` instance. The `site_role` can be one of the following: `Interactor`, `Publisher`, `ServerAdministrator`, `SiteAdministrator`, `Unlicensed`, `UnlicensedWithPublish`, `Viewer`, `ViewerWithPublish`, `Guest` +Name | Description +:--- | :--- +`auth_setting` | (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for tis attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. +`domain_name` | The name of the site. +`external_auth_user_id` | Represents ID stored in Tableau's single sign-on (SSO) system. The `externalAuthUserId` value is returned for Tableau Online. For other server configurations, this field contains null. +`id` | The id of the user on the site. +`last_login` | The date and time the user last logged in. +`workbooks` | The workbooks the user owns. You must run the populate_workbooks method to add the workbooks to the `UserItem`. +`email` | The email address of the user. +`fullname` | The full name of the user. +`name` | The name of the user. This attribute is required when you are creating a `UserItem` instance. +`site_role` | The role the user has on the site. This attribute is required with you are creating a `UserItem` instance. The `site_role` can be one of the following: `Interactor`, `Publisher`, `ServerAdministrator`, `SiteAdministrator`, `Unlicensed`, `UnlicensedWithPublish`, `Viewer`, `ViewerWithPublish`, `Guest` **Example** @@ -1344,7 +1605,7 @@ Source file: models/user_item.py
    -### Users Methods +### Users methods The Tableau Server Client provides several methods for interacting with user resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. @@ -1352,7 +1613,7 @@ Source file: server/endpoint/users_endpoint.py

    -#### users.add(*user_item*) +#### users.add ```py users.add(user_item) @@ -1392,7 +1653,7 @@ Returns the new `UserItem` object. ``` -### users.get +#### users.get ```py users.get(req_options=None) @@ -1432,8 +1693,7 @@ with server.auth.sign_in(tableau_auth):

    -#### users.get_by_id(*user_id*) - +#### users.get_by_id ```py users.get_by_id(user_id) @@ -1485,7 +1745,7 @@ Returns the list of favorites (views, workbooks, and data sources) for a user.
    -#### users.populate_workbooks(*user_item*, *req_options=None*) +#### users.populate_workbooks ```py users.populate_workbooks(user_item, req_options=None): @@ -1539,7 +1799,7 @@ A `PaginationItem` that points (`user_item.workbooks`). See [UserItem class](#us

    -#### users.remove(*user_id*) +#### users.remove ```py users.remove(user_id) @@ -1581,7 +1841,7 @@ REST API: [Remove User from Site](http://onlinehelp.tableau.com/current/api/rest -#### users.update(*user_item*, *password=None*) +#### users.update ```py users.update(user_item, password=None) From 29206823669cfb3dcc886215bed7643bba55438a Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Tue, 11 Apr 2017 18:50:35 -0700 Subject: [PATCH 08/17] um updates, workbooks in prog, etc. --- docs/docs/api-ref.md | 517 +++++++++++++++++++++++++++++++++---------- 1 file changed, 404 insertions(+), 113 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index b91ec8d2e..fa60494ef 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -8,9 +8,11 @@ layout: docs Until this reference is completed, we have noted the source files in the TSC library where you can get more information for individual endpoints. -* TOC -{:toc} -{:toc_levels(1,2,3)} +* TOC +{:toc } + + + ## Authentication @@ -145,18 +147,17 @@ The connections for Tableau Server data sources and workbooks are represented by ### ConnectionItem class ```py -ConnectionItem(object) +ConnectionItem() ``` -**Attributes** - -`datasource_id` : The identifier of the data source. - -`datasource_name` : The name of the data source. - -`id` : The identifer of the connection. +**Attributes** -`connection_type` : The type of connection. +Name | Description + :--- | : --- +`datasource_id` | The identifier of the data source. +`datasource_name` | The name of the data source. +`id` | The identifer of the connection. +`connection_type` | The type of connection. Source file: models/connection_item.py @@ -213,9 +214,10 @@ The `Server` class contains the attributes that represent the server on Tableau **Attributes** -`server_address` : Specifies the address of the Tableau Server or Tableau Online (for example, `http://MY-SERVER/`). - -`version` : Specifies the version of the REST API to use (for example, `2.5`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to 2.3, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_versions.htm){:target="_blank"} +Attribute | Description +:--- | :--- +`server_address` | Specifies the address of the Tableau Server or Tableau Online (for example, `http://MY-SERVER/`). +`version` | Specifies the version of the REST API to use (for example, `2.5`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to 2.3, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_versions.htm){:target="_blank"} @@ -234,14 +236,14 @@ server.version = 2.5 ``` -#### Server.*Resources* (Objects) +#### Server.*Resources* When you create an instance of the `Server` class, you have access to the resources on the server after you sign in. You can select these resources and their methods as members of the class, for example: `server.views.get()` -Resource | Description | - --- | ---| +Resource | Description + :--- | : --- *server*.auth | Sets authentication for sign in and sign out. See [Auth](#auththentication) | *server*.views | Access the server views and methods. See [Views](#views) *server*.users | Access the user resources and methods. See [Users](#users) @@ -261,9 +263,14 @@ Resource | Description | The `Server` class has `PublishMode` class that enumerates the options that specify what happens when you publish a workbook or data source. The options are `Overwrite`, `Append`, or `CreateNew`. -**Properties** +**Properties** + +Resource | Description + :--- | : --- +`PublishMode.Overwrite` | Overwrites the workbook or data source. +`PublishMode.Append` | Appends to the workbook or data source. +`PublishMode.CreateNew` | Creates a new workbook or data source. -`PublishMode.Overwrite` : The `Server` class has `PublishMode` class that you can set to specify what happens when you publish a workbook or data source. The options are `Overwrite`, `Append`, or `CreateNew`. **Example** @@ -294,11 +301,13 @@ ServerInfoItem(product_version, build_number, rest_api_version) ``` The `ServerInfoItem` class contains the builid and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class. -**Attributes** +**Attributes** -`product_version` : Shows the version of the Tableau Server or Tableau Online (for example, 10.2.0). -`build_number` : Shows the specific build number (for example, 10200.17.0329.1446). -`rest_api_version` : Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the `Server.version` attribute. To take advantage of new features, you should query the server and set the `Server.version` to match the supported REST API version number. +Name | Description +:--- | :--- +`product_version` | Shows the version of the Tableau Server or Tableau Online (for example, 10.2.0). +`build_number` | Shows the specific build number (for example, 10200.17.0329.1446). +`rest_api_version` | Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the `Server.version` attribute. To take advantage of new features, you should query the server and set the `Server.version` to match the supported REST API version number.
    @@ -328,7 +337,9 @@ REST API: [Server Info](https://onlinehelp.tableau.com/current/api/rest_api/en-u **Exceptions** -`404003 UNKNOWN_RESOURCE` : Raises an exception if the server info endpoint is not found. +Error | Description +:--- | :--- +`404003 UNKNOWN_RESOURCE` | Raises an exception if the server info endpoint is not found. **Example** @@ -405,7 +416,7 @@ Source file: models/site_item.py
    -### Sites methods +### Site methods The TSC library provides methods that operate on sites for Tableau Server and Tableau Online. These methods correspond to endpoints or methods for sites in the Tableau REST API. @@ -413,7 +424,7 @@ The TSC library provides methods that operate on sites for Tableau Server and Ta Source file: server/endpoint/sites_endpoint.py
    - +
    #### sites.create @@ -432,7 +443,9 @@ REST API: [Create Site](https://onlinehelp.tableau.com/current/api/rest_api/en-u **Parameters** -`site_item` : The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass the the `create` method. +Name | Description +:--- | :--- +`site_item` | The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass the the `create` method. **Returns** @@ -474,6 +487,8 @@ REST API: [Query Site](https://onlinehelp.tableau.com/current/api/rest_api/en-u **Parameters** +Name | Description +:--- | :--- `site_id` | The id for the site you want to query. @@ -560,8 +575,10 @@ The site item object must include the site ID and overrides all other settings. REST API: [Update Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Site%3FTocPath%3DAPI%2520Reference%7C_____84){:target="_blank"} -**Parameters** +**Parameters** +Name | Description +:--- | :--- `site_item` | The site item that you want to update. The settings specified in the site item override the current site settings. @@ -711,9 +728,9 @@ new_project = TSC.ProjectItem(name='My Project', content_permissions=by_owner, d

    -### Projects methods - +### Project methods +The project methods are based upon the endpoints for projects in the REST API and operate on the `ProjectItem` class. Source files: server/endpoint/projects_endpoint.py @@ -824,9 +841,9 @@ REST API: [Update Project](http://onlinehelp.tableau.com/current/api/rest_api/en **Parameters** -`project_item` - - The project item object must include the project ID. The values in the project item override the current project settings. +Name | Description +:--- | :--- +`project_item` | The project item object must include the project ID. The values in the project item override the current project settings. **Exceptions** @@ -882,10 +899,14 @@ REST API: [Delete Project](http://onlinehelp.tableau.com/current/api/rest_api/en **Parameters** +Name | Description +:--- | :--- `project_id` | The ID of the project to delete. **Exceptions** +Error | Description +:--- | :--- `Project ID undefined.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. @@ -905,6 +926,55 @@ REST API: [Delete Project](http://onlinehelp.tableau.com/current/api/rest_api/en
    +## Requests + +The TSC library provides a `RequestOptions` class that you can use to filter and sort. + +### RequestOptions class + +```py +RequestOptions(pagenumber=1, pagesize=100) + +``` + +**Attributes** + +Name | Description +:--- | :--- +`pagenumber` | The page number of the returned results. The defauilt value is 1. +`pagesize` | The number of items to return with each page (the default value is 100). +`sort()` | Returns a iterable set of `Sort` objects. +`filter()` | Returns an iterable set of `Filter` objects. + + + + +#### RequestOptions.Field class + +#### RequestOptions.Operator class +
    +
    + + +## Sort + +The `Sort` class is used with request options where you can filter and sort on the results returned from the server. + +### Sort class + +```py +sort(field, direction) +``` + + +**Attributes** + +Name | Description +:--- | :--- +`field` | Sets the field to sort on. The fields are defined in the `RequestOption` class. +`direction` | Name of the project. + + ## Workbooks @@ -926,144 +996,352 @@ The project resources for Tableau are defined in the `WorkbookItem` class. The c WorkbookItem(project_id, name=None, show_tabs=False) ``` -The workbook resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. +The workbook resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. Some workbook methods take an instance of the `WorkbookItem` class as arguments. The workbook item specifies the project **Attributes** Name | Description :--- | :--- -`content_permissions` | Sets or shows the permissions for the content in the project. The options are either `LockedToProject` or `ManagedByOwner`. -`name` | Name of the project. +`connections` | The list of data connections (`ConnectionItem`) for the data sources used by the workbook. You must first call the [workbooks.populate_connections](#workbooks.populate_connections) method to access this data. See the [ConnectionItem class](#connectionitem-class). +`content_url` | The name of the data source as it would appear in a URL. +`created_at` | The date and time when the data source was created. +`id` | The identifier for the workbook. You need this value to query a specific workbook or to delete a workbook with the `get_by_id` and `delete` methods. +`name` | The name of the workbook. +`preview_image` | The list of +`project_id` | The project id. +`project_name` | The name of the project. +`tags` | The tags that have been added to the workbook. +`updated_at` | The date and time when the workbook was last updated. +`views` | The list of views (`ViewItem`) for the workbook. You must first call the [workbooks.populate_views](#workbooks.populate_viewss) method to access this data. See the [ViewItem class](#viewitem-class). + + + +`connections` | The list of data connections (`ConnectionItem`) for the specified data source. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class). +name` | Name of the project. `description` | The description of the project. -`id` | The project id. +`project_id` | The project id. +`show_tabs` | (Boolean) +`connections` | The list of data connections (`ConnectionItem`) for the specified data source. You must first call the [workbooks.populate_connections](#workbooks.populate_connections) method to access this data. See the [ConnectionItem class](#connectionitem-class). +`content_url` | The name of the data source as it would appear in a URL. +`created_at` | The date and time when the data source was created. + +`datasource_type` | The type of data source, for example, `sqlserver` or `excel-direct`. +`id` | The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. +`name` | The name of the workbook. If not specified, the name of the published workbook file is used. +`project_id` | The identifer of the project associated with the workbook. When you must provide this identifier when create an instance of a `WorkbookItem`. +`project_name` | The name of the project associated with the data source. +`tags` | The tags that have been added to the data source. +`updated_at` | The date and time when the data source was last updated. + + + self._connections = None + self._content_url = None + self._created_at = None + self._id = None + self._initial_tags = set() + self._preview_image = None + self._project_name = None + self._size = None + self._updated_at = None + self._views = None + self.name = name + self.owner_id = None + self.tags = set() + self.project_id = project_id + self.show_tabs = show_tabs_ + + + +**Example** + +```py +# creating a new instance of a WorkbookItem +# +import tableauserverclient as TSC + +# Create new workbook_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39' + + new_workbook = TSC.WorkbookItem('3a8b6148-493c-11e6-a621-6f3499394a39') + + +```` + Source file: models/workbook_item.py

    -### Workbooks methods +### Workbook methods +The Tableau Server Client (TSC) library provides methods for interacting with workbooks. These methods correspond to endpoints in the Tableau Server REST API. For example, you can use the library to publish, update, download, or delete workbooks on the site. +The methods operate on a workbook object (`WorkbookItem`) that represents the workbook resources. +Source files: server/endpoint/workbooks_endpoint.py +
    +
    -Source files: server/endpoint/workbooks_endpoint.py +#### workbooks.get +```py +workbooks.get(req_options=None) +``` +Queries the server and returns information about the workbooks the site. -#### workbooks.get + + + + +REST API: [Query Workbooks for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbooks_for_Site%3FTocPath%3DAPI%2520Reference%7C_____70){:target="_blank"} + + +**Parameters** + +Name | Description +:--- | :--- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific workbook, you could specify the name of the workbook or the name of the owner. See [Filter and Sort](filter-sort) + + +**Returns** + +Returns a list of all `WorkbookItem` objects and a `PaginationItem`. Use these values to iterate through the results. + + +**Example** + +```py + +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') +server = TSC.Server('http://servername') + +with server.auth.sign_in(tableau_auth): + all_workbook_items, pagination_item = server.workbooks.get() + print([workbook.name for workbook in all_workbooks]) + + + +``` + +
    +
    + + + +#### workbooks.get_by_id ```py -Workbooks.get() +workbooks.get_by_id(workbook_id) ``` -Get the first 100 workbooks on the server. To get all workbooks, use the Pager. +Returns information about the specified workbook on the site. + +REST API: [Query Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook%3FTocPath%3DAPI%2520Reference%7C_____66){:target="_blank"} + + +**Parameters** + +Name | Description +:--- | :--- +`workbook_id` | The `workbook_id` specifies the workbook to query. The ID is a LUID (64-bit hexadecimal string). + + +**Exceptions** + +`Workbook ID undefined` : Raises an exception if a `workbook_id` is not provided. +**Returns** + +The `WorkbookItem`. See [WorkbookItem class](#workbookitem-class) -### Get Workbook by ID -Gets a workbook with a given ID. +**Example** ```py -Workbooks.get_by_id(id) + +workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') +print(workbook.name) + ``` -### Publish Workbook -Publish a local workbook to Tableau Server. +
    +
    + + +#### workbooks.publish ```py -Workbooks.publish(workbook_item, file_path, publish_mode) +workbooks.publish(workbook_item, file_path, publish_mode) ``` -Where the publish mode is one of the following: +Publish a workbook to the specified site. + +**Note:** The REST API cannot automatically include +extracts or other resources that the workbook uses. Therefore, + a .twb file that usess data from an Excel or csv file on a local computer cannot be published, +unless you package the data and workbook in a .twbx file, or publish the data source separately. + +For workbooks that are larger than 64 MB, the publish method automatically takes care of chunking the file in parts for uploading. Using this method is considerably more convenient than calling the publish REST APIs directly. + +REST API: [Publish Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Workbook%3FTocPath%3DAPI%2520Reference%7C_____45){:target="_blank"}, [Initiate File Upload](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Initiate_File_Upload%3FTocPath%3DAPI%2520Reference%7C_____43){:target="_blank"}, [Append to File Upload](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Append_to_File_Upload%3FTocPath%3DAPI%2520Reference%7C_____13){:target="_blank"} + + + +**Parameters** + +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that inlcudes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class). +`file_path` | The path and name of the workbook to publish. +`mode` | Specifies whether you are publishing a new workbook (`CreateNew`) or overwriting an existing workbook (`Overwrite`). You cannot appending workbooks. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. +`connection_credentials` | (Optional) The credentials (if required) to connect to the workbook's data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). + + + +**Exceptions** + +Error | Description +:--- | :--- +`File path does not lead to an existing file.` | Raises an error of the file path is incorrect or if the file is missing. +`Invalid mode defined.` | Raises an error if the publish mode is not one of the defined options. +`Workbooks cannot be appended.` | The `mode` must be set to `Overwrite` or `CreateNew`. +`Only .twb or twbx files can be published as workbooks.` | Raises an error if the type of file specified is not supported. + +See the REST API [Publish Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Workbook%3FTocPath%3DAPI%2520Reference%7C_____45){:target="_blank"} for additional error codes. + +**Returns** -* Append -* Overwrite -* CreateNew +The `WorkbookItem` for the workbook that was published. + -Example: +**Example** ```py -wb_item = TSC.WorkbookItem(name='Sample', - show_tabs=False, - project_id='ee8c6e70-43b6-11e6-af4f-f7b0d8e20760') -server.workbooks.publish(wb_item, +import tableauserverclient as TSC +import os +tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') +server = TSC.Server('http://servername') + +with server.auth.sign_in(tableau_auth): + # create a workbook item + wb_item = TSC.WorkbookItem(name='Sample', project_id='3a8b6148-493c-11e6-a621-6f3499394a39') + # call the publish method with the workbook item + wb_item = server.workbooks.publish(wb_item, os.path.join(YOUR_DIR, 'SampleWB.twbx'), - self.server.PublishMode.CreateNew) + 'Overwrite') ``` -### Update Workbook +
    +
    + -Modifies a workbook. The workbook item object must include the workbook ID and overrides all other settings. +#### workbooks.update ```py -Workbooks.update(wb_item_object) +workbooks.update(wb_item_object) +``` + + +Modifies a workbook. The workbook item object must include the workbook ID and overrides all other settings. + + ``` -### Delete Workbook + + +
    +
    + + + +#### workbooks.delete Deletes a workbook with the given ID. ```py -Workbooks.delete(id) +workbooks.delete(id) ``` -### Download Workbook +
    +
    + + +#### workbooks.download Downloads a workbook to the specified directory. ```py -Workbooks.download(id, file_path) +workbooks.download(id, file_path) ``` -### Populate Views for a Workbook +
    +
    + + +#### workbooks.populate_views Populates a list of views for a workbook object. You must populate views before you can iterate through the views. ```py -Workbooks.populate_views(workbook_obj) +workbooks.populate_views(workbook_obj) ``` -### Populate Connections for a Workbook +
    +
    + +#### workbooks.populate_connections Populates a list of connections for a given workbook. You must populate connections before you can iterate through the connections. ```py -Workbooks.populate_connections(workbook_obj) +workbooks.populate_connections(workbook_obj) ``` -### Populate a Preview Image for a Workbook +
    +
    + + +#### workbooks.populate_preview_image Populates a preview image for a given workbook. You must populate the image before you can iterate through the connections. ```py -Workbooks.populate_preview_image(workbook_obj) +workbooks.populate_preview_image(workbook_obj) ``` -### Get Views for a Workbook +
    +
    + + +#### workbooks.views Returns a list of views for a workbook. Before you get views, you must call populate_views. ```py -Workbooks.views +workbooks.views ``` -### Get Connections for a Workbook +
    +
    + +#### workbooks.connections Returns a list of connections for a workbook. Before you get connections, you must call populate_connections. ```py -workbook_obj.connections +workbooks.connections ```
    @@ -1090,18 +1368,14 @@ Source file: models/view_item.py **Attributes** - -`id` : The identifier of the view item. - -`name` : The name of the view. - -`owner_id` : The id for the owner of the view. - -`preview_image` : The thumbnail image for the view. - -`total_views` : The usage statistics for the view. Indicates the total number of times the view has been looked at. - -`workbook_id` : The id of the workbook associated with the view. +Name | Description +:--- | :--- +`id` | The identifier of the view item. +`name` | The name of the view. +`owner_id` | The id for the owner of the view. +`preview_image` | The thumbnail image for the view. +`total_views` | The usage statistics for the view. Indicates the total number of times the view has been looked at. +`workbook_id` | The id of the workbook associated with the view.
    @@ -1127,9 +1401,12 @@ Returns the list of views items for a site. REST API: [Query Views for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Site%3FTocPath%3DAPI%2520Reference%7C_____64){:target="_blank"} -**Parameters** +**Parameters** + +Name | Description +:--- | :--- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific view, you could specify the name of the view or its id. -`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific view, you could specify the name of the view or its id. **Returns** @@ -1250,9 +1527,11 @@ datasources.delete(datasource_id) Removes the specified data source from Tableau Server. -**Parameters** +**Parameters** -`datasource_id` : The identifier (`id`) for the the `DatasourceItem` that you want to delete from the server. +Name | Description +:--- | :--- +`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to delete from the server. **Exceptions** @@ -1278,14 +1557,17 @@ REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_a **Parameters** -`datasource_id` : The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. - -`filepath` : (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. +Name | Description +:--- | :--- +`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. +`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. **Exceptions** -`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. +Error | Description +:--- | :--- +`Datasource ID undefined` | Raises an exception if a valid `datasource_id` is not provided. **Returns** @@ -1312,7 +1594,9 @@ REST API: [Query Datasources](http://onlinehelp.tableau.com/current/api/rest_api **Parameters** -`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific data source, you could specify the name of the project or its id. +Name | Description +:--- | :--- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific data source, you could specify the name of the project or its id. **Returns** @@ -1354,12 +1638,16 @@ REST API: [Query Datasource](http://onlinehelp.tableau.com/current/api/rest_api/ **Parameters** -`datasource_id` : The `datasource_id` specifies the data source to query. +Name | Description +:--- | :--- +`datasource_id` | The `datasource_id` specifies the data source to query. **Exceptions** -`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. +Error | Description +:--- | :--- +`Datasource ID undefined` | Raises an exception if a valid `datasource_id` is not provided. **Returns** @@ -1399,14 +1687,18 @@ REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/ **Parameters** -`datasource_item` : The `datasource_item` specifies the data source to populate with connection information. +Name | Description +:--- | :--- +`datasource_item` | The `datasource_item` specifies the data source to populate with connection information. **Exceptions** -`Datasource item missing ID. Datasource must be retrieved from server first.` : Raises an errror if the datasource_item is unspecified. +Error | Description +:--- | :--- +`Datasource item missing ID. Datasource must be retrieved from server first.` | Raises an errror if the datasource_item is unspecified. **Returns** @@ -1457,23 +1749,22 @@ REST API: [Publish Datasource](http://onlinehelp.tableau.com/current/api/rest_ap **Parameters** -`datasource_item` : The `datasource_item` specifies the new data source you are adding, or the data source you are appending to. If you are adding a new data source, you need to create a new `datasource_item` with a `project_id` of an existing project. The name of the data source will be the name of the file, unless you also specify a name for the new data source when you create the instance. See [DatasourceItem](#datasourceitem-class). - -`file_path` : The path and name of the data source to publish. - -`mode` : Specifies whether you are publishing a new data source (`CreateNew`), overwriting an existing data source (`Overwrite`), or appending data to a data source (`Append`). If you are appending to a data source, the data source on the server and the data source you are publishing must be be extracts (.tde files) and they must share the same schema. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. - -`connection_credentials` : (Optional) The credentials required to connect to the data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). +Name | Description +:--- | :--- +`datasource_item` | The `datasource_item` specifies the new data source you are adding, or the data source you are appending to. If you are adding a new data source, you need to create a new `datasource_item` with a `project_id` of an existing project. The name of the data source will be the name of the file, unless you also specify a name for the new data source when you create the instance. See [DatasourceItem](#datasourceitem-class). +`file_path` | The path and name of the data source to publish. +`mode` | Specifies whether you are publishing a new data source (`CreateNew`), overwriting an existing data source (`Overwrite`), or appending data to a data source (`Append`). If you are appending to a data source, the data source on the server and the data source you are publishing must be be extracts (.tde files) and they must share the same schema. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. +`connection_credentials` | (Optional) The credentials required to connect to the data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). **Exceptions** -`File path does not lead to an existing file.` : Raises an error of the file path is incorrect or if the file is missing. - -`Invalid mode defined.` : Raises an error if the publish mode is not one of the defined options. - -`Only .tds, tdsx, or .tde files can be published as datasources.` : Raises an error if the type of file specified is not supported. +Error | Description +:--- | :--- +`File path does not lead to an existing file.` | Raises an error of the file path is incorrect or if the file is missing. +`Invalid mode defined.` | Raises an error if the publish mode is not one of the defined options. +`Only .tds, tdsx, or .tde files can be published as datasources.` | Raises an error if the type of file specified is not supported. **Returns** From cb3962e8612e62f11d41477f09978f57221df890 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Wed, 12 Apr 2017 18:59:37 -0700 Subject: [PATCH 09/17] getting there, mostly done. --- docs/docs/api-ref.md | 360 +++++++++++++++++++++++++++++++++---------- 1 file changed, 281 insertions(+), 79 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index fa60494ef..e76b51d78 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -1008,49 +1008,14 @@ Name | Description `created_at` | The date and time when the data source was created. `id` | The identifier for the workbook. You need this value to query a specific workbook or to delete a workbook with the `get_by_id` and `delete` methods. `name` | The name of the workbook. -`preview_image` | The list of +`owner_id` | The ID of the owner. +`preview_image` | The thumbnail image for the view. You must first call the [workbooks.populate_preview_image](#workbooks.populate_preview_image) method to access this data. `project_id` | The project id. `project_name` | The name of the project. +`show_tabs` | (Boolean) Determines whether the workbook shows tabs for the view. `tags` | The tags that have been added to the workbook. `updated_at` | The date and time when the workbook was last updated. -`views` | The list of views (`ViewItem`) for the workbook. You must first call the [workbooks.populate_views](#workbooks.populate_viewss) method to access this data. See the [ViewItem class](#viewitem-class). - - - -`connections` | The list of data connections (`ConnectionItem`) for the specified data source. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class). -name` | Name of the project. -`description` | The description of the project. -`project_id` | The project id. -`show_tabs` | (Boolean) -`connections` | The list of data connections (`ConnectionItem`) for the specified data source. You must first call the [workbooks.populate_connections](#workbooks.populate_connections) method to access this data. See the [ConnectionItem class](#connectionitem-class). -`content_url` | The name of the data source as it would appear in a URL. -`created_at` | The date and time when the data source was created. - -`datasource_type` | The type of data source, for example, `sqlserver` or `excel-direct`. -`id` | The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. -`name` | The name of the workbook. If not specified, the name of the published workbook file is used. -`project_id` | The identifer of the project associated with the workbook. When you must provide this identifier when create an instance of a `WorkbookItem`. -`project_name` | The name of the project associated with the data source. -`tags` | The tags that have been added to the data source. -`updated_at` | The date and time when the data source was last updated. - - - self._connections = None - self._content_url = None - self._created_at = None - self._id = None - self._initial_tags = set() - self._preview_image = None - self._project_name = None - self._size = None - self._updated_at = None - self._views = None - self.name = name - self.owner_id = None - self.tags = set() - self.project_id = project_id - self.show_tabs = show_tabs_ - +`views` | The list of views (`ViewItem`) for the workbook. You must first call the [workbooks.populate_views](#workbooks.populate_views) method to access this data. See the [ViewItem class](#viewitem-class). @@ -1228,17 +1193,14 @@ The `WorkbookItem` for the workbook that was published. ```py import tableauserverclient as TSC -import os tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') server = TSC.Server('http://servername') with server.auth.sign_in(tableau_auth): # create a workbook item - wb_item = TSC.WorkbookItem(name='Sample', project_id='3a8b6148-493c-11e6-a621-6f3499394a39') + wb_item = TSC.WorkbookItem(name='Sample', project_id='1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e') # call the publish method with the workbook item - wb_item = server.workbooks.publish(wb_item, - os.path.join(YOUR_DIR, 'SampleWB.twbx'), - 'Overwrite') + wb_item = server.workbooks.publish(wb_item, 'SampleWB.twbx', 'Overwrite') ```
    @@ -1248,15 +1210,50 @@ with server.auth.sign_in(tableau_auth): #### workbooks.update ```py -workbooks.update(wb_item_object) +workbooks.update(workbook_item) ``` -Modifies a workbook. The workbook item object must include the workbook ID and overrides all other settings. +Modifies an existing workbook. Use this method to change the owner or the project that the workbook belongs to, or to change whether the workbook shows views in tabs. The workbook item must include the workbook ID and overrides the existing settings. +REST API: [Update Workbooks](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Workbook%3FTocPath%3DAPI%2520Reference%7C_____87){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the settings for the workbook you are updating. You can change the `owner_id`, `project_id`, and the `show_tabs` values. See [WorkbookItem](#workbookitem-class). + + +**Exceptions** + +Error | Description +:--- | :--- +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. Use the `workbooks.get()` or `workbooks.get_by_id()` methods to retreive the workbook item from the server. -``` +```py + +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') +server = TSC.Server('http://servername') + +with server.auth.sign_in(tableau_auth): + + # get the workbook item from the site + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + print("\nUpdate {0} workbook. Project was {1}".format(workbook.name, workbook.project_name)) + + + # make an change, for example a new project ID + workbook.project_id = '1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e' + + # call the update method + workbook = server.workbooks.update(workbook) + print("\nUpdated {0} workbook. Project is now {1}".format(workbook.name, workbook.project_name)) + + +```
    @@ -1266,34 +1263,152 @@ Modifies a workbook. The workbook item object must include the workbook ID and o #### workbooks.delete -Deletes a workbook with the given ID. - ```py -workbooks.delete(id) +workbooks.delete(workbook_id) ``` +Deletes a workbook with the specified ID. + + + +To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). + + +REST API: [Delete Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Workbook%3FTocPath%3DAPI%2520Reference%7C_____31){:target="_blank"} + + +**Parameters** + +Name | Description +:--- | :--- +`workbook_id` | The ID of the workbook to delete. + +**Exceptions** + +Error | Description +:--- | :--- +`Workbook ID undefined.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. + + +**Example** + +```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# tableau_auth sign in, etc. + + server.workbooks.delete('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + +``` + +

    #### workbooks.download -Downloads a workbook to the specified directory. - ```py -workbooks.download(id, file_path) +workbooks.download(workbook_id, filepath=None) ``` +Downloads a workbook to the specified directory (optional). + + +REST API: [Download Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Workbook%3FTocPath%3DAPI%2520Reference%7C_____36){:target="_blank"} + + +**Parameters** + +Name | Description +:--- | :--- +`workbook_id` | The ID for the the `WorkbookItem` that you want to download from the server. +`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default is `Filepath=None`. + + +**Exceptions** + +Error | Description +:--- | :--- +`Workbook ID undefined` | Raises an exception if a valid `datasource_id` is not provided. + + +**Returns** + +The file path to the downloaded workbook. + + +**Example** + +```py + + file_path = server.workbooks.download('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + print("\nDownloaded the file to {0}.".format(file_path)) + +```` + +

    #### workbooks.populate_views -Populates a list of views for a workbook object. You must populate views before you can iterate through the views. +```py +workbooks.populate_views(workbook_item) +``` + +Populates (or gets) a list of views for a workbook. + +You must first call this method to populate views before you can iterate through the views. + +This method retrieves the view information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the view information is not included. Use this method to retrieve the views. The method adds the list of views to the workbook item (`workbook_item.views`). This is a list of `ViewItem`. + +REST API: [Query Views for Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Workbook%3FTocPath%3DAPI%2520Reference%7C_____65){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the workbook to populate with views information. See [WorkbookItem class](#workbookitem-class). + + + + +**Exceptions** + +Error | Description +:--- | :--- +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. You can retreive the workbook items using the `workbooks.get()` and `workbooks.get_by_id()` methods. + + +**Returns** + +None. A list of `ViewItem` objects are added to the workbook (`workbook_item.views`). + + +**Example** ```py -workbooks.populate_views(workbook_obj) +# import tableauserverclient as TSC + +# server = TSC.Server('http://SERVERURL') +# + ... + +# get the workbook item + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + + +# get the view information + server.workbooks.populate_views(workbook) + +# print information about the views for the work item + print("\nThe views for {0}: ".format(workbook.name)) + print([view.name for view in workbook.views]) + + ... + ```
    @@ -1301,11 +1416,63 @@ workbooks.populate_views(workbook_obj) #### workbooks.populate_connections -Populates a list of connections for a given workbook. You must populate connections before you can iterate through the +```py +workbooks.populate_connections(workbook_item) +``` + +Populates a list of data source connections for the specified workbook. + +You must populate connections before you can iterate through the connections. +This method retrieves the data source connection information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query all the workbooks, the data source connection information is not included. Use this method to retrieve the connection information for any data sources used by the workbook. The method adds the list of data connections to the workbook item (`workbook_item.connections`). This is a list of `ConnectionItem`. + +REST API: [Query Workbook Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Connections%3FTocPath%3DAPI%2520Reference%7C_____67){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the workbook to populate with data connection information. + + + + +**Exceptions** + +Error | Description +:--- | :--- +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. + + +**Returns** + +None. A list of `ConnectionItem` objects are added to the data source (`workbook_item.connections`). + + +**Example** + ```py -workbooks.populate_connections(workbook_obj) +# import tableauserverclient as TSC + +# server = TSC.Server('http://SERVERURL') +# + ... + +# get the workbook item + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + + +# get the connection information + server.workbooks.populate_connections(workbook) + +# print information about the data connections for the workbook item + print("\nThe connections for {0}: ".format(workbook.name)) + print([connection.id for connection in workbook.connections]) + + + ... + ```
    @@ -1314,38 +1481,60 @@ workbooks.populate_connections(workbook_obj) #### workbooks.populate_preview_image -Populates a preview image for a given workbook. You must populate the image before you can iterate through the -connections. - ```py -workbooks.populate_preview_image(workbook_obj) +workbooks.populate_preview_image(workbook_item) ``` -
    -
    +This method gets the preview image (thumbnail) for the specified workbook item. +The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `workbook_item.preview_image`. -#### workbooks.views +REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69){:target="_blank"} -Returns a list of views for a workbook. Before you get views, you must call populate_views. +**Parameters** -```py -workbooks.views -``` +Name | Description +:--- | :--- +`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. -
    -
    +**Exceptions** + +Error | Description +:--- | :--- +`View item missing ID or workbook ID` | Raises an error if the ID for the view item or workbook is missing. + + + +**Returns** + +None. The preview image is added to the view. -#### workbooks.connections -Returns a list of connections for a workbook. Before you get connections, you must call populate_connections. + +**Example** ```py -workbooks.connections + +# import tableauserverclient as TSC + +# server = TSC.Server('http://SERVERURL') + + ... + + # get the workbook item + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + + # add the png thumbnail to the workbook item + server.workbooks.populate_preview_image(workbook) + + ``` -

    +
    + + + ## Views @@ -1439,7 +1628,7 @@ See [ViewItem class](#viewitem-class) ``` -Populates a preview image for a given view. +Populates a preview image for the specified view. This method gets the preview image (thumbnail) for the specified view item. The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `view.preview_image` for the view. @@ -1447,11 +1636,17 @@ REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/r **Parameters** -`view_item` : The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. +Name | Description +:--- | :--- +`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. **Exceptions** -`View item missing ID or workbook ID` : Raises an error if the id for the view item or workbook is missing. +Error | Description +:--- | :--- +`View item missing ID or workbook ID` | Raises an error if the ID for the view item or workbook is missing. + + **Returns** @@ -1572,9 +1767,16 @@ Error | Description **Returns** -The data source in `.tdsx` format. +The file path to the downloaded data source. The data source is downloaded in `.tdsx` format. +**Example** +```py + + file_path = server.datasources.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') + print("\nDownloaded the file to {0}.".format(file_path)) + +````
    @@ -1681,7 +1883,7 @@ Populates the connections for the specified data source. -This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (`datasource_item.connections`) populates the data source with the list of `ConnectionItem`. +This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (`datasource_item.connections`). This is a list of `ConnectionItem` objects. REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47){:target="_blank"} From 45310dcba1bd06e9f272c35ff544f5fe58f69f0a Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Thu, 13 Apr 2017 13:54:00 -0700 Subject: [PATCH 10/17] sorted, added filters, requests, etc. --- docs/docs/api-ref.md | 2840 ++++++++++++++++++++++-------------------- 1 file changed, 1503 insertions(+), 1337 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index e76b51d78..6efe5255d 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -195,468 +195,794 @@ Source file: models/connection_credentials.py

    -## Server - -In the Tableau REST API, the server (`http://MY-SERVER/`) is the base or core of the URI that makes up the various endpoints or methods for accessing resources on the server (views, workbooks, sites, users, data sources, etc.) -The TSC library provides a `Server` class that represents the server. You create a server instance to sign in to the server and to call the various methods for accessing resources. +## Data sources +Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project. +The data source resources for Tableau Server are defined in the `DatasourceItem` class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the `DatasourceItem` class.
    -
    - -### Server class +### DatasourceItem class ```py -Server(server_address) +DatasourceItem(project_id, name=None) ``` -The `Server` class contains the attributes that represent the server on Tableau Server. After you create an instance of the `Server` class, you can sign in to the server and call methods to access all of the resources on the server. -**Attributes** +The `DatasourceItem` represents the data source resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for data sources. When you create a new `DatasourceItem` instance, you must specify the `project_id` that the data source is associated with. -Attribute | Description -:--- | :--- -`server_address` | Specifies the address of the Tableau Server or Tableau Online (for example, `http://MY-SERVER/`). -`version` | Specifies the version of the REST API to use (for example, `2.5`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to 2.3, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_versions.htm){:target="_blank"} +**Attributes** +Name | Description +:--- | :--- +`connections` | The list of data connections (`ConnectionItem`) for the specified data source. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class). +`content_url` | The name of the data source as it would appear in a URL. +`created_at` | The date and time when the data source was created. +`datasource_type` | The type of data source, for example, `sqlserver` or `excel-direct`. +`id` | The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. +`name` | The name of the data source. If not specified, the name of the published data source file is used. +`project_id` | The identifer of the project associated with the data source. When you must provide this identifier when create an instance of a `DatasourceItem` +`project_name` | The name of the project associated with the data source. +`tags` | The tags that have been added to the data source. +`updated_at` | The date and time when the data source was last updated. **Example** ```py -import tableauserverclient as TSC + import tableauserverclient as TSC -# create a instance of server -server = TSC.Server('http://MY-SERVER') + # Create new datasource_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39' + new_datasource = TSC.DatasourceItem('3a8b6148-493c-11e6-a621-6f3499394a39') +``` -# change the REST API version to 2.5 -server.version = 2.5 +Source file: models/datasource_item.py + +
    +
    + +### Datasources methods + +The Tableau Server Client provides several methods for interacting with data source resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. + +Source file: server/endpoint/datasources_endpoint.py +
    +
    + +#### datasources.delete + +```py +datasources.delete(datasource_id) ``` -#### Server.*Resources* +Removes the specified data source from Tableau Server. -When you create an instance of the `Server` class, you have access to the resources on the server after you sign in. You can select these resources and their methods as members of the class, for example: `server.views.get()` +**Parameters** +Name | Description +:--- | :--- +`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to delete from the server. -Resource | Description - :--- | : --- -*server*.auth | Sets authentication for sign in and sign out. See [Auth](#auththentication) | -*server*.views | Access the server views and methods. See [Views](#views) -*server*.users | Access the user resources and methods. See [Users](#users) -*server*.sites | Access the sites. See [Sites](#sites) -*server*.groups | Access the groups resources and methods. See [Groups](#groups) -*server*.workbooks | Access the resources and methods for workbooks. See [Workbooks](#workbooks) -*server*.datasources | Access the resources and methods for data sources. See [Data Sources](#data-sources) -*server*.projects | Access the resources and methods for projects. See [Projects](#projets) -*server*.schedules | Access the resources and methods for schedules. See [Schedules](#Schedules) -*server*.server_info | Access the resources and methods for server information. See [ServerInfo class](#serverinfo-class) +**Exceptions** + +`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. + + +REST API: [Delete Datasource](http://onlinehelp.tableau.com/v0.0/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Datasource%3FTocPath%3DAPI%2520Reference%7C_____19){:target="_blank"} + +

    + + +#### datasources.download + +```py +datasources.download(datasource_id, filepath=None) + +``` +Downloads the specified data source in `.tdsx` format. + +REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Datasource%3FTocPath%3DAPI%2520Reference%7C_____34){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. +`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. + + +**Exceptions** + +Error | Description +:--- | :--- +`Datasource ID undefined` | Raises an exception if a valid `datasource_id` is not provided. + + +**Returns** + +The file path to the downloaded data source. The data source is downloaded in `.tdsx` format. + +**Example** + +```py + + file_path = server.datasources.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') + print("\nDownloaded the file to {0}.".format(file_path)) + +```` + + +

    -#### Server.PublishMode +#### datasources.get -The `Server` class has `PublishMode` class that enumerates the options that specify what happens when you publish a workbook or data source. The options are `Overwrite`, `Append`, or `CreateNew`. +```py +datasources.get(req_options=None) +``` +Returns all the data sources for the site. + +To get the connection information for each data source, you must first populate the `DatasourceItem` with connection information using the [populate_connections(*datasource_item*)](#populate-connections-datasource) method. For more information, see [Populate Connections and Views](populate-connections-views#populate-connections-for-data-sources) + +REST API: [Query Datasources](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasources%3FTocPath%3DAPI%2520Reference%7C_____49){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific data source, you could specify the name of the project or its id. + + +**Returns** + +Returns a list of `DatasourceItem` objects and a `PaginationItem` object. Use these values to iterate through the results. -**Properties** -Resource | Description - :--- | : --- -`PublishMode.Overwrite` | Overwrites the workbook or data source. -`PublishMode.Append` | Appends to the workbook or data source. -`PublishMode.CreateNew` | Creates a new workbook or data source. **Example** ```py - - print(TSC.Server.PublishMode.Overwrite) - # prints 'Overwrite' - - overwrite_true = TSC.Server.PublishMode.Overwrite +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('http://SERVERURL') - ... +with server.auth.sign_in(tableau_auth): + all_datasources, pagination_item = server.datasources.get() + print("\nThere are {} datasources on site: ".format(pagination_item.total_available)) + print([datasource.name for datasource in all_datasources]) +```` - # pass the PublishMode to the publish workbooks method - new_workbook = server.workbooks.publish(new_workbook, args.filepath, overwrite_true) +
    +
    + + +#### datasources.get_by_id + +```py +datasources.get_by_id(datasource_id) ``` +Returns the specified data source item. + +REST API: [Query Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource%3FTocPath%3DAPI%2520Reference%7C_____46){:target="_blank"} -
    -
    +**Parameters** -### ServerInfoItem class +Name | Description +:--- | :--- +`datasource_id` | The `datasource_id` specifies the data source to query. + + +**Exceptions** + +Error | Description +:--- | :--- +`Datasource ID undefined` | Raises an exception if a valid `datasource_id` is not provided. + + +**Returns** + +The `DatasourceItem`. See [DatasourceItem class](#datasourceitem-class) + + +**Example** ```py -ServerInfoItem(product_version, build_number, rest_api_version) + +datasource = server.datasources.get_by_id('59a57c0f-3905-4022-9e87-424fb05e9c0e') +print(datasource.name) + ``` -The `ServerInfoItem` class contains the builid and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class. -**Attributes** -Name | Description -:--- | :--- -`product_version` | Shows the version of the Tableau Server or Tableau Online (for example, 10.2.0). -`build_number` | Shows the specific build number (for example, 10200.17.0329.1446). -`rest_api_version` | Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the `Server.version` attribute. To take advantage of new features, you should query the server and set the `Server.version` to match the supported REST API version number. +
    +
    + -
    -
    +#### datasources.populate_connections +```py +datasources.populate_connections(datasource_item) +``` -### ServerInfo methods +Populates the connections for the specified data source. + + + + +This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (`datasource_item.connections`). This is a list of `ConnectionItem` objects. + +REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`datasource_item` | The `datasource_item` specifies the data source to populate with connection information. + + + + +**Exceptions** + +Error | Description +:--- | :--- +`Datasource item missing ID. Datasource must be retrieved from server first.` | Raises an errror if the datasource_item is unspecified. + + +**Returns** + +None. A list of `ConnectionItem` objects are added to the data source (`datasource_item.connections`). + + +**Example** + +```py +# import tableauserverclient as TSC + +# server = TSC.Server('http://SERVERURL') +# + ... + +# get the data source + datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') + + +# get the connection information + server.datasources.populate_connections(datasource) + +# print the information about the first connection item + print(datasource.connections[0].connection_type) + print(datasource.connections[0].id) + print(datasource.connections[0].server_address) + + ... + +``` -The TSC library provides a method to access the build and version information from Tableau Server.
    +
    -#### server_info.get +#### datasources.publish ```py -server_info.get() - +datasources.publish(datasource_item, file_path, mode, connection_credentials=None) ``` -Retrieve the build and version information for the server. -This method makes an unauthenticated call, so no sign in or authentication token is required. +Publishes a data source to a server, or appends data to an existing data source. -REST API: [Server Info](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Server_Info%3FTocPath%3DAPI%2520Reference%7C_____76){:target="_blank"} - -**Parameters** - None +This method checks the size of the data source and automatically determines whether the publish the data source in multiple parts or in one opeation. + +REST API: [Publish Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Datasource%3FTocPath%3DAPI%2520Reference%7C_____44){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`datasource_item` | The `datasource_item` specifies the new data source you are adding, or the data source you are appending to. If you are adding a new data source, you need to create a new `datasource_item` with a `project_id` of an existing project. The name of the data source will be the name of the file, unless you also specify a name for the new data source when you create the instance. See [DatasourceItem](#datasourceitem-class). +`file_path` | The path and name of the data source to publish. +`mode` | Specifies whether you are publishing a new data source (`CreateNew`), overwriting an existing data source (`Overwrite`), or appending data to a data source (`Append`). If you are appending to a data source, the data source on the server and the data source you are publishing must be be extracts (.tde files) and they must share the same schema. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. +`connection_credentials` | (Optional) The credentials required to connect to the data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). + + **Exceptions** -Error | Description -:--- | :--- -`404003 UNKNOWN_RESOURCE` | Raises an exception if the server info endpoint is not found. +Error | Description +:--- | :--- +`File path does not lead to an existing file.` | Raises an error of the file path is incorrect or if the file is missing. +`Invalid mode defined.` | Raises an error if the publish mode is not one of the defined options. +`Only .tds, tdsx, or .tde files can be published as datasources.` | Raises an error if the type of file specified is not supported. + + +**Returns** + +The `DatasourceItem` for the data source that was added or appened to. + + +**Example** + +```py + + import tableauserverclient as TSC + server = TSC.Server('http://SERVERURL') + + ... + + project_id = '3a8b6148-493c-11e6-a621-6f3499394a39' + file_path = 'C:\\temp\\WorldIndicators.tde' + + # Use the project id to create new datsource_item + new_datasource = TSC.DatasourceItem(project_id) + + # publish data source (specifed in file_path) + new_datasource = server.datasources.publish( + new_datasource, file_path, 'CreateNew') + + ... +``` + +
    +
    + +#### datasources.update + +```py +datasource.update(datasource_item) +``` + +Updates the owner, or project of the specified data source. + +REST API: [Update Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Datasource%3FTocPath%3DAPI%2520Reference%7C_____79){:target="_blank"} + +**Parameters** + +`datasource_item` : The `datasource_item` specifies the data source to update. + + + +**Exceptions** + +`Datasource item missing ID. Datasource must be retrieved from server first.` : Raises an errror if the datasource_item is unspecified. Use the `Datasources.get()` method to retrieve that identifies for the data sources on the server. + + +**Returns** + +An updated `DatasourceItem`. + + +**Example** + +```py +# from server-client-python/test/test_datasource.py + + ... + + single_datasource = TSC.DatasourceItem('test', '1d0304cd-3796-429f-b815-7258370b9b74') + # need to specify the ID - this is a workaround. + single_datasource._id = '9dbd2263-16b5-46e1-9c43-a76bb8ab65fb' + single_datasource._tags = ['a', 'b', 'c'] + single_datasource._project_name = 'Tester' + updated_datasource = self.server.datasources.update(single_datasource) + + ... + +``` + + + +
    +
    + +## Filters + +The TSC library provides a `Filter` class that you can use to filter results returned from the server. + +You can use the `Filter` and `RequestOptions` classes to filter and sort the following endpoints: + +- Users +- Datasources +- Workbooks +- Views + +For more information, see [Filter and Sort](filter-sort). + + +### Filter class + +```py +Filter(field, operator, value) +``` + +The `Filter` class corresponds to the *filter expresions* in the Tableau REST API. + + + +**Attributes** + +Name | Description +:--- | :--- +`Field` | Defined in the `RequestOptions.Field` class. +`Operator` | Defined in the `RequestOptions.Operator` class +`Value` | The value to compare with the specified field and operator. + + + + + +
    +
    + + +## Groups + +Using the TSC library, you can get information about all the groups on a site, you can add or remove groups, or add or remove users in a group. + +The group resources for Tableau Server are defined in the `GroupItem` class. The class corresponds to the group resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the `GroupItem` class. + +
    +
    + +### GroupItem class + +```py +GroupItem(name) +``` + +The `GroupItem` class contains the members or attributes for the view resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. + +Source file: models/group_item.py + +**Attributes** + +Name | Description +:--- | :--- +`domain_name` | The name of the Active Directory domain (`local` if local authentication is used). +`id` | The id of the group. +`users` | The list of users (`UserItem`). +`name` | The name of the group. The `name` is required when you create an instance of a group. + + **Example** ```py -import tableauserverclient as TSC - -# create a instance of server -server = TSC.Server('http://MY-SERVER') + newgroup = TSC.GroupItem('My Group') +``` -# set the version number > 2.3 -# the server_info.get() method works in 2.4 and later -server.version = '2.5' -s_info = server.server_info.get() -print("\nServer info:") -print("\tProduct version: {0}".format(s_info.product_version)) -print("\tREST API version: {0}".format(s_info.rest_api_version)) -print("\tBuild number: {0}".format(s_info.build_number)) -``` +
    +
    -
    -
    +### Groups methods +The Tableau Server Client provides several methods for interacting with group resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. -## Sites -Using the TSC library, you can query a site or sites on a server, or create or delete a site on the server. -The site resources for Tableau Server and Tableau Online are defined in the `SiteItem` class. The class corresponds to the site resources you can access using the Tableau Server REST API. The site methods are based upon the endpoints for sites in the REST API and operate on the `SiteItem` class. +Source file: server/endpoint/groups_endpoint.py

    -### SiteItem class +#### groups.add_user ```py -SiteItem(name, content_url, admin_mode=None, user_quota=None, storage_quota=None, - disable_subscriptions=False, subscribe_others_enabled=True, revision_history_enabled=False) +groups.add_user(group_item, user_id): ``` -The `SiteItem` class contains the members or attributes for the site resources on Tableau Server or Tableau Online. The `SiteItem` class defines the information you can request or query from Tableau Server or Tableau Online. The class members correspond to the attributes of a server request or response payload. +Adds a user to the specified group. -**Attributes** -Attribute | Description -:--- | :--- -`name` | The name of the site. The name of the default site is "". -`content_url` | The path to the site. -`admin_mode` | (Optional) For Tableau Server only. Specify `ContentAndUsers` to allow site administrators to use the server interface and **tabcmd** commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify `ContentOnly` to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.) -`user_quota`| (Optional) Specifies the maximum number of users for the site. If you do not specify this value, the limit depends on the type of licensing configured for the server. For user-based license, the maximum number of users is set by the license. For core-based licensing, there is no limit to the number of users. If you specify a maximum value, only licensed users are counted and server administrators are excluded. -`storage_quota` | (Optional) Specifes the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again. -`disable_subscriptions` | (Optional) Specify `true` to prevent users from being able to subscribe to workbooks on the specified site. The default is `false`. -`subscribe_others_enabled` | (Optional) Specify `false` to prevent server administrators, site administrators, and project or content owners from being able to subscribe other users to workbooks on the specified site. The default is `true`. -`revision_history_enabled` | (Optional) Specify `true` to enable revision history for content resources (workbooks and datasources). The default is `false`. -`revision_limit` | (Optional) Specifies the number of revisions of a content source (workbook or data source) to allow. On Tableau Server, the default is 25. -`state` | Shows the current state of the site (`Active` or `Suspended`). +REST API [Add User to Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Add_User_to_Group%3FTocPath%3DAPI%2520Reference%7C_____8){:target="_blank"} +**Parameters** -**Example** +Name | Description +:--- | :--- +`group_item` | The `group_item` specifies the group to update. +`user_id` | The id of the user. -```py -# create a new instance of a SiteItem -new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode='ContentAndUsers', user_quota=15, storage_quota=1000, disable_subscriptions=True) -``` +**Returns** -Source file: models/site_item.py +None. -
    -
    +**Example** -### Site methods +```py +# Adding a user to a group +# Using the second group on the site, aleady have all_groups +# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba' -The TSC library provides methods that operate on sites for Tableau Server and Tableau Online. These methods correspond to endpoints or methods for sites in the Tableau REST API. +# add Ian to the second group + server.groups.add_user(all_groups[1], '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba') + +# populate the GroupItem with the users + pagination_item = server.groups.populate_users(all_groups[1]) + for user in all_groups[1].users : + print(user.name) -Source file: server/endpoint/sites_endpoint.py +``` +

    -
    -#### sites.create +#### groups.create ```py -sites.create(site_item) +create(group_item) ``` -Creates a new site on the server for the specified site item object. +Creates a new group in Tableau Server. -Tableau Server only. +REST API: [Create Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Group%3FTocPath%3DAPI%2520Reference%7C_____14){:target="_blank"} -REST API: [Create Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Site%3FTocPath%3DAPI%2520Reference%7C_____17){:target="_blank"} +**Parameters** +Name | Description +:--- | :--- +`group_item` | The `group_item` specifies the group to add. You first create a new instance of a `GroupItem` and pass that to this method. -**Parameters** - -Name | Description -:--- | :--- -`site_item` | The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass the the `create` method. -**Returns** -Returns a new instance of `SiteItem`. +**Returns** +Adds new `GroupItem`. **Example** ```py -import tableauserverclient as TSC -# create an instance of server -server = TSC.Server('http://MY-SERVER') +# Create a new group -# create shortcut for admin mode -content_users=TSC.SiteItem.AdminMode.ContentAndUsers +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') -# create a new SiteItem -new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode=content_users, user_quota=15, storage_quota=1000, disable_subscriptions=True) -# call the sites create method with the SiteItem -new_site = server.sites.create(new_site) +# create a new instance with the group name + newgroup = TSC.GroupItem('My Group') + +# call the create method + newgroup = server.groups.create(newgroup) + +# print the names of the groups on the server + all_groups, pagination_item = server.groups.get() + for group in all_groups : + print(group.name, group.id) ``` -
    -
    +
    +
    -#### sites.get_by_id +#### groups.delete ```py -sites.get_by_id(site_id) +groups.delete(group_id) ``` -Queries the site with the given ID. +Deletes the group on the site. +REST API: [Delete Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Site%3FTocPath%3DAPI%2520Reference%7C_____74){:target="_blank"} -REST API: [Query Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Site){:target="_blank"} **Parameters** -Name | Description -:--- | :--- -`site_id` | The id for the site you want to query. - - -**Exceptions** +Name | Description +:--- | :--- +`group_id` | The identifier (`id`) for the the group that you want to remove from the server. -`Site ID undefined.` | Raises an error if an id is not specified. +**Exceptions** -**Returns** +Error | Description +:--- | :--- +`Group ID undefined` | Raises an exception if a valid `group_id` is not provided. -Returns the `SiteItem`. - -**Example** +**Example** ```py +# Delete a group from the site # import tableauserverclient as TSC -# server = TSC.Server('http://MY-SERVER') -# sign in, etc. +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') - a_site = server.sites.get_by_id('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d') - print("\nThe site with id '9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d' is: {0}".format(a_site.name)) + with server.auth.sign_in(tableau_auth): + server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') ``` - -
    +

    -#### sites.get +#### groups.get ```py -sites.get() +groups.get(req_options=None) ``` -Queries all the sites on the server. +Returns information about the groups on the site. -REST API: [Query Sites](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Sites%3FTocPath%3DAPI%2520Reference%7C_____58){:target="_blank"} +To get information about the users in a group, you must first populate the `GroupItem` with user information using the [groups.populate_users](api-ref#groupspopulateusers) method. +REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} + **Parameters** - None. +Name | Description +:--- | :--- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific groups, you could specify the name of the group or the group id. -**Returns** - -Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these values to iterate through the results. + +**Returns** + +Returns a list of `GroupItem` objects and a `PaginationItem` object. Use these values to iterate through the results. **Example** + ```py # import tableauserverclient as TSC -# server = TSC.Server('http://MY-SERVER') -# sign in, etc. - - # query the sites - all_sites, pagination_item = server.sites.get() +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') - # print all the site names and ids - for site in TSC.Pager(server.sites): - print(site.id, site.name, site.content_url, site.state) + with server.auth.sign_in(tableau_auth): + # get the groups on the server + all_groups, pagination_item = server.groups.get() -``` + # print the names of the groups + for group in all_groups : + print(group.name, group.id) +```` -
    -
    +
    +
    -#### sites.update +#### groups.populate_users ```py -sites.update(site_item) +groups.populate_users(group_item, req_options=None) ``` -Modifies the settings for site. - - -The site item object must include the site ID and overrides all other settings. +Populates the `group_item` with the list of users. -REST API: [Update Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Site%3FTocPath%3DAPI%2520Reference%7C_____84){:target="_blank"} +REST API: [Get Users in Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_in_Group){:target="_blank"} +**Parameters** -**Parameters** +Name | Description +:--- | :--- +`group_item` | The `group_item` specifies the group to populate with user information. +`req_options` | (Optional) Additional request options to send to the endpoint. -Name | Description -:--- | :--- -`site_item` | The site item that you want to update. The settings specified in the site item override the current site settings. **Exceptions** -Error | Description -:--- | :--- -`Site item missing ID.` | The site id must be present and must match the id of the site you are updating. -`You cannot set admin_mode to ContentOnly and also set a user quota` | To set the `user_quota`, the `AdminMode` must be set to `ContentAndUsers` +`Group item missing ID. Group must be retrieved from server first.` : Raises an errror if the `group_item` is unspecified. -**Returns** +**Returns** -Returns the updated `site_item`. +None. A list of `UserItem` objects are added to the group (`group_item.users`). -**Example** +**Example** ```py -... +# import tableauserverclient as TSC -# make some updates to an existing site_item -site_item.name ="New name" +# server = TSC.Server('http://SERVERURL') +# + ... -# call update -site_item = server.sites.update(site_item) +# get the group + mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') -... -``` -
    -
    +# get the user information + pagination_item = server.groups.populate_users(mygroup) + +# print the information about the first connection item + for user in mygroup.users : + print(user.name) + -#### sites.delete +``` +
    +
    + +#### groups.remove_user ```py -Sites.delete(site_id) +groups.remove_user(group_item, user_id) ``` -Deletes the specified site. +Removes a user from a group. -REST API: [Delete Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Site%3FTocPath%3DAPI%2520Reference%7C_____27){:target="_name"} + + +REST API: [Remove User from Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Group%3FTocPath%3DAPI%2520Reference%7C_____73){:target="_blank"} **Parameters** - -`site_id` | The id of the site that you want to delete. +Name | Description +:--- | :--- +`group_item` | The `group_item` specifies the group to remove the user from. +`user_id` | The id for the user. **Exceptions** -Error | Description -:--- | :--- -`Site ID Undefined.` | The site id must be present and must match the id of the site you are deleting. +Error | Description +:--- | :--- +`Group must be populated with users first.` | Raises an errror if the `group_item` is unpopulated. -**Example** + +**Returns** + +None. The user is removed from the group. + + +**Example** ```py +# Remove a user from the group # import tableauserverclient as TSC -# server = TSC.Server('http://MY-SERVER') -# sign in, etc. +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') -server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d') + with server.auth.sign_in(tableau_auth): + + # get the group + mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') + + # remove user '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d' + server.groups.remove_user(mygroup, '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') ``` -
    +

    - + ## Projects @@ -778,1032 +1104,847 @@ with server.auth.sign_in(tableau_auth): # create the project new_project = server.projects.create(new_project) -``` - -
    -
    - - -#### projects.get - -```py -projects.get() - -``` - -Return a list of project items for a site. - - -To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). - -REST API: [Query Projects](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Projects%3FTocPath%3DAPI%2520Reference%7C_____55){:target="_blank"} - - -**Parameters** - -None. - -**Returns** - -Returns a list of all `ProjectItem` objects and a `PaginationItem`. Use these values to iterate through the results. - - - - **Example** - -```py -import tableauserverclient as TSC -tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL') -server = TSC.Server('http://SERVER') - -with server.auth.sign_in(tableau_auth): - # get all projects on site - all_project_items, pagination_item = server.projects.get() - print([proj.name for proj in all_project_items]) - -``` - -
    -
    - - -#### projects.update - -```py -projects.update(project_item) -``` - -Modify the project settings. - -You can use this method to update the project name, the project description, or the project permissions. To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). - -REST API: [Update Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Project%3FTocPath%3DAPI%2520Reference%7C_____82){:target="_blank"} - -**Parameters** - -Name | Description -:--- | :--- -`project_item` | The project item object must include the project ID. The values in the project item override the current project settings. - - -**Exceptions** - -`Project item missing ID.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. - - -**Returns** - -Returns the updated project information. - -See [ProjectItem class]() - -```py -# import tableauserverclient as TSC -# server = TSC.Server('http://MY-SERVER') -# sign in, etc - - ... - - all_project_items, pagination_item = server.projects.get() - print([prj.name for prj in all_project_items]) - - # update project item #7 with new name, etc. - all_projects[7].name ='New name' - all_projects[7].description = 'New description' - - # call method to update project - updated_proj = server.projects.update(all_projects[7]) - - - - -``` -
    -
    - - -#### projects.delete - -```py -projects.delete(project_id) -``` - -Deletes a project by ID. - - -To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). - - -REST API: [Delete Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Project%3FTocPath%3DAPI%2520Reference%7C_____24){:target="_blank"} - - -**Parameters** - -Name | Description -:--- | :--- -`project_id` | The ID of the project to delete. - -**Exceptions** - -Error | Description -:--- | :--- -`Project ID undefined.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. - - -**Example** - -```py -# import tableauserverclient as TSC -# server = TSC.Server('http://MY-SERVER') -# sign in, etc. - - server.projects.delete('1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e') - -``` - - -
    -
    - - -## Requests - -The TSC library provides a `RequestOptions` class that you can use to filter and sort. - -### RequestOptions class - -```py -RequestOptions(pagenumber=1, pagesize=100) - -``` - -**Attributes** - -Name | Description -:--- | :--- -`pagenumber` | The page number of the returned results. The defauilt value is 1. -`pagesize` | The number of items to return with each page (the default value is 100). -`sort()` | Returns a iterable set of `Sort` objects. -`filter()` | Returns an iterable set of `Filter` objects. - - - - -#### RequestOptions.Field class - -#### RequestOptions.Operator class -
    -
    - - -## Sort - -The `Sort` class is used with request options where you can filter and sort on the results returned from the server. - -### Sort class - -```py -sort(field, direction) -``` - - -**Attributes** - -Name | Description -:--- | :--- -`field` | Sets the field to sort on. The fields are defined in the `RequestOption` class. -`direction` | Name of the project. - - - -## Workbooks - -Using the TSC library, you can get information about a specific workbook or all the workbooks on a site, and you can publish, update, or delete workbooks. - -The project resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. The workbook methods are based upon the endpoints for projects in the REST API and operate on the `WorkbookItem` class. - - +``` +
    +
    -
    -
    +#### projects.get -### WorkbookItem class +```py +projects.get() -```py - - WorkbookItem(project_id, name=None, show_tabs=False) - ``` -The workbook resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. Some workbook methods take an instance of the `WorkbookItem` class as arguments. The workbook item specifies the project +Return a list of project items for a site. -**Attributes** -Name | Description -:--- | :--- -`connections` | The list of data connections (`ConnectionItem`) for the data sources used by the workbook. You must first call the [workbooks.populate_connections](#workbooks.populate_connections) method to access this data. See the [ConnectionItem class](#connectionitem-class). -`content_url` | The name of the data source as it would appear in a URL. -`created_at` | The date and time when the data source was created. -`id` | The identifier for the workbook. You need this value to query a specific workbook or to delete a workbook with the `get_by_id` and `delete` methods. -`name` | The name of the workbook. -`owner_id` | The ID of the owner. -`preview_image` | The thumbnail image for the view. You must first call the [workbooks.populate_preview_image](#workbooks.populate_preview_image) method to access this data. -`project_id` | The project id. -`project_name` | The name of the project. -`show_tabs` | (Boolean) Determines whether the workbook shows tabs for the view. -`tags` | The tags that have been added to the workbook. -`updated_at` | The date and time when the workbook was last updated. -`views` | The list of views (`ViewItem`) for the workbook. You must first call the [workbooks.populate_views](#workbooks.populate_views) method to access this data. See the [ViewItem class](#viewitem-class). +To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). +REST API: [Query Projects](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Projects%3FTocPath%3DAPI%2520Reference%7C_____55){:target="_blank"} +**Parameters** +None. -**Example** +**Returns** -```py -# creating a new instance of a WorkbookItem -# -import tableauserverclient as TSC +Returns a list of all `ProjectItem` objects and a `PaginationItem`. Use these values to iterate through the results. + -# Create new workbook_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39' - new_workbook = TSC.WorkbookItem('3a8b6148-493c-11e6-a621-6f3499394a39') + **Example** +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL') +server = TSC.Server('http://SERVER') -```` +with server.auth.sign_in(tableau_auth): + # get all projects on site + all_project_items, pagination_item = server.projects.get() + print([proj.name for proj in all_project_items]) -Source file: models/workbook_item.py +```

    -### Workbook methods - -The Tableau Server Client (TSC) library provides methods for interacting with workbooks. These methods correspond to endpoints in the Tableau Server REST API. For example, you can use the library to publish, update, download, or delete workbooks on the site. -The methods operate on a workbook object (`WorkbookItem`) that represents the workbook resources. - - - -Source files: server/endpoint/workbooks_endpoint.py - -
    -
    -#### workbooks.get +#### projects.update ```py -workbooks.get(req_options=None) +projects.update(project_item) ``` -Queries the server and returns information about the workbooks the site. - +Modify the project settings. +You can use this method to update the project name, the project description, or the project permissions. To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). +REST API: [Update Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Project%3FTocPath%3DAPI%2520Reference%7C_____82){:target="_blank"} +**Parameters** -REST API: [Query Workbooks for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbooks_for_Site%3FTocPath%3DAPI%2520Reference%7C_____70){:target="_blank"} +Name | Description +:--- | :--- +`project_item` | The project item object must include the project ID. The values in the project item override the current project settings. -**Parameters** +**Exceptions** -Name | Description -:--- | :--- -`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific workbook, you could specify the name of the workbook or the name of the owner. See [Filter and Sort](filter-sort) +`Project item missing ID.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. **Returns** -Returns a list of all `WorkbookItem` objects and a `PaginationItem`. Use these values to iterate through the results. - +Returns the updated project information. -**Example** +See [ProjectItem class]() -```py +```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc -import tableauserverclient as TSC -tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') -server = TSC.Server('http://servername') + ... -with server.auth.sign_in(tableau_auth): - all_workbook_items, pagination_item = server.workbooks.get() - print([workbook.name for workbook in all_workbooks]) + all_project_items, pagination_item = server.projects.get() + print([prj.name for prj in all_project_items]) + # update project item #7 with new name, etc. + all_projects[7].name ='New name' + all_projects[7].description = 'New description' + + # call method to update project + updated_proj = server.projects.update(all_projects[7]) + + ``` -
    -
    - - +
    + -#### workbooks.get_by_id +#### projects.delete ```py -workbooks.get_by_id(workbook_id) +projects.delete(project_id) ``` -Returns information about the specified workbook on the site. - -REST API: [Query Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook%3FTocPath%3DAPI%2520Reference%7C_____66){:target="_blank"} - +Deletes a project by ID. -**Parameters** -Name | Description -:--- | :--- -`workbook_id` | The `workbook_id` specifies the workbook to query. The ID is a LUID (64-bit hexadecimal string). +To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). -**Exceptions** +REST API: [Delete Project](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Project%3FTocPath%3DAPI%2520Reference%7C_____24){:target="_blank"} -`Workbook ID undefined` : Raises an exception if a `workbook_id` is not provided. +**Parameters** -**Returns** +Name | Description +:--- | :--- +`project_id` | The ID of the project to delete. -The `WorkbookItem`. See [WorkbookItem class](#workbookitem-class) +**Exceptions** +Error | Description +:--- | :--- +`Project ID undefined.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. -**Example** +**Example** + ```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. -workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') -print(workbook.name) + server.projects.delete('1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e') -``` +``` -
    +

    -#### workbooks.publish +## Requests -```py -workbooks.publish(workbook_item, file_path, publish_mode) -``` +The TSC library provides a `RequestOptions` class that you can use to filter results returned from the server. -Publish a workbook to the specified site. +You can use the `Sort` and `RequestOptions` classes to filter and sort the following endpoints: -**Note:** The REST API cannot automatically include -extracts or other resources that the workbook uses. Therefore, - a .twb file that usess data from an Excel or csv file on a local computer cannot be published, -unless you package the data and workbook in a .twbx file, or publish the data source separately. +- Users +- Datasources +- Workbooks +- Views -For workbooks that are larger than 64 MB, the publish method automatically takes care of chunking the file in parts for uploading. Using this method is considerably more convenient than calling the publish REST APIs directly. +For more information, see [Filter and Sort](filter-sort). -REST API: [Publish Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Workbook%3FTocPath%3DAPI%2520Reference%7C_____45){:target="_blank"}, [Initiate File Upload](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Initiate_File_Upload%3FTocPath%3DAPI%2520Reference%7C_____43){:target="_blank"}, [Append to File Upload](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Append_to_File_Upload%3FTocPath%3DAPI%2520Reference%7C_____13){:target="_blank"} +
    +### RequestOptions class -**Parameters** +```py +RequestOptions(pagenumber=1, pagesize=100) -Name | Description -:--- | :--- -`workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that inlcudes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class). -`file_path` | The path and name of the workbook to publish. -`mode` | Specifies whether you are publishing a new workbook (`CreateNew`) or overwriting an existing workbook (`Overwrite`). You cannot appending workbooks. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. -`connection_credentials` | (Optional) The credentials (if required) to connect to the workbook's data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). - +``` -**Exceptions** -Error | Description -:--- | :--- -`File path does not lead to an existing file.` | Raises an error of the file path is incorrect or if the file is missing. -`Invalid mode defined.` | Raises an error if the publish mode is not one of the defined options. -`Workbooks cannot be appended.` | The `mode` must be set to `Overwrite` or `CreateNew`. -`Only .twb or twbx files can be published as workbooks.` | Raises an error if the type of file specified is not supported. +**Attributes** -See the REST API [Publish Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Workbook%3FTocPath%3DAPI%2520Reference%7C_____45){:target="_blank"} for additional error codes. +Name | Description +:--- | :--- +`pagenumber` | The page number of the returned results. The defauilt value is 1. +`pagesize` | The number of items to return with each page (the default value is 100). +`sort()` | Returns a iterable set of `Sort` objects. +`filter()` | Returns an iterable set of `Filter` objects. -**Returns** +
    +
    -The `WorkbookItem` for the workbook that was published. - -**Example** -```py +#### RequestOptions.Field class -import tableauserverclient as TSC -tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') -server = TSC.Server('http://servername') +The `RequestOptions.Field` class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, see [Fitering and Sorting](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_filtering_and_sorting.htm%3FTocPath%3DConcepts%7C_____7){:target="_blank"} in the Tableau REST API. + +**Attributes** + +**Attributes** + +Field | Description +:--- | :--- +`CreatedAt` | Same as 'createdAt' in the REST API. TSC. `RequestOptions.Field.CreatedAt` +`LastLogin` | Same as 'lastLogin' in the REST API. `RequestOptions.Field.LastLogin` +`Name` | Same as 'name' in the REST API. `RequestOptions.Field.Name` +`OwnerName` | Same as 'ownerName' in the REST API. `RequestOptions.Field.OwnerName` +`SiteRole` | Same as 'siteRole' in the REST API. `RequestOptions.Field.SiteRole` +`Tags` | Same as 'tags' in the REST API. `RequestOptions.Field.Tags` +`UpdatedAt` | Same as 'updatedAt' in the REST API. `RequestOptions.Field.UpdatedAt` -with server.auth.sign_in(tableau_auth): - # create a workbook item - wb_item = TSC.WorkbookItem(name='Sample', project_id='1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e') - # call the publish method with the workbook item - wb_item = server.workbooks.publish(wb_item, 'SampleWB.twbx', 'Overwrite') -```
    -
    +
    -#### workbooks.update -```py -workbooks.update(workbook_item) -``` +#### RequestOptions.Operator class +Specifies the operators you can use to filter requests. -Modifies an existing workbook. Use this method to change the owner or the project that the workbook belongs to, or to change whether the workbook shows views in tabs. The workbook item must include the workbook ID and overrides the existing settings. -REST API: [Update Workbooks](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Workbook%3FTocPath%3DAPI%2520Reference%7C_____87){:target="_blank"} +**Attributes** -**Parameters** +Operator | Description +:--- | :--- +`Equals` | Sets the operator to equals (same as `eq` in the REST API). `TSC.RequestOptions.Operator.Equals` +`GreaterThan` | Sets the operator to greater than (same as `gt` in the REST API). `TSC.RequestOptions.Operator.GreaterThan` +`GreaterThanOrEqual` | Sets the operator to greater than or equal (same as `gte` in the REST API). `TSC.RequestOptions.Operator.GreaterThanOrEqual` +`LessThan` | Sets the operator to less than (same as `lt` in the REST API). `TSC.RequestOptions.Operator.LessThan` +`LessThanOrEqual` | Sets the operator to less than or equal (same as `lte` in the REST API). `TSC.RequestOptions.Operator.LessThanOrEqual` +`In` | Sets the operator to in (same as `in` in the REST API). `TSC.RequestOptions.Operator.In` -Name | Description -:--- | :--- -`workbook_item` | The `workbook_item` specifies the settings for the workbook you are updating. You can change the `owner_id`, `project_id`, and the `show_tabs` values. See [WorkbookItem](#workbookitem-class). +
    +
    -**Exceptions** -Error | Description -:--- | :--- -`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. Use the `workbooks.get()` or `workbooks.get_by_id()` methods to retreive the workbook item from the server. +#### RequestOptions.Direction class +Specifies the direction to sort the returned fields. -```py -import tableauserverclient as TSC -tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') -server = TSC.Server('http://servername') +**Attributes** -with server.auth.sign_in(tableau_auth): +Name | Description +:--- | :--- +`Asc` | Sets the sort direction to ascending (`TSC.RequestOptions.Direction.Asc`) +`Desc` | Sets the sort direction to descending (`TSC.RequestOptions.Direction.Desc`). - # get the workbook item from the site - workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') - print("\nUpdate {0} workbook. Project was {1}".format(workbook.name, workbook.project_name)) +
    +
    - # make an change, for example a new project ID - workbook.project_id = '1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e' - # call the update method - workbook = server.workbooks.update(workbook) - print("\nUpdated {0} workbook. Project is now {1}".format(workbook.name, workbook.project_name)) +## Server -``` +In the Tableau REST API, the server (`http://MY-SERVER/`) is the base or core of the URI that makes up the various endpoints or methods for accessing resources on the server (views, workbooks, sites, users, data sources, etc.) +The TSC library provides a `Server` class that represents the server. You create a server instance to sign in to the server and to call the various methods for accessing resources.
    -
    - +
    -#### workbooks.delete +### Server class ```py -workbooks.delete(workbook_id) +Server(server_address) ``` +The `Server` class contains the attributes that represent the server on Tableau Server. After you create an instance of the `Server` class, you can sign in to the server and call methods to access all of the resources on the server. -Deletes a workbook with the specified ID. +**Attributes** +Attribute | Description +:--- | :--- +`server_address` | Specifies the address of the Tableau Server or Tableau Online (for example, `http://MY-SERVER/`). +`version` | Specifies the version of the REST API to use (for example, `2.5`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to 2.3, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_versions.htm){:target="_blank"} -To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). +**Example** -REST API: [Delete Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Workbook%3FTocPath%3DAPI%2520Reference%7C_____31){:target="_blank"} +```py +import tableauserverclient as TSC +# create a instance of server +server = TSC.Server('http://MY-SERVER') -**Parameters** -Name | Description -:--- | :--- -`workbook_id` | The ID of the workbook to delete. +# change the REST API version to 2.5 +server.version = 2.5 -**Exceptions** -Error | Description -:--- | :--- -`Workbook ID undefined.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. +``` +#### Server.*Resources* -**Example** - -```py -# import tableauserverclient as TSC -# server = TSC.Server('http://MY-SERVER') -# tableau_auth sign in, etc. +When you create an instance of the `Server` class, you have access to the resources on the server after you sign in. You can select these resources and their methods as members of the class, for example: `server.views.get()` - server.workbooks.delete('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') -``` +Resource | Description + :--- | : --- +*server*.auth | Sets authentication for sign in and sign out. See [Auth](#auththentication) | +*server*.views | Access the server views and methods. See [Views](#views) +*server*.users | Access the user resources and methods. See [Users](#users) +*server*.sites | Access the sites. See [Sites](#sites) +*server*.groups | Access the groups resources and methods. See [Groups](#groups) +*server*.workbooks | Access the resources and methods for workbooks. See [Workbooks](#workbooks) +*server*.datasources | Access the resources and methods for data sources. See [Data Sources](#data-sources) +*server*.projects | Access the resources and methods for projects. See [Projects](#projets) +*server*.schedules | Access the resources and methods for schedules. See [Schedules](#Schedules) +*server*.server_info | Access the resources and methods for server information. See [ServerInfo class](#serverinfo-class)
    -
    - +
    -#### workbooks.download +#### Server.PublishMode -```py -workbooks.download(workbook_id, filepath=None) -``` +The `Server` class has `PublishMode` class that enumerates the options that specify what happens when you publish a workbook or data source. The options are `Overwrite`, `Append`, or `CreateNew`. -Downloads a workbook to the specified directory (optional). +**Properties** -REST API: [Download Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Workbook%3FTocPath%3DAPI%2520Reference%7C_____36){:target="_blank"} +Resource | Description + :--- | : --- +`PublishMode.Overwrite` | Overwrites the workbook or data source. +`PublishMode.Append` | Appends to the workbook or data source. +`PublishMode.CreateNew` | Creates a new workbook or data source. -**Parameters** +**Example** -Name | Description -:--- | :--- -`workbook_id` | The ID for the the `WorkbookItem` that you want to download from the server. -`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default is `Filepath=None`. +```py + + print(TSC.Server.PublishMode.Overwrite) + # prints 'Overwrite' + + overwrite_true = TSC.Server.PublishMode.Overwrite + ... -**Exceptions** + # pass the PublishMode to the publish workbooks method + new_workbook = server.workbooks.publish(new_workbook, args.filepath, overwrite_true) -Error | Description -:--- | :--- -`Workbook ID undefined` | Raises an exception if a valid `datasource_id` is not provided. +``` -**Returns** -The file path to the downloaded workbook. +
    +
    -**Example** +### ServerInfoItem class ```py +ServerInfoItem(product_version, build_number, rest_api_version) +``` +The `ServerInfoItem` class contains the builid and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class. - file_path = server.workbooks.download('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') - print("\nDownloaded the file to {0}.".format(file_path)) +**Attributes** -```` +Name | Description +:--- | :--- +`product_version` | Shows the version of the Tableau Server or Tableau Online (for example, 10.2.0). +`build_number` | Shows the specific build number (for example, 10200.17.0329.1446). +`rest_api_version` | Shows the supported REST API version number. Note that this might be different from the default value specified for the server, with the `Server.version` attribute. To take advantage of new features, you should query the server and set the `Server.version` to match the supported REST API version number.
    -
    +
    -#### workbooks.populate_views +### ServerInfo methods + +The TSC library provides a method to access the build and version information from Tableau Server. + +
    + +#### server_info.get ```py -workbooks.populate_views(workbook_item) +server_info.get() + ``` +Retrieve the build and version information for the server. -Populates (or gets) a list of views for a workbook. +This method makes an unauthenticated call, so no sign in or authentication token is required. -You must first call this method to populate views before you can iterate through the views. +REST API: [Server Info](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Server_Info%3FTocPath%3DAPI%2520Reference%7C_____76){:target="_blank"} + +**Parameters** + None + +**Exceptions** -This method retrieves the view information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the view information is not included. Use this method to retrieve the views. The method adds the list of views to the workbook item (`workbook_item.views`). This is a list of `ViewItem`. +Error | Description +:--- | :--- +`404003 UNKNOWN_RESOURCE` | Raises an exception if the server info endpoint is not found. -REST API: [Query Views for Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Workbook%3FTocPath%3DAPI%2520Reference%7C_____65){:target="_blank"} +**Example** -**Parameters** +```py +import tableauserverclient as TSC -Name | Description -:--- | :--- -`workbook_item` | The `workbook_item` specifies the workbook to populate with views information. See [WorkbookItem class](#workbookitem-class). +# create a instance of server +server = TSC.Server('http://MY-SERVER') + +# set the version number > 2.3 +# the server_info.get() method works in 2.4 and later +server.version = '2.5' +s_info = server.server_info.get() +print("\nServer info:") +print("\tProduct version: {0}".format(s_info.product_version)) +print("\tREST API version: {0}".format(s_info.rest_api_version)) +print("\tBuild number: {0}".format(s_info.build_number)) +``` -**Exceptions** +
    +
    -Error | Description -:--- | :--- -`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. You can retreive the workbook items using the `workbooks.get()` and `workbooks.get_by_id()` methods. +## Sites -**Returns** +Using the TSC library, you can query a site or sites on a server, or create or delete a site on the server. -None. A list of `ViewItem` objects are added to the workbook (`workbook_item.views`). +The site resources for Tableau Server and Tableau Online are defined in the `SiteItem` class. The class corresponds to the site resources you can access using the Tableau Server REST API. The site methods are based upon the endpoints for sites in the REST API and operate on the `SiteItem` class. +
    +
    -**Example** +### SiteItem class ```py -# import tableauserverclient as TSC +SiteItem(name, content_url, admin_mode=None, user_quota=None, storage_quota=None, + disable_subscriptions=False, subscribe_others_enabled=True, revision_history_enabled=False) +``` -# server = TSC.Server('http://SERVERURL') -# - ... +The `SiteItem` class contains the members or attributes for the site resources on Tableau Server or Tableau Online. The `SiteItem` class defines the information you can request or query from Tableau Server or Tableau Online. The class members correspond to the attributes of a server request or response payload. -# get the workbook item - workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') +**Attributes** +Attribute | Description +:--- | :--- +`name` | The name of the site. The name of the default site is "". +`content_url` | The path to the site. +`admin_mode` | (Optional) For Tableau Server only. Specify `ContentAndUsers` to allow site administrators to use the server interface and **tabcmd** commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify `ContentOnly` to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.) +`user_quota`| (Optional) Specifies the maximum number of users for the site. If you do not specify this value, the limit depends on the type of licensing configured for the server. For user-based license, the maximum number of users is set by the license. For core-based licensing, there is no limit to the number of users. If you specify a maximum value, only licensed users are counted and server administrators are excluded. +`storage_quota` | (Optional) Specifes the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again. +`disable_subscriptions` | (Optional) Specify `true` to prevent users from being able to subscribe to workbooks on the specified site. The default is `false`. +`subscribe_others_enabled` | (Optional) Specify `false` to prevent server administrators, site administrators, and project or content owners from being able to subscribe other users to workbooks on the specified site. The default is `true`. +`revision_history_enabled` | (Optional) Specify `true` to enable revision history for content resources (workbooks and datasources). The default is `false`. +`revision_limit` | (Optional) Specifies the number of revisions of a content source (workbook or data source) to allow. On Tableau Server, the default is 25. +`state` | Shows the current state of the site (`Active` or `Suspended`). -# get the view information - server.workbooks.populate_views(workbook) -# print information about the views for the work item - print("\nThe views for {0}: ".format(workbook.name)) - print([view.name for view in workbook.views]) +**Example** - ... +```py + +# create a new instance of a SiteItem + +new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode='ContentAndUsers', user_quota=15, storage_quota=1000, disable_subscriptions=True) ``` +Source file: models/site_item.py +
    -
    +
    -#### workbooks.populate_connections -```py -workbooks.populate_connections(workbook_item) -``` +### Site methods -Populates a list of data source connections for the specified workbook. +The TSC library provides methods that operate on sites for Tableau Server and Tableau Online. These methods correspond to endpoints or methods for sites in the Tableau REST API. -You must populate connections before you can iterate through the -connections. -This method retrieves the data source connection information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query all the workbooks, the data source connection information is not included. Use this method to retrieve the connection information for any data sources used by the workbook. The method adds the list of data connections to the workbook item (`workbook_item.connections`). This is a list of `ConnectionItem`. +Source file: server/endpoint/sites_endpoint.py -REST API: [Query Workbook Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Connections%3FTocPath%3DAPI%2520Reference%7C_____67){:target="_blank"} +
    +
    -**Parameters** +#### sites.create -Name | Description -:--- | :--- -`workbook_item` | The `workbook_item` specifies the workbook to populate with data connection information. +```py +sites.create(site_item) +``` +Creates a new site on the server for the specified site item object. +Tableau Server only. -**Exceptions** +REST API: [Create Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Site%3FTocPath%3DAPI%2520Reference%7C_____17){:target="_blank"} -Error | Description -:--- | :--- -`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. -**Returns** +**Parameters** + +Name | Description +:--- | :--- +`site_item` | The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass the the `create` method. + + +**Returns** -None. A list of `ConnectionItem` objects are added to the data source (`workbook_item.connections`). +Returns a new instance of `SiteItem`. **Example** ```py -# import tableauserverclient as TSC - -# server = TSC.Server('http://SERVERURL') -# - ... - -# get the workbook item - workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') - - -# get the connection information - server.workbooks.populate_connections(workbook) +import tableauserverclient as TSC -# print information about the data connections for the workbook item - print("\nThe connections for {0}: ".format(workbook.name)) - print([connection.id for connection in workbook.connections]) +# create an instance of server +server = TSC.Server('http://MY-SERVER') +# create shortcut for admin mode +content_users=TSC.SiteItem.AdminMode.ContentAndUsers - ... +# create a new SiteItem +new_site = TSC.SiteItem(name='Tableau', content_url='tableau', admin_mode=content_users, user_quota=15, storage_quota=1000, disable_subscriptions=True) +# call the sites create method with the SiteItem +new_site = server.sites.create(new_site) ``` -
    -
    +
    -#### workbooks.populate_preview_image +#### sites.get_by_id ```py -workbooks.populate_preview_image(workbook_item) +sites.get_by_id(site_id) ``` -This method gets the preview image (thumbnail) for the specified workbook item. +Queries the site with the given ID. -The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `workbook_item.preview_image`. -REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69){:target="_blank"} +REST API: [Query Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Site){:target="_blank"} -**Parameters** +**Parameters** -Name | Description +Name | Description :--- | :--- -`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. - -**Exceptions** +`site_id` | The id for the site you want to query. -Error | Description -:--- | :--- -`View item missing ID or workbook ID` | Raises an error if the ID for the view item or workbook is missing. - +**Exceptions** -**Returns** +`Site ID undefined.` | Raises an error if an id is not specified. -None. The preview image is added to the view. +**Returns** +Returns the `SiteItem`. + -**Example** +**Example** ```py # import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. -# server = TSC.Server('http://SERVERURL') - - ... - - # get the workbook item - workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') - - # add the png thumbnail to the workbook item - server.workbooks.populate_preview_image(workbook) - + a_site = server.sites.get_by_id('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d') + print("\nThe site with id '9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d' is: {0}".format(a_site.name)) ```
    -
    +
    +#### sites.get +```py +sites.get() +``` +Queries all the sites on the server. -## Views -Using the TSC library, you can get all the views on a site, or get the views for a workbook, or populate a view with preview images. -The view resources for Tableau Server are defined in the `ViewItem` class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, you can find the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the `ViewItem` class. +REST API: [Query Sites](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Sites%3FTocPath%3DAPI%2520Reference%7C_____58){:target="_blank"} -
    +**Parameters** -### ViewItem class + None. -``` -class ViewItem(object) +**Returns** -``` +Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these values to iterate through the results. -The `ViewItem` class contains the members or attributes for the view resources on Tableau Server. The `ViewItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. -Source file: models/view_item.py +**Example** -**Attributes** +```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. -Name | Description -:--- | :--- -`id` | The identifier of the view item. -`name` | The name of the view. -`owner_id` | The id for the owner of the view. -`preview_image` | The thumbnail image for the view. -`total_views` | The usage statistics for the view. Indicates the total number of times the view has been looked at. -`workbook_id` | The id of the workbook associated with the view. + # query the sites + all_sites, pagination_item = server.sites.get() + + # print all the site names and ids + for site in TSC.Pager(server.sites): + print(site.id, site.name, site.content_url, site.state) -
    +``` + +

    -### Views methods +#### sites.update -The Tableau Server Client provides two methods for interacting with view resources, or endpoints. These methods correspond to the endpoints for views in the Tableau Server REST API. +```py +sites.update(site_item) +``` -Source file: server/endpoint/views_endpoint.py +Modifies the settings for site. -
    -
    -#### views.get -``` -views.get(req_option=None) -``` +The site item object must include the site ID and overrides all other settings. -Returns the list of views items for a site. +REST API: [Update Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Site%3FTocPath%3DAPI%2520Reference%7C_____84){:target="_blank"} -REST API: [Query Views for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Site%3FTocPath%3DAPI%2520Reference%7C_____64){:target="_blank"} -**Parameters** +**Parameters** -Name | Description +Name | Description :--- | :--- -`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific view, you could specify the name of the view or its id. +`site_item` | The site item that you want to update. The settings specified in the site item override the current site settings. +**Exceptions** -**Returns** +Error | Description +:--- | :--- +`Site item missing ID.` | The site id must be present and must match the id of the site you are updating. +`You cannot set admin_mode to ContentOnly and also set a user quota` | To set the `user_quota`, the `AdminMode` must be set to `ContentAndUsers` -Returns a list of all `ViewItem` objects and a `PaginationItem`. Use these values to iterate through the results. -**Example** +**Returns** -```py -import tableauserverclient as TSC -tableau_auth = TSC.TableauAuth('username', 'password') -server = TSC.Server('http://servername') +Returns the updated `site_item`. -with server.auth.sign_in(tableau_auth): - all_views, pagination_item = server.views.get() - print([view.name for view in all_views]) -```` +**Example** -See [ViewItem class](#viewitem-class) +```py +... +# make some updates to an existing site_item +site_item.name ="New name" -
    -
    +# call update +site_item = server.sites.update(site_item) -#### views.populate_preview_image +... +``` -```py - views.populate_preview_image(view_item) +
    +
    -``` -Populates a preview image for the specified view. -This method gets the preview image (thumbnail) for the specified view item. The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `view.preview_image` for the view. -REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69){:target="_blank"} +#### sites.delete -**Parameters** -Name | Description -:--- | :--- -`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. +```py +Sites.delete(site_id) +``` -**Exceptions** +Deletes the specified site. -Error | Description -:--- | :--- -`View item missing ID or workbook ID` | Raises an error if the ID for the view item or workbook is missing. - +REST API: [Delete Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Site%3FTocPath%3DAPI%2520Reference%7C_____27){:target="_name"} -**Returns** -None. The preview image is added to the view. +**Parameters** + -See [ViewItem class](#viewitem-class) +`site_id` | The id of the site that you want to delete. -
    -
    -## Data sources -Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project. -The data source resources for Tableau Server are defined in the `DatasourceItem` class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the `DatasourceItem` class. +**Exceptions** -
    +Error | Description +:--- | :--- +`Site ID Undefined.` | The site id must be present and must match the id of the site you are deleting. -### DatasourceItem class +**Example** ```py -DatasourceItem(project_id, name=None) -``` -The `DatasourceItem` represents the data source resources on Tableau Server. This is the information that can be sent or returned in the response to an REST API request for data sources. When you create a new `DatasourceItem` instance, you must specify the `project_id` that the data source is associated with. +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. -**Attributes** +server.sites.delete('9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d') -Name | Description -:--- | :--- -`connections` | The list of data connections (`ConnectionItem`) for the specified data source. You must first call the `populate_connections` method to access this data. See the [ConnectionItem class](#connectionitem-class). -`content_url` | The name of the data source as it would appear in a URL. -`created_at` | The date and time when the data source was created. -`datasource_type` | The type of data source, for example, `sqlserver` or `excel-direct`. -`id` | The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. -`name` | The name of the data source. If not specified, the name of the published data source file is used. -`project_id` | The identifer of the project associated with the data source. When you must provide this identifier when create an instance of a `DatasourceItem` -`project_name` | The name of the project associated with the data source. -`tags` | The tags that have been added to the data source. -`updated_at` | The date and time when the data source was last updated. +``` +
    +
    -**Example** + -```py - import tableauserverclient as TSC - # Create new datasource_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39' +## Sort - new_datasource = TSC.DatasourceItem('3a8b6148-493c-11e6-a621-6f3499394a39') -``` +The `Sort` class is used with request options (`RequestOptions`) where you can filter and sort on the results returned from the server. +You can use the sort and request options to filter and sort the following endpoints: -Source file: models/datasource_item.py +- Users +- Datasources +- Workbooks +- Views -
    -
    +### Sort class + +```py +sort(field, direction) +``` -### Datasources methods -The Tableau Server Client provides several methods for interacting with data source resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. -Source file: server/endpoint/datasources_endpoint.py +**Attributes** -
    -
    +Name | Description +:--- | :--- +`field` | Sets the field to sort on. The fields are defined in the `RequestOption` class. +`direction` | The direction to sort, either asscending (`Asc`) or descending (`Desc`). The options are defined in the `RequestOptions.Direction` class. -#### datasources.delete +**Example** -```py -datasources.delete(datasource_id) -``` +```py -Removes the specified data source from Tableau Server. +# create an new instance of a request option object +req_option = TSC.RequestOptions() +# add the sort expression, sorting by name and direction +req_option.sort.add(TSC.Sort(TSC.RequestOptions.Field.Name, + TSC.RequestOptions.Direction.Asc)) +matching_workbooks, pagination_item = server.workbooks.get(req_option) -**Parameters** +for wb in matching_workbooks: + print(wb.name) +``` -Name | Description -:--- | :--- -`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to delete from the server. +For information about using the `Sort` class, see [Filter and Sort](filter-sort). +
    +
    -**Exceptions** -`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. +## Users -REST API: [Delete Datasource](http://onlinehelp.tableau.com/v0.0/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Datasource%3FTocPath%3DAPI%2520Reference%7C_____19){:target="_blank"} +Using the TSC library, you can get information about all the users on a site, and you can add or remove users, or update user information. -
    -
    +The user resources for Tableau Server are defined in the `UserItem` class. The class corresponds to the user resources you can access using the Tableau Server REST API. The user methods are based upon the endpoints for users in the REST API and operate on the `UserItem` class. -#### datasources.download +### UserItem class ```py -datasources.download(datasource_id, filepath=None) - +UserItem(name, site_role, auth_setting=None) ``` -Downloads the specified data source in `.tdsx` format. -REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Datasource%3FTocPath%3DAPI%2520Reference%7C_____34){:target="_blank"} +The `UserItem` class contains the members or attributes for the view resources on Tableau Server. The `UserItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. -**Parameters** +**Attributes** Name | Description -:--- | :--- -`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. -`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. +:--- | :--- +`auth_setting` | (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for tis attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. +`domain_name` | The name of the site. +`external_auth_user_id` | Represents ID stored in Tableau's single sign-on (SSO) system. The `externalAuthUserId` value is returned for Tableau Online. For other server configurations, this field contains null. +`id` | The id of the user on the site. +`last_login` | The date and time the user last logged in. +`workbooks` | The workbooks the user owns. You must run the populate_workbooks method to add the workbooks to the `UserItem`. +`email` | The email address of the user. +`fullname` | The full name of the user. +`name` | The name of the user. This attribute is required when you are creating a `UserItem` instance. +`site_role` | The role the user has on the site. This attribute is required with you are creating a `UserItem` instance. The `site_role` can be one of the following: `Interactor`, `Publisher`, `ServerAdministrator`, `SiteAdministrator`, `Unlicensed`, `UnlicensedWithPublish`, `Viewer`, `ViewerWithPublish`, `Guest` -**Exceptions** +**Example** -Error | Description -:--- | :--- -`Datasource ID undefined` | Raises an exception if a valid `datasource_id` is not provided. +```py +# import tableauserverclient as TSC +# server = TSC.Server('server') +# create a new UserItem object. + newU = TSC.UserItem('Monty', 'Publisher') + + print(newU.name, newU.site_role) -**Returns** +``` -The file path to the downloaded data source. The data source is downloaded in `.tdsx` format. +Source file: models/user_item.py -**Example** +
    +
    -```py - file_path = server.datasources.download('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') - print("\nDownloaded the file to {0}.".format(file_path)) +### Users methods -```` +The Tableau Server Client provides several methods for interacting with user resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. - +Source file: server/endpoint/users_endpoint.py

    -#### datasources.get +#### users.add ```py -datasources.get(req_options=None) +users.add(user_item) ``` -Returns all the data sources for the site. +Adds the user to the site. -To get the connection information for each data source, you must first populate the `DatasourceItem` with connection information using the [populate_connections(*datasource_item*)](#populate-connections-datasource) method. For more information, see [Populate Connections and Views](populate-connections-views#populate-connections-for-data-sources) +To add a new user to the site you need to first create a new `user_item` (from `UserItem` class). When you create a new user, you specify the name of the user and their site role. For Tableau Online, you also specify the `auth_setting` attribute in your request. When you add user to Tableau Online, the name of the user must be the email address that is used to sign in to Tableau Online. After you add a user, Tableau Online sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password. -REST API: [Query Datasources](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasources%3FTocPath%3DAPI%2520Reference%7C_____49){:target="_blank"} +REST API: [Add User to Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Add_User_to_Site%3FTocPath%3DAPI%2520Reference%7C_____9){:target="_blank"} **Parameters** -Name | Description -:--- | :--- -`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific data source, you could specify the name of the project or its id. +`user_item` : You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. **Returns** -Returns a list of `DatasourceItem` objects and a `PaginationItem` object. Use these values to iterate through the results. +Returns the new `UserItem` object. @@ -1811,852 +1952,875 @@ Returns a list of `DatasourceItem` objects and a `PaginationItem` object. Use **Example** ```py -import tableauserverclient as TSC -tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -server = TSC.Server('http://SERVERURL') - -with server.auth.sign_in(tableau_auth): - all_datasources, pagination_item = server.datasources.get() - print("\nThere are {} datasources on site: ".format(pagination_item.total_available)) - print([datasource.name for datasource in all_datasources]) -```` - +# import tableauserverclient as TSC +# server = TSC.Server('server') +# login, etc. +# create a new UserItem object. + newU = TSC.UserItem('Heather', 'Publisher') -
    -
    +# add the new user to the site + newU = server.users.add(newU) + print(newU.name, newU.site_role) +``` -#### datasources.get_by_id +#### users.get ```py -datasources.get_by_id(datasource_id) +users.get(req_options=None) ``` -Returns the specified data source item. - -REST API: [Query Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource%3FTocPath%3DAPI%2520Reference%7C_____46){:target="_blank"} - +Returns information about the users on the specified site. -**Parameters** +To get information about the workbooks a user owns or has view permission for, you must first populate the `UserItem` with workbook information using the [populate_workbooks(*user_item*)](#populate-workbooks-user) method. -Name | Description -:--- | :--- -`datasource_id` | The `datasource_id` specifies the data source to query. +REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} -**Exceptions** +**Parameters** -Error | Description -:--- | :--- -`Datasource ID undefined` | Raises an exception if a valid `datasource_id` is not provided. +``req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. **Returns** -The `DatasourceItem`. See [DatasourceItem class](#datasourceitem-class) +Returns a list of `UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. **Example** -```py - -datasource = server.datasources.get_by_id('59a57c0f-3905-4022-9e87-424fb05e9c0e') -print(datasource.name) - -``` +```py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +server = TSC.Server('http://SERVERURL') -
    -
    +with server.auth.sign_in(tableau_auth): + all_users, pagination_item = server.users.get() + print("\nThere are {} user on site: ".format(pagination_item.total_available)) + print([user.name for user in all_users]) +```` - +
    +
    -#### datasources.populate_connections +#### users.get_by_id ```py -datasources.populate_connections(datasource_item) +users.get_by_id(user_id) ``` -Populates the connections for the specified data source. - - - +Returns information about the specified user. -This method retrieves the connection information for the specified data source. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the connection information is not included. Use this method to retrieve the connections. The method adds the list of data connections to the data source item (`datasource_item.connections`). This is a list of `ConnectionItem` objects. +REST API: [Query User On Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_User_On_Site%3FTocPath%3DAPI%2520Reference%7C_____61){:target="_blank"} -REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47){:target="_blank"} **Parameters** -Name | Description -:--- | :--- -`datasource_item` | The `datasource_item` specifies the data source to populate with connection information. - - +`user_id` : The `user_id` specifies the user to query. **Exceptions** -Error | Description -:--- | :--- -`Datasource item missing ID. Datasource must be retrieved from server first.` | Raises an errror if the datasource_item is unspecified. +`User ID undefined.` : Raises an exception if a valid `user_id` is not provided. **Returns** -None. A list of `ConnectionItem` objects are added to the data source (`datasource_item.connections`). +The `UserItem`. See [UserItem class](#useritem-class) **Example** ```py -# import tableauserverclient as TSC - -# server = TSC.Server('http://SERVERURL') -# - ... - -# get the data source - datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') - + user1 = server.users.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + print(user1.name) -# get the connection information - server.datasources.populate_connections(datasource) +``` -# print the information about the first connection item - print(datasource.connections[0].connection_type) - print(datasource.connections[0].id) - print(datasource.connections[0].server_address) +
    +
    - ... +#### users.populate_favorites + +```py +users.populate_favorites(user_item) ``` +Returns the list of favorites (views, workbooks, and data sources) for a user. + +*Not currently implemented*
    -
    +
    -#### datasources.publish + +#### users.populate_workbooks ```py -datasources.publish(datasource_item, file_path, mode, connection_credentials=None) +users.populate_workbooks(user_item, req_options=None): ``` -Publishes a data source to a server, or appends data to an existing data source. +Returns information about the workbooks that the specified user owns and has Read (view) permissions for. -This method checks the size of the data source and automatically determines whether the publish the data source in multiple parts or in one opeation. -REST API: [Publish Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Datasource%3FTocPath%3DAPI%2520Reference%7C_____44){:target="_blank"} +This method retrieves the workbook information for the specified user. The REST API is designed to return only the information you ask for explicitly. When you query for all the users, the workbook information for each user is not included. Use this method to retrieve information about the workbooks that the user owns or has Read (view) permissions. The method adds the list of workbooks to the user item object (`user_item.workbooks`). -**Parameters** +REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47){:target="_blank"} -Name | Description -:--- | :--- -`datasource_item` | The `datasource_item` specifies the new data source you are adding, or the data source you are appending to. If you are adding a new data source, you need to create a new `datasource_item` with a `project_id` of an existing project. The name of the data source will be the name of the file, unless you also specify a name for the new data source when you create the instance. See [DatasourceItem](#datasourceitem-class). -`file_path` | The path and name of the data source to publish. -`mode` | Specifies whether you are publishing a new data source (`CreateNew`), overwriting an existing data source (`Overwrite`), or appending data to a data source (`Append`). If you are appending to a data source, the data source on the server and the data source you are publishing must be be extracts (.tde files) and they must share the same schema. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. -`connection_credentials` | (Optional) The credentials required to connect to the data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). - +**Parameters** +`user_item` : The `user_item` specifies the user to populate with workbook information. -**Exceptions** -Error | Description -:--- | :--- -`File path does not lead to an existing file.` | Raises an error of the file path is incorrect or if the file is missing. -`Invalid mode defined.` | Raises an error if the publish mode is not one of the defined options. -`Only .tds, tdsx, or .tde files can be published as datasources.` | Raises an error if the type of file specified is not supported. -**Returns** +**Exceptions** -The `DatasourceItem` for the data source that was added or appened to. +`User item missing ID.` : Raises an errror if the `user_item` is unspecified. -**Example** +**Returns** -```py +A list of `WorkbookItem` - import tableauserverclient as TSC - server = TSC.Server('http://SERVERURL') - - ... +A `PaginationItem` that points (`user_item.workbooks`). See [UserItem class](#useritem-class) - project_id = '3a8b6148-493c-11e6-a621-6f3499394a39' - file_path = 'C:\\temp\\WorldIndicators.tde' - # Use the project id to create new datsource_item - new_datasource = TSC.DatasourceItem(project_id) +**Example** - # publish data source (specifed in file_path) - new_datasource = server.datasources.publish( - new_datasource, file_path, 'CreateNew') +```py +# first get all users, call server.users.get() +# get workbooks for user[0] + ... + + page_n = server.users.populate_workbooks(all_users[0]) + print("\nUser {0} owns or has READ permissions for {1} workbooks".format(all_users[0].name, page_n.total_available)) + print("\nThe workbooks are:") + for workbook in all_users[0].workbooks : + print(workbook.name) ... ``` + + +
    -
    +
    -#### datasources.update +#### users.remove ```py -datasource.update(datasource_item) +users.remove(user_id) ``` -Updates the owner, or project of the specified data source. - -REST API: [Update Datasource](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Datasource%3FTocPath%3DAPI%2520Reference%7C_____79){:target="_blank"} -**Parameters** -`datasource_item` : The `datasource_item` specifies the data source to update. +Removes the specified user from the site. +REST API: [Remove User from Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Site%3FTocPath%3DAPI%2520Reference%7C_____74){:target="_blank"} -**Exceptions** +**Parameters** -`Datasource item missing ID. Datasource must be retrieved from server first.` : Raises an errror if the datasource_item is unspecified. Use the `Datasources.get()` method to retrieve that identifies for the data sources on the server. +`user_id` : The identifier (`id`) for the the user that you want to remove from the server. -**Returns** +**Exceptions** -An updated `DatasourceItem`. +`User ID undefined` : Raises an exception if a valid `user_id` is not provided. **Example** ```py -# from server-client-python/test/test_datasource.py +# Remove a user from the site + +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + with server.auth.sign_in(tableau_auth): + server.users.remove('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') + +``` +
    +
    - ... - single_datasource = TSC.DatasourceItem('test', '1d0304cd-3796-429f-b815-7258370b9b74') - # need to specify the ID - this is a workaround. - single_datasource._id = '9dbd2263-16b5-46e1-9c43-a76bb8ab65fb' - single_datasource._tags = ['a', 'b', 'c'] - single_datasource._project_name = 'Tester' - updated_datasource = self.server.datasources.update(single_datasource) - ... +#### users.update + +```py +users.update(user_item, password=None) ``` +Updates information about the specified user. +The information you can modify depends upon whether you are using Tableau Server or Tableau Online, and whether you have configured Tableau Server to use local authentication or Active Directory. For more information, see [Update User](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_User%3FTocPath%3DAPI%2520Reference%7C_____86){:target="_blank"}. -
    -
    -## Users -Using the TSC library, you can get information about all the users on a site, and you can add or remove users, or update user information. +REST API: [Update User](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_User%3FTocPath%3DAPI%2520Reference%7C_____86){:target="_blank"} -The user resources for Tableau Server are defined in the `UserItem` class. The class corresponds to the user resources you can access using the Tableau Server REST API. The user methods are based upon the endpoints for users in the REST API and operate on the `UserItem` class. +**Parameters** +`user_item` : The `user_item` specifies the user to update. -### UserItem class +`password` : (Optional) The new password for the user. -```py -UserItem(name, site_role, auth_setting=None) -``` -The `UserItem` class contains the members or attributes for the view resources on Tableau Server. The `UserItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. -**Attributes** +**Exceptions** -Name | Description -:--- | :--- -`auth_setting` | (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for tis attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. -`domain_name` | The name of the site. -`external_auth_user_id` | Represents ID stored in Tableau's single sign-on (SSO) system. The `externalAuthUserId` value is returned for Tableau Online. For other server configurations, this field contains null. -`id` | The id of the user on the site. -`last_login` | The date and time the user last logged in. -`workbooks` | The workbooks the user owns. You must run the populate_workbooks method to add the workbooks to the `UserItem`. -`email` | The email address of the user. -`fullname` | The full name of the user. -`name` | The name of the user. This attribute is required when you are creating a `UserItem` instance. -`site_role` | The role the user has on the site. This attribute is required with you are creating a `UserItem` instance. The `site_role` can be one of the following: `Interactor`, `Publisher`, `ServerAdministrator`, `SiteAdministrator`, `Unlicensed`, `UnlicensedWithPublish`, `Viewer`, `ViewerWithPublish`, `Guest` +`User item missing ID.` : Raises an errror if the `user_item` is unspecified. + + +**Returns** + +An updated `UserItem`. See [UserItem class](#useritem-class) **Example** ```py -# import tableauserverclient as TSC -# server = TSC.Server('server') -# create a new UserItem object. - newU = TSC.UserItem('Monty', 'Publisher') +# import tableauserverclient as TSC +# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') +# server = TSC.Server('http://SERVERURL') + + with server.auth.sign_in(tableau_auth): + + # create a new user_item + user1 = TSC.UserItem('temp', 'Viewer') + + # add new user + user1 = server.users.add(user1) + print(user1.name, user1.site_role, user1.id) + + # modify user info + user1.name = 'Laura' + user1.fullname = 'Laura Rodriguez' + user1.email = 'laura@example.com' - print(newU.name, newU.site_role) + # update user + user1 = server.users.update(user1) + print("\Updated user info:") + print(user1.name, user1.fullname, user1.email, user1.id) + ``` -Source file: models/user_item.py -
    -
    +
    +
    -### Users methods -The Tableau Server Client provides several methods for interacting with user resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. -Source file: server/endpoint/users_endpoint.py -
    -
    -#### users.add +## Views -```py -users.add(user_item) -``` +Using the TSC library, you can get all the views on a site, or get the views for a workbook, or populate a view with preview images. +The view resources for Tableau Server are defined in the `ViewItem` class. The class corresponds to the view resources you can access using the Tableau Server REST API, for example, you can find the name of the view, its id, and the id of the workbook it is associated with. The view methods are based upon the endpoints for views in the REST API and operate on the `ViewItem` class. -Adds the user to the site. -To add a new user to the site you need to first create a new `user_item` (from `UserItem` class). When you create a new user, you specify the name of the user and their site role. For Tableau Online, you also specify the `auth_setting` attribute in your request. When you add user to Tableau Online, the name of the user must be the email address that is used to sign in to Tableau Online. After you add a user, Tableau Online sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password. +
    -REST API: [Add User to Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Add_User_to_Site%3FTocPath%3DAPI%2520Reference%7C_____9){:target="_blank"} +### ViewItem class -**Parameters** +``` +class ViewItem(object) + +``` -`user_item` : You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. +The `ViewItem` class contains the members or attributes for the view resources on Tableau Server. The `ViewItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. +Source file: models/view_item.py -**Returns** +**Attributes** -Returns the new `UserItem` object. +Name | Description +:--- | :--- +`id` | The identifier of the view item. +`name` | The name of the view. +`owner_id` | The id for the owner of the view. +`preview_image` | The thumbnail image for the view. +`total_views` | The usage statistics for the view. Indicates the total number of times the view has been looked at. +`workbook_id` | The id of the workbook associated with the view. +
    +
    -**Example** +### Views methods -```py -# import tableauserverclient as TSC -# server = TSC.Server('server') -# login, etc. +The Tableau Server Client provides two methods for interacting with view resources, or endpoints. These methods correspond to the endpoints for views in the Tableau Server REST API. -# create a new UserItem object. - newU = TSC.UserItem('Heather', 'Publisher') +Source file: server/endpoint/views_endpoint.py -# add the new user to the site - newU = server.users.add(newU) - print(newU.name, newU.site_role) +
    +
    +#### views.get ``` - -#### users.get - -```py -users.get(req_options=None) +views.get(req_option=None) ``` -Returns information about the users on the specified site. +Returns the list of views items for a site. -To get information about the workbooks a user owns or has view permission for, you must first populate the `UserItem` with workbook information using the [populate_workbooks(*user_item*)](#populate-workbooks-user) method. +REST API: [Query Views for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Site%3FTocPath%3DAPI%2520Reference%7C_____64){:target="_blank"} -REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} +**Parameters** -**Parameters** +Name | Description +:--- | :--- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific view, you could specify the name of the view or its id. -``req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. **Returns** -Returns a list of `UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. - +Returns a list of all `ViewItem` objects and a `PaginationItem`. Use these values to iterate through the results. **Example** - ```py import tableauserverclient as TSC -tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -server = TSC.Server('http://SERVERURL') +tableau_auth = TSC.TableauAuth('username', 'password') +server = TSC.Server('http://servername') with server.auth.sign_in(tableau_auth): - all_users, pagination_item = server.users.get() - print("\nThere are {} user on site: ".format(pagination_item.total_available)) - print([user.name for user in all_users]) + all_views, pagination_item = server.views.get() + print([view.name for view in all_views]) + ```` -
    +See [ViewItem class](#viewitem-class) + + +

    -#### users.get_by_id +#### views.populate_preview_image ```py -users.get_by_id(user_id) -``` + views.populate_preview_image(view_item) -Returns information about the specified user. +``` -REST API: [Query User On Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_User_On_Site%3FTocPath%3DAPI%2520Reference%7C_____61){:target="_blank"} +Populates a preview image for the specified view. +This method gets the preview image (thumbnail) for the specified view item. The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `view.preview_image` for the view. -**Parameters** +REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69){:target="_blank"} -`user_id` : The `user_id` specifies the user to query. +**Parameters** +Name | Description +:--- | :--- +`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. -**Exceptions** +**Exceptions** -`User ID undefined.` : Raises an exception if a valid `user_id` is not provided. +Error | Description +:--- | :--- +`View item missing ID or workbook ID` | Raises an error if the ID for the view item or workbook is missing. + **Returns** -The `UserItem`. See [UserItem class](#useritem-class) +None. The preview image is added to the view. +See [ViewItem class](#viewitem-class) -**Example** +
    +
    -```py - user1 = server.users.get_by_id('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') - print(user1.name) -``` -
    -
    -#### users.populate_favorites - -```py -users.populate_favorites(user_item) -``` +## Workbooks -Returns the list of favorites (views, workbooks, and data sources) for a user. +Using the TSC library, you can get information about a specific workbook or all the workbooks on a site, and you can publish, update, or delete workbooks. -*Not currently implemented* +The project resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. The workbook methods are based upon the endpoints for projects in the REST API and operate on the `WorkbookItem` class. -
    -
    -#### users.populate_workbooks -```py -users.populate_workbooks(user_item, req_options=None): -``` -Returns information about the workbooks that the specified user owns and has Read (view) permissions for. +
    +
    +### WorkbookItem class -This method retrieves the workbook information for the specified user. The REST API is designed to return only the information you ask for explicitly. When you query for all the users, the workbook information for each user is not included. Use this method to retrieve information about the workbooks that the user owns or has Read (view) permissions. The method adds the list of workbooks to the user item object (`user_item.workbooks`). +```py + + WorkbookItem(project_id, name=None, show_tabs=False) + +``` +The workbook resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. Some workbook methods take an instance of the `WorkbookItem` class as arguments. The workbook item specifies the project -REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Datasource_Connections%3FTocPath%3DAPI%2520Reference%7C_____47){:target="_blank"} -**Parameters** +**Attributes** -`user_item` : The `user_item` specifies the user to populate with workbook information. +Name | Description +:--- | :--- +`connections` | The list of data connections (`ConnectionItem`) for the data sources used by the workbook. You must first call the [workbooks.populate_connections](#workbooks.populate_connections) method to access this data. See the [ConnectionItem class](#connectionitem-class). +`content_url` | The name of the data source as it would appear in a URL. +`created_at` | The date and time when the data source was created. +`id` | The identifier for the workbook. You need this value to query a specific workbook or to delete a workbook with the `get_by_id` and `delete` methods. +`name` | The name of the workbook. +`owner_id` | The ID of the owner. +`preview_image` | The thumbnail image for the view. You must first call the [workbooks.populate_preview_image](#workbooks.populate_preview_image) method to access this data. +`project_id` | The project id. +`project_name` | The name of the project. +`size` | The size of the workbook (in megabytes). +`show_tabs` | (Boolean) Determines whether the workbook shows tabs for the view. +`tags` | The tags that have been added to the workbook. +`updated_at` | The date and time when the workbook was last updated. +`views` | The list of views (`ViewItem`) for the workbook. You must first call the [workbooks.populate_views](#workbooks.populate_views) method to access this data. See the [ViewItem class](#viewitem-class). -**Exceptions** -`User item missing ID.` : Raises an errror if the `user_item` is unspecified. +**Example** +```py +# creating a new instance of a WorkbookItem +# +import tableauserverclient as TSC -**Returns** +# Create new workbook_item with project id '3a8b6148-493c-11e6-a621-6f3499394a39' -A list of `WorkbookItem` + new_workbook = TSC.WorkbookItem('3a8b6148-493c-11e6-a621-6f3499394a39') -A `PaginationItem` that points (`user_item.workbooks`). See [UserItem class](#useritem-class) +```` -**Example** +Source file: models/workbook_item.py -```py -# first get all users, call server.users.get() -# get workbooks for user[0] - ... +
    +
    - page_n = server.users.populate_workbooks(all_users[0]) - print("\nUser {0} owns or has READ permissions for {1} workbooks".format(all_users[0].name, page_n.total_available)) - print("\nThe workbooks are:") - for workbook in all_users[0].workbooks : - print(workbook.name) +### Workbook methods - ... -``` +The Tableau Server Client (TSC) library provides methods for interacting with workbooks. These methods correspond to endpoints in the Tableau Server REST API. For example, you can use the library to publish, update, download, or delete workbooks on the site. +The methods operate on a workbook object (`WorkbookItem`) that represents the workbook resources. +Source files: server/endpoint/workbooks_endpoint.py -
    +

    -#### users.remove +#### workbooks.get ```py -users.remove(user_id) +workbooks.get(req_options=None) ``` +Queries the server and returns information about the workbooks the site. -Removes the specified user from the site. -REST API: [Remove User from Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Site%3FTocPath%3DAPI%2520Reference%7C_____74){:target="_blank"} + + +REST API: [Query Workbooks for Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbooks_for_Site%3FTocPath%3DAPI%2520Reference%7C_____70){:target="_blank"} **Parameters** -`user_id` : The identifier (`id`) for the the user that you want to remove from the server. +Name | Description +:--- | :--- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific workbook, you could specify the name of the workbook or the name of the owner. See [Filter and Sort](filter-sort) -**Exceptions** +**Returns** -`User ID undefined` : Raises an exception if a valid `user_id` is not provided. +Returns a list of all `WorkbookItem` objects and a `PaginationItem`. Use these values to iterate through the results. **Example** -```py -# Remove a user from the site +```py + +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') +server = TSC.Server('http://servername') + +with server.auth.sign_in(tableau_auth): + all_workbook_items, pagination_item = server.workbooks.get() + print([workbook.name for workbook in all_workbooks]) -# import tableauserverclient as TSC -# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -# server = TSC.Server('http://SERVERURL') - with server.auth.sign_in(tableau_auth): - server.users.remove('9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') ``` -
    -
    +
    +
    -#### users.update +#### workbooks.get_by_id ```py -users.update(user_item, password=None) +workbooks.get_by_id(workbook_id) ``` -Updates information about the specified user. - -The information you can modify depends upon whether you are using Tableau Server or Tableau Online, and whether you have configured Tableau Server to use local authentication or Active Directory. For more information, see [Update User](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_User%3FTocPath%3DAPI%2520Reference%7C_____86){:target="_blank"}. - +Returns information about the specified workbook on the site. +REST API: [Query Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook%3FTocPath%3DAPI%2520Reference%7C_____66){:target="_blank"} -REST API: [Update User](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_User%3FTocPath%3DAPI%2520Reference%7C_____86){:target="_blank"} **Parameters** -`user_item` : The `user_item` specifies the user to update. - -`password` : (Optional) The new password for the user. - +Name | Description +:--- | :--- +`workbook_id` | The `workbook_id` specifies the workbook to query. The ID is a LUID (64-bit hexadecimal string). **Exceptions** -`User item missing ID.` : Raises an errror if the `user_item` is unspecified. +`Workbook ID undefined` : Raises an exception if a `workbook_id` is not provided. **Returns** -An updated `UserItem`. See [UserItem class](#useritem-class) +The `WorkbookItem`. See [WorkbookItem class](#workbookitem-class) **Example** ```py -# import tableauserverclient as TSC -# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -# server = TSC.Server('http://SERVERURL') - - with server.auth.sign_in(tableau_auth): - - # create a new user_item - user1 = TSC.UserItem('temp', 'Viewer') - - # add new user - user1 = server.users.add(user1) - print(user1.name, user1.site_role, user1.id) - - # modify user info - user1.name = 'Laura' - user1.fullname = 'Laura Rodriguez' - user1.email = 'laura@example.com' - - # update user - user1 = server.users.update(user1) - print("\Updated user info:") - print(user1.name, user1.fullname, user1.email, user1.id) - +workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') +print(workbook.name) ``` -

    -## Groups - -Using the TSC library, you can get information about all the groups on a site, you can add or remove groups, or add or remove users in a group. - -The group resources for Tableau Server are defined in the `GroupItem` class. The class corresponds to the group resources you can access using the Tableau Server REST API. The group methods are based upon the endpoints for groups in the REST API and operate on the `GroupItem` class. - -
    -
    -### GroupItem class +#### workbooks.publish ```py -GroupItem(name) +workbooks.publish(workbook_item, file_path, publish_mode) ``` -The `GroupItem` class contains the members or attributes for the view resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. +Publish a workbook to the specified site. -Source file: models/group_item.py +**Note:** The REST API cannot automatically include +extracts or other resources that the workbook uses. Therefore, + a .twb file that usess data from an Excel or csv file on a local computer cannot be published, +unless you package the data and workbook in a .twbx file, or publish the data source separately. -**Attributes** +For workbooks that are larger than 64 MB, the publish method automatically takes care of chunking the file in parts for uploading. Using this method is considerably more convenient than calling the publish REST APIs directly. -`domain_name` : The name of the Active Directory domain (`local` if local authentication is used). -`id` : The id of the group. -`users` : The list of users (`UserItem`). -`name` : The name of the group. The `name` is required when you create an instance of a group. +REST API: [Publish Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Workbook%3FTocPath%3DAPI%2520Reference%7C_____45){:target="_blank"}, [Initiate File Upload](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Initiate_File_Upload%3FTocPath%3DAPI%2520Reference%7C_____43){:target="_blank"}, [Append to File Upload](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Append_to_File_Upload%3FTocPath%3DAPI%2520Reference%7C_____13){:target="_blank"} -**Example** +**Parameters** -```py - newgroup = TSC.GroupItem('My Group') -``` +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that inlcudes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class). +`file_path` | The path and name of the workbook to publish. +`mode` | Specifies whether you are publishing a new workbook (`CreateNew`) or overwriting an existing workbook (`Overwrite`). You cannot appending workbooks. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. +`connection_credentials` | (Optional) The credentials (if required) to connect to the workbook's data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). + +**Exceptions** +Error | Description +:--- | :--- +`File path does not lead to an existing file.` | Raises an error of the file path is incorrect or if the file is missing. +`Invalid mode defined.` | Raises an error if the publish mode is not one of the defined options. +`Workbooks cannot be appended.` | The `mode` must be set to `Overwrite` or `CreateNew`. +`Only .twb or twbx files can be published as workbooks.` | Raises an error if the type of file specified is not supported. -
    -
    +See the REST API [Publish Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Publish_Workbook%3FTocPath%3DAPI%2520Reference%7C_____45){:target="_blank"} for additional error codes. -### Groups methods +**Returns** -The Tableau Server Client provides several methods for interacting with group resources, or endpoints. These methods correspond to endpoints in the Tableau Server REST API. +The `WorkbookItem` for the workbook that was published. + +**Example** +```py -Source file: server/endpoint/groups_endpoint.py +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') +server = TSC.Server('http://servername') -
    -
    +with server.auth.sign_in(tableau_auth): + # create a workbook item + wb_item = TSC.WorkbookItem(name='Sample', project_id='1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e') + # call the publish method with the workbook item + wb_item = server.workbooks.publish(wb_item, 'SampleWB.twbx', 'Overwrite') +``` -#### groups.add_user +
    +
    + + +#### workbooks.update ```py -groups.add_user(group_item, user_id): +workbooks.update(workbook_item) ``` -Adds a user to the specified group. +Modifies an existing workbook. Use this method to change the owner or the project that the workbook belongs to, or to change whether the workbook shows views in tabs. The workbook item must include the workbook ID and overrides the existing settings. -REST API [Add User to Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Add_User_to_Group%3FTocPath%3DAPI%2520Reference%7C_____8){:target="_blank"} +REST API: [Update Workbooks](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Workbook%3FTocPath%3DAPI%2520Reference%7C_____87){:target="_blank"} **Parameters** -`group_item` : The `group_item` specifies the group to update. +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the settings for the workbook you are updating. You can change the `owner_id`, `project_id`, and the `show_tabs` values. See [WorkbookItem](#workbookitem-class). -`user_id` : The id of the user. +**Exceptions** +Error | Description +:--- | :--- +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. Use the `workbooks.get()` or `workbooks.get_by_id()` methods to retreive the workbook item from the server. -**Returns** +```py -None. +import tableauserverclient as TSC +tableau_auth = TSC.TableauAuth('username', 'password', site_id='site') +server = TSC.Server('http://servername') +with server.auth.sign_in(tableau_auth): -**Example** + # get the workbook item from the site + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + print("\nUpdate {0} workbook. Project was {1}".format(workbook.name, workbook.project_name)) -```py -# Adding a user to a group -# Using the second group on the site, aleady have all_groups -# The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba' -# add Ian to the second group - server.groups.add_user(all_groups[1], '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba') + # make an change, for example a new project ID + workbook.project_id = '1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e' -# populate the GroupItem with the users - pagination_item = server.groups.populate_users(all_groups[1]) + # call the update method + workbook = server.workbooks.update(workbook) + print("\nUpdated {0} workbook. Project is now {1}".format(workbook.name, workbook.project_name)) - for user in all_groups[1].users : - print(user.name) ``` -
    +
    +
    -#### groups.create + + +#### workbooks.delete ```py -create(group_item) +workbooks.delete(workbook_id) ``` -Creates a new group in Tableau Server. +Deletes a workbook with the specified ID. -REST API: [Create Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Create_Group%3FTocPath%3DAPI%2520Reference%7C_____14){:target="_blank"} +To specify the site, create a `TableauAuth` instance using the content URL for the site (`site_id`), and sign in to that site. See the [TableauAuth class](#tableauauth-class). -**Parameters** -`group_item` : The `group_item` specifies the group to add. You first create a new instance of a `GroupItem` and pass that to this method. +REST API: [Delete Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Workbook%3FTocPath%3DAPI%2520Reference%7C_____31){:target="_blank"} +**Parameters** +Name | Description +:--- | :--- +`workbook_id` | The ID of the workbook to delete. -**Returns** -Adds new `GroupItem`. +**Exceptions** +Error | Description +:--- | :--- +`Workbook ID undefined.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. -**Example** +**Example** + ```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# tableau_auth sign in, etc. -# Create a new group - -# import tableauserverclient as TSC -# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -# server = TSC.Server('http://SERVERURL') - - -# create a new instance with the group name - newgroup = TSC.GroupItem('My Group') + server.workbooks.delete('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') -# call the create method - newgroup = server.groups.create(newgroup) +``` -# print the names of the groups on the server - all_groups, pagination_item = server.groups.get() - for group in all_groups : - print(group.name, group.id) -``` -
    +

    -#### groups.delete + +#### workbooks.download ```py -groups.delete(group_id) +workbooks.download(workbook_id, filepath=None) ``` -Deletes the group on the site. +Downloads a workbook to the specified directory (optional). -REST API: [Delete Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Site%3FTocPath%3DAPI%2520Reference%7C_____74){:target="_blank"} + +REST API: [Download Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Download_Workbook%3FTocPath%3DAPI%2520Reference%7C_____36){:target="_blank"} **Parameters** -`group_id` : The identifier (`id`) for the the group that you want to remove from the server. +Name | Description +:--- | :--- +`workbook_id` | The ID for the the `WorkbookItem` that you want to download from the server. +`filepath` | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default is `Filepath=None`. **Exceptions** -`Group ID undefined` : Raises an exception if a valid `group_id` is not provided. +Error | Description +:--- | :--- +`Workbook ID undefined` | Raises an exception if a valid `datasource_id` is not provided. + + +**Returns** + +The file path to the downloaded workbook. **Example** ```py -# Delete a group from the site -# import tableauserverclient as TSC -# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -# server = TSC.Server('http://SERVERURL') + file_path = server.workbooks.download('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + print("\nDownloaded the file to {0}.".format(file_path)) + +```` - with server.auth.sign_in(tableau_auth): - server.groups.delete('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') -``` -

    +
    -#### groups.get + +#### workbooks.populate_views ```py -groups.get(req_options=None) +workbooks.populate_views(workbook_item) ``` -Returns information about the groups on the site. - +Populates (or gets) a list of views for a workbook. -To get information about the users in a group, you must first populate the `GroupItem` with user information using the [groups.populate_users](api-ref#groupspopulateusers) method. +You must first call this method to populate views before you can iterate through the views. +This method retrieves the view information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query for all the data sources, the view information is not included. Use this method to retrieve the views. The method adds the list of views to the workbook item (`workbook_item.views`). This is a list of `ViewItem`. -REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} +REST API: [Query Views for Workbook](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Views_for_Workbook%3FTocPath%3DAPI%2520Reference%7C_____65){:target="_blank"} **Parameters** -`req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific groups, you could specify the name of the group or the group id. +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the workbook to populate with views information. See [WorkbookItem class](#workbookitem-class). + + + + +**Exceptions** + +Error | Description +:--- | :--- +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. You can retreive the workbook items using the `workbooks.get()` and `workbooks.get_by_id()` methods. **Returns** -Returns a list of `GroupItem` objects and a `PaginationItem` object. Use these values to iterate through the results. +None. A list of `ViewItem` objects are added to the workbook (`workbook_item.views`). **Example** - ```py # import tableauserverclient as TSC -# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') -# server = TSC.Server('http://SERVERURL') - with server.auth.sign_in(tableau_auth): +# server = TSC.Server('http://SERVERURL') +# + ... - # get the groups on the server - all_groups, pagination_item = server.groups.get() +# get the workbook item + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') - # print the names of the groups - for group in all_groups : - print(group.name, group.id) -```` +# get the view information + server.workbooks.populate_views(workbook) -
    -
    +# print information about the views for the work item + print("\nThe views for {0}: ".format(workbook.name)) + print([view.name for view in workbook.views]) -#### groups.populate_users + ... -```py -groups.populate_users(group_item, req_options=None) ``` -Populates the `group_item` with the list of users. +
    +
    +#### workbooks.populate_connections -REST API: [Get Users in Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_in_Group){:target="_blank"} +```py +workbooks.populate_connections(workbook_item) +``` + +Populates a list of data source connections for the specified workbook. + +You must populate connections before you can iterate through the +connections. + +This method retrieves the data source connection information for the specified workbook. The REST API is designed to return only the information you ask for explicitly. When you query all the workbooks, the data source connection information is not included. Use this method to retrieve the connection information for any data sources used by the workbook. The method adds the list of data connections to the workbook item (`workbook_item.connections`). This is a list of `ConnectionItem`. + +REST API: [Query Workbook Connections](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Connections%3FTocPath%3DAPI%2520Reference%7C_____67){:target="_blank"} **Parameters** -`group_item` : The `group_item` specifies the group to populate with user information. +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the workbook to populate with data connection information. -`req_options` : (Optional) Additional request options to send to the endpoint. **Exceptions** -`Group item missing ID. Group must be retrieved from server first.` : Raises an errror if the `group_item` is unspecified. +Error | Description +:--- | :--- +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. **Returns** -None. A list of `UserItem` objects are added to the group (`group_item.users`). +None. A list of `ConnectionItem` objects are added to the data source (`workbook_item.connections`). **Example** @@ -2668,76 +2832,78 @@ None. A list of `UserItem` objects are added to the group (`group_item.users`). # ... -# get the group - mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') - +# get the workbook item + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') -# get the user information - pagination_item = server.groups.populate_users(mygroup) +# get the connection information + server.workbooks.populate_connections(workbook) -# print the information about the first connection item - for user in mygroup.users : - print(user.name) - +# print information about the data connections for the workbook item + print("\nThe connections for {0}: ".format(workbook.name)) + print([connection.id for connection in workbook.connections]) + ... ``` -
    +

    -#### groups.remove_user + +#### workbooks.populate_preview_image ```py -groups.remove_user(group_item, user_id) +workbooks.populate_preview_image(workbook_item) ``` -Removes a user from a group. - - - - -REST API: [Remove User from Group](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Remove_User_from_Group%3FTocPath%3DAPI%2520Reference%7C_____73){:target="_blank"} - - -**Parameters** +This method gets the preview image (thumbnail) for the specified workbook item. -`group_item` : The `group_item` specifies the group to remove the user from. +The method uses the `view.id` and `workbook.id` to identify the preview image. The method populates the `workbook_item.preview_image`. -`user_id` : The id for the user. +REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Workbook_Preview_Image%3FTocPath%3DAPI%2520Reference%7C_____69){:target="_blank"} +**Parameters** +Name | Description +:--- | :--- +`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. -**Exceptions** +**Exceptions** -`Group must be populated with users first.` : Raises an errror if the `group_item` is unpopulated. +Error | Description +:--- | :--- +`View item missing ID or workbook ID` | Raises an error if the ID for the view item or workbook is missing. + **Returns** -None. The user is removed from the group. +None. The preview image is added to the view. + **Example** ```py -# Remove a user from the group # import tableauserverclient as TSC -# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') + # server = TSC.Server('http://SERVERURL') - with server.auth.sign_in(tableau_auth): + ... - # get the group - mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') + # get the workbook item + workbook = server.workbooks.get_by_id('1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d') + + # add the png thumbnail to the workbook item + server.workbooks.populate_preview_image(workbook) - # remove user '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d' - server.groups.remove_user(mygroup, '9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d') ``` -

    +
    + + From 9e2e795fa9b69a1c6c81228889b2ed092b794fac Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Fri, 14 Apr 2017 12:48:58 -0700 Subject: [PATCH 11/17] ready for review.... --- docs/docs/api-ref.md | 94 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 75 insertions(+), 19 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 6efe5255d..c41bf4d98 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -3,10 +3,21 @@ title: API reference layout: docs --- -
    + + + + +The Tableau Server Client (TSC) is a Python library for the Tableau Server REST API. Using the TSC library, you can manage and change many of the Tableau Server and Tableau Online resources programmatically. You can use this library to create your own custom applications. + +The TSC API reference is organized by resource. The TSC library is modeled after the REST API. The methods, for example, `workbooks.get()`, correspond to the endpoints for resources, such as [workbooks](#workbooks), [users](#users), [views](#views), and [data sources](#data-sources). The model classes (for example, the [WorkbookItem class](#workbookitem-class) have attributes that represent the fields (`name`, `id`, `owner_id`) that are in the REST API request and response packages, or payloads. + +|:--- | +| **Note:** Some methods and features provided in the REST API might not be currently available in the TSC library. In addition, the same limitations apply to the TSC library that apply to the REST API with respect to resources on Tableau Server and Tableau Online. For more information, see the [Tableau Server REST API Reference](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#API_Reference%3FTocPath%3DAPI%2520Reference%7C_____0){:target="_blank"}.| + + * TOC {:toc } @@ -14,6 +25,10 @@ layout: docs +
    +
    + + ## Authentication You can use the TSC library to manage authentication, so you can sign in and sign out of Tableau Server and Tableau Online. The authentication resources for Tableau Server are defined in the `TableauAuth` class and they correspond to the authentication attributes you can access using the Tableau Server REST API. @@ -269,7 +284,9 @@ Name | Description **Exceptions** -`Datasource ID undefined` : Raises an exception if a valid `datasource_id` is not provided. +Error | Description + :--- | : --- +`Datasource ID undefined` | Raises an exception if a valid `datasource_id` is not provided. REST API: [Delete Datasource](http://onlinehelp.tableau.com/v0.0/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Delete_Datasource%3FTocPath%3DAPI%2520Reference%7C_____19){:target="_blank"} @@ -549,7 +566,9 @@ REST API: [Update Datasource](http://onlinehelp.tableau.com/current/api/rest_api **Parameters** -`datasource_item` : The `datasource_item` specifies the data source to update. +Name | Description + :--- | : --- +`datasource_item` | The `datasource_item` specifies the data source to update. @@ -1174,6 +1193,8 @@ Name | Description **Exceptions** +Error | Description + :--- | : --- `Project item missing ID.` | Raises an exception if the project item does not have an ID. The project ID is sent to the server as part of the URI. @@ -1229,6 +1250,9 @@ Name | Description :--- | :--- `project_id` | The ID of the project to delete. + + + **Exceptions** Error | Description @@ -1653,6 +1677,8 @@ Name | Description **Exceptions** +Error | Description + :--- | : --- `Site ID undefined.` | Raises an error if an id is not specified. @@ -1789,10 +1815,11 @@ REST API: [Delete Site](https://onlinehelp.tableau.com/current/api/rest_api/en-u **Parameters** - +Name | Description + :--- | : --- `site_id` | The id of the site that you want to delete. - + **Exceptions** @@ -1800,6 +1827,8 @@ Error | Description :--- | :--- `Site ID Undefined.` | The site id must be present and must match the id of the site you are deleting. + + **Example** ```py @@ -1939,7 +1968,9 @@ REST API: [Add User to Site](http://onlinehelp.tableau.com/current/api/rest_api/ **Parameters** -`user_item` : You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. +Name | Description + :--- | : --- +`user_item` | You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. **Returns** @@ -1980,7 +2011,9 @@ REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/ **Parameters** -``req_option` : (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. +Name | Description + :--- | : --- +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific user, you could specify the name of the user or the user's id. **Returns** @@ -2018,12 +2051,16 @@ REST API: [Query User On Site](http://onlinehelp.tableau.com/current/api/rest_ap **Parameters** -`user_id` : The `user_id` specifies the user to query. +Name | Description + :--- | : --- +`user_id` | The `user_id` specifies the user to query. **Exceptions** -`User ID undefined.` : Raises an exception if a valid `user_id` is not provided. +Error | Description + :--- | : --- +`User ID undefined.` | Raises an exception if a valid `user_id` is not provided. **Returns** @@ -2072,14 +2109,18 @@ REST API: [Query Datasource Connections](http://onlinehelp.tableau.com/current/ **Parameters** -`user_item` : The `user_item` specifies the user to populate with workbook information. +Name | Description + :--- | : --- +`user_item` | The `user_item` specifies the user to populate with workbook information. **Exceptions** -`User item missing ID.` : Raises an errror if the `user_item` is unspecified. +Error | Description + :--- | : --- +`User item missing ID.` | Raises an errror if the `user_item` is unspecified. **Returns** @@ -2126,12 +2167,16 @@ REST API: [Remove User from Site](http://onlinehelp.tableau.com/current/api/rest **Parameters** -`user_id` : The identifier (`id`) for the the user that you want to remove from the server. +Name | Description + :--- | : --- +`user_id` | The identifier (`id`) for the the user that you want to remove from the server. **Exceptions** -`User ID undefined` : Raises an exception if a valid `user_id` is not provided. +Error | Description + :--- | : --- +`User ID undefined` | Raises an exception if a valid `user_id` is not provided. **Example** @@ -2169,15 +2214,18 @@ REST API: [Update User](http://onlinehelp.tableau.com/current/api/rest_api/en-us **Parameters** -`user_item` : The `user_item` specifies the user to update. - -`password` : (Optional) The new password for the user. +Name | Description + :--- | : --- +`user_item` | The `user_item` specifies the user to update. +`password` | (Optional) The new password for the user. **Exceptions** -`User item missing ID.` : Raises an errror if the `user_item` is unspecified. +Error | Description + :--- | : --- +`User item missing ID.` | Raises an errror if the `user_item` is unspecified. **Returns** @@ -2326,6 +2374,7 @@ REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/r Name | Description :--- | :--- `view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. + **Exceptions** @@ -2493,7 +2542,9 @@ Name | Description **Exceptions** -`Workbook ID undefined` : Raises an exception if a `workbook_id` is not provided. +Error | Description + :--- | : --- +`Workbook ID undefined` | Raises an exception if a `workbook_id` is not provided. **Returns** @@ -2656,6 +2707,9 @@ Name | Description :--- | :--- `workbook_id` | The ID of the workbook to delete. + + + **Exceptions** Error | Description @@ -2870,6 +2924,8 @@ Name | Description :--- | :--- `view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. + + **Exceptions** Error | Description From bb63aed99066bc806546a58976ec4e8b9f3fb6d2 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Fri, 14 Apr 2017 12:51:04 -0700 Subject: [PATCH 12/17] update to the left nav for new classes --- docs/_includes/docs_menu.html | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/_includes/docs_menu.html b/docs/_includes/docs_menu.html index 222b86e6b..737b2c68d 100644 --- a/docs/_includes/docs_menu.html +++ b/docs/_includes/docs_menu.html @@ -33,18 +33,27 @@
  • Data sources
    • +
  • + Filters +
  • Groups
  • Projects
    • +
  • + Requests +
  • Server
  • Sites
    • +
  • + Sort +
  • Users
    • From a1a5c12d9b179fae9fa79ccbb6cd6b5843d3de10 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Tue, 18 Apr 2017 13:06:30 -0700 Subject: [PATCH 13/17] Added sites.get_by_name; added quotes to sever.version number example --- docs/docs/api-ref.md | 95 +++++++++++++++++++++++++++++++++----------- 1 file changed, 71 insertions(+), 24 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index c41bf4d98..325204bf5 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -3,10 +3,10 @@ title: API reference layout: docs --- - + +
    @@ -39,7 +39,7 @@ You can use the TSC library to manage authentication, so you can sign in and sig ### TableauAuth class ```py -TableauAuth(username, password, site=None, site_id='', user_id_to_impersonate=None) +TableauAuth(username, password, site_id='', user_id_to_impersonate=None) ``` The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method. @@ -48,9 +48,8 @@ The `TableauAuth` class contains the attributes for the authentication resources Name | Description :--- | :--- `username` | The name of the user whose credentials will be used to sign in. -`password` | The password of the user. -`site` | (Deprecated) Use `site_id` instead. -`site_id` | This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string **" "**. For Tableau Online, you must provide a value for the `site_id`. +`password` | The password of the user. +`site_id` | This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string **' '**. For Tableau Online, you must provide a value for the `site_id`. `user_id_to_impersonate` | Specifies the id (not the name) of the user to sign in as. Source file: models/tableau_auth.py @@ -1400,7 +1399,7 @@ The `Server` class contains the attributes that represent the server on Tableau Attribute | Description :--- | :--- `server_address` | Specifies the address of the Tableau Server or Tableau Online (for example, `http://MY-SERVER/`). -`version` | Specifies the version of the REST API to use (for example, `2.5`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to 2.3, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_versions.htm){:target="_blank"} +`version` | Specifies the version of the REST API to use (for example, `'2.5'`). When you use the TSC library to call methods that access Tableau Server, the `version` is passed to the endpoint as part of the URI (`https://MY-SERVER/api/2.5/`). Each release of Tableau Server supports specific versions of the REST API. New versions of the REST API are released with Tableau Server. By default, the value of `version` is set to `'2.3'`, which corresponds to Tableau Server 10.0. You can view or set this value. You might need to set this to a different value, for example, if you want to access features that are supported by the server and a later version of the REST API. For more information, see [REST API Versions](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_versions.htm){:target="_blank"} @@ -1414,7 +1413,7 @@ server = TSC.Server('http://MY-SERVER') # change the REST API version to 2.5 -server.version = 2.5 +server.version = '2.5' ``` @@ -1656,6 +1655,48 @@ new_site = server.sites.create(new_site)

    +#### sites.get + +```py +sites.get() +``` + +Queries all the sites on the server. + + +REST API: [Query Sites](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Sites%3FTocPath%3DAPI%2520Reference%7C_____58){:target="_blank"} + + +**Parameters** + + None. + +**Returns** + +Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these values to iterate through the results. + + +**Example** + +```py +# import tableauserverclient as TSC +# server = TSC.Server('http://MY-SERVER') +# sign in, etc. + + # query the sites + all_sites, pagination_item = server.sites.get() + + # print all the site names and ids + for site in TSC.Pager(server.sites): + print(site.id, site.name, site.content_url, site.state) + + +``` + +
    +
    + + #### sites.get_by_id @@ -1703,40 +1744,45 @@ Returns the `SiteItem`.

    -#### sites.get +#### sites.get_by_name ```py -sites.get() +sites.get_by_name(site_name) ``` -Queries all the sites on the server. +Queries the site with the specifed name. -REST API: [Query Sites](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Sites%3FTocPath%3DAPI%2520Reference%7C_____58){:target="_blank"} +REST API: [Query Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Site){:target="_blank"} +**Parameters** -**Parameters** +Name | Description +:--- | :--- +`site_name` | The name of the site you want to query. + + +**Exceptions** + +Error | Description + :--- | : --- +`Site Name undefined.` | Raises an error if an name is not specified. - None. **Returns** - -Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these values to iterate through the results. +Returns the `SiteItem`. + -**Example** +**Example** ```py + # import tableauserverclient as TSC # server = TSC.Server('http://MY-SERVER') # sign in, etc. - # query the sites - all_sites, pagination_item = server.sites.get() - - # print all the site names and ids - for site in TSC.Pager(server.sites): - print(site.id, site.name, site.content_url, site.state) + a_site = server.sites.get_by_name('MY_SITE') ``` @@ -1745,6 +1791,7 @@ Returns a list of all `SiteItem` objects and a `PaginationItem`. Use these value
    + #### sites.update ```py From 457760733fdd90c1345163543d12bf865ea045cd Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Thu, 20 Apr 2017 13:08:41 -0700 Subject: [PATCH 14/17] updates from tech review; added no_extract to downloads (workbook, data sources) --- docs/docs/api-ref.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 325204bf5..2f5d635e4 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -5,7 +5,7 @@ layout: docs
    Important: More coming soon! This section is under active construction and might not reflect all the available functionality of the TSC library. - +
    @@ -15,15 +15,12 @@ The Tableau Server Client (TSC) is a Python library for the Tableau Server REST The TSC API reference is organized by resource. The TSC library is modeled after the REST API. The methods, for example, `workbooks.get()`, correspond to the endpoints for resources, such as [workbooks](#workbooks), [users](#users), [views](#views), and [data sources](#data-sources). The model classes (for example, the [WorkbookItem class](#workbookitem-class) have attributes that represent the fields (`name`, `id`, `owner_id`) that are in the REST API request and response packages, or payloads. |:--- | -| **Note:** Some methods and features provided in the REST API might not be currently available in the TSC library. In addition, the same limitations apply to the TSC library that apply to the REST API with respect to resources on Tableau Server and Tableau Online. For more information, see the [Tableau Server REST API Reference](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#API_Reference%3FTocPath%3DAPI%2520Reference%7C_____0){:target="_blank"}.| +| **Note:** Some methods and features provided in the REST API might not be currently available in the TSC library (and in some cases, the opposite is true). In addition, the same limitations apply to the TSC library that apply to the REST API with respect to resources on Tableau Server and Tableau Online. For more information, see the [Tableau Server REST API Reference](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#API_Reference%3FTocPath%3DAPI%2520Reference%7C_____0){:target="_blank"}.| * TOC {:toc } - - -

    @@ -41,7 +38,10 @@ You can use the TSC library to manage authentication, so you can sign in and sig ```py TableauAuth(username, password, site_id='', user_id_to_impersonate=None) ``` -The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method. +The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method. + + + **Note:** In the future, there might be support for additional forms of authorization and authentication (for example, OAuth). **Attributes** @@ -49,7 +49,7 @@ Name | Description :--- | :--- `username` | The name of the user whose credentials will be used to sign in. `password` | The password of the user. -`site_id` | This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string **' '**. For Tableau Online, you must provide a value for the `site_id`. +`site_id` | This corresponds to the `contentUrl` attribute in the Tableau REST API. The `site_id` is the portion of the URL that follows the `/site/` in the URL. For example, "MarketingTeam" is the `site_id` in the following URL *MyServer*/#/site/**MarketingTeam**/projects. To specify the default site on Tableau Server, you can use an empty string `''` (single quotes, no space). For Tableau Online, you must provide a value for the `site_id`. `user_id_to_impersonate` | Specifies the id (not the name) of the user to sign in as. Source file: models/tableau_auth.py @@ -297,7 +297,7 @@ REST API: [Delete Datasource](http://onlinehelp.tableau.com/v0.0/api/rest_api/en #### datasources.download ```py -datasources.download(datasource_id, filepath=None) +datasources.download(datasource_id, filepath=None, no_extract=False) ``` Downloads the specified data source in `.tdsx` format. @@ -310,7 +310,7 @@ Name | Description :--- | :--- `datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. `filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. - +`no_extract` | (Optional) Specifies whether to download the file without the extract. When the data source has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. The default is to include the extract, if present (`no_extract=False`). **Exceptions** @@ -2783,7 +2783,7 @@ Error | Description #### workbooks.download ```py -workbooks.download(workbook_id, filepath=None) +workbooks.download(workbook_id, filepath=None, no_extract=False) ``` Downloads a workbook to the specified directory (optional). @@ -2798,6 +2798,8 @@ Name | Description :--- | :--- `workbook_id` | The ID for the the `WorkbookItem` that you want to download from the server. `filepath` | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default is `Filepath=None`. +`no_extract` | (Optional) Specifies whether to download the file without the extract. When the workbook has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading workbooks that have large extracts. The default is to include the extract, if present (`no_extract=False`). + **Exceptions** From 3f8df49d567b94b617ac514530a9e2cb441694bf Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Thu, 20 Apr 2017 16:31:41 -0700 Subject: [PATCH 15/17] Added workbooks.update_connections (the cause of merge conflict); fixed some connectionitem info --- docs/_includes/docs_menu.html | 2 +- docs/docs/api-ref.md | 50 ++++++++++++++++++++++++++++++++++- 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/_includes/docs_menu.html b/docs/_includes/docs_menu.html index 737b2c68d..9b7066f12 100644 --- a/docs/_includes/docs_menu.html +++ b/docs/_includes/docs_menu.html @@ -28,7 +28,7 @@ Authentication
  • - Connection + Connections
  • Data sources diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 2f5d635e4..dcb906355 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -164,6 +164,10 @@ The connections for Tableau Server data sources and workbooks are represented by ConnectionItem() ``` +The `ConnectionItem` class corresponds to workbook and data source connections. + +In the Tableau Server REST API, there are separate endopoints to query and update workbook and data source connections. + **Attributes** Name | Description @@ -172,7 +176,11 @@ Name | Description `datasource_name` | The name of the data source. `id` | The identifer of the connection. `connection_type` | The type of connection. - +`username` | The username for the connection. +`password` | The password used for the connection. +`embed_password` | (Boolean) Determines whether to embed the passowrd (`True`) for the workbook or data source connection or not (`False`). +`server_address` | The server address for the connection. +`server_port` | The port used by the server. Source file: models/connection_item.py @@ -3006,6 +3014,46 @@ None. The preview image is added to the view. server.workbooks.populate_preview_image(workbook) +``` + +#### workbooks.update_connection + +```py +workbooks.update_conn(workbook_item, connection_item) +``` + +Updates a workbook connection information (server address, server port, user name, and password). + +The workbook connections must be populated before the strings can be updated. See [workbooks.populate_connections](#workbooks.populate_connections) + +REST API: [Update Workbook Connection](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Update_Workbook_Connection%3FTocPath%3DAPI%2520Reference%7C_____88){:target="_blank"} + +**Parameters** + +Name | Description +:--- | :--- +`workbook_item` | The `workbook_item` specifies the workbook to populate with data connection information. +`connection_item` | The `connection_item` that has the information you want to update. + + + +**Returns** + +None. The connection information is updated with the information in the `ConnectionItem`. + + + + +**Example** + +```py + +# update connection item user name and password +workbook.connections[0].username = 'USERNAME' +workbook.connections[0].password = 'PASSWORD' + +# call the update method +server.workbooks.update_conn(workbook, workbook.connections[0]) ```
    From 70fa4a0e857f7e9f0008830f06f4872cb081646f Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Fri, 21 Apr 2017 13:22:28 -0700 Subject: [PATCH 16/17] tech review fixes, removed groups.get_by_id from examples, fixed datasource update example --- docs/docs/api-ref.md | 81 +++++++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 38 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index dcb906355..c35897bdd 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -28,7 +28,7 @@ The TSC API reference is organized by resource. The TSC library is modeled after ## Authentication -You can use the TSC library to manage authentication, so you can sign in and sign out of Tableau Server and Tableau Online. The authentication resources for Tableau Server are defined in the `TableauAuth` class and they correspond to the authentication attributes you can access using the Tableau Server REST API. +You can use the TSC library to sign in and sign out of Tableau Server and Tableau Online. The credentials for signing in are defined in the `TableauAuth` class and they correspond to the attributes you specify when you sign in using the Tableau Server REST API.

    @@ -38,7 +38,7 @@ You can use the TSC library to manage authentication, so you can sign in and sig ```py TableauAuth(username, password, site_id='', user_id_to_impersonate=None) ``` -The `TableauAuth` class contains the attributes for the authentication resources. The `TableauAuth` class defines the information you can set in a request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method. +The `TableauAuth` class defines the information you can set in a sign-in request. The class members correspond to the attributes of a server request or response payload. To use this class, create a new instance, supplying user name, password, and site information if necessary, and pass the request object to the [Auth.sign_in](#auth.sign-in) method. **Note:** In the future, there might be support for additional forms of authorization and authentication (for example, OAuth). @@ -63,7 +63,7 @@ import tableauserverclient as TSC tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL') # create a server instance -# pass the "tableau_auth" request object to server.auth.sign_in() +# pass the "tableau_auth" object to the server.auth.sign_in() method ```
    @@ -87,7 +87,7 @@ auth.sign_in(auth_req) Signs you in to Tableau Server. -The method signs into Tableau Server or Tableau Online and manages the authentication token. You call this method from the server object you create. For information about the server object, see [Server](#server). The authentication token keeps you signed in for 240 minutes, or until you call the `auth.sign_out` method. Before you use this method, you first need to create the sign-in request (`auth_req`) by creating an instance of the `TableauAuth`. To call this method, create a server object for your server. For more information, see [Sign in and Out](sign-in-out). +The method signs into Tableau Server or Tableau Online and manages the authentication token. You call this method from the server object you create. For information about the server object, see [Server](#server). The authentication token keeps you signed in for 240 minutes, or until you call the `auth.sign_out` method. Before you use this method, you first need to create the sign-in request (`auth_req`) object by creating an instance of the `TableauAuth`. To call this method, create a server object for your server. For more information, see [Sign in and Out](sign-in-out). REST API: [Sign In](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_In%3FTocPath%3DAPI%2520Reference%7C_____77){:target="_blank"} @@ -101,13 +101,13 @@ REST API: [Sign In](http://onlinehelp.tableau.com/current/api/rest_api/en-us/hel ```py import tableauserverclient as TSC -# create a auth request +# create an auth object tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') # create an instance for your server server = TSC.Server('http://SERVER_URL') -# call the sign-in method with the request +# call the sign-in method with the auth object server.auth.sign_in(tableau_auth) ``` @@ -128,7 +128,7 @@ auth.sign_out() ``` Signs you out of the current session. -The method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out). +The `sign_out()` method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out). REST API: [Sign Out](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_Out%3FTocPath%3DAPI%2520Reference%7C_____78){:target="_blank"} @@ -156,7 +156,7 @@ server.auth.sign_out() ## Connections -The connections for Tableau Server data sources and workbooks are represented by a `ConnectionItem` class. You can call data source and view methods to query or update the connection information. The `ConnectionCredentials` class represents the connection information you can update. +The connections for Tableau Server data sources and workbooks are represented by a `ConnectionItem` class. You can call data source and workbook methods to query or update the connection information. The `ConnectionCredentials` class represents the connection information you can update. ### ConnectionItem class @@ -178,9 +178,9 @@ Name | Description `connection_type` | The type of connection. `username` | The username for the connection. `password` | The password used for the connection. -`embed_password` | (Boolean) Determines whether to embed the passowrd (`True`) for the workbook or data source connection or not (`False`). +`embed_password` | (Boolean) Determines whether to embed the password (`True`) for the workbook or data source connection or not (`False`). `server_address` | The server address for the connection. -`server_port` | The port used by the server. +`server_port` | The port used for the connection. Source file: models/connection_item.py @@ -196,9 +196,9 @@ ConnectionCredentials(name, password, embed=True, oauth=False) ``` -The `ConnectionCredentials` class corresponds to workbook and data source connections. +The `ConnectionCredentials` class is used for workbook and data source publish requests. + -In the Tableau Server REST API, there are separate endopoints to query and update workbook and data source connections. **Attributes** @@ -220,7 +220,7 @@ Source file: models/connection_credentials.py ## Data sources Using the TSC library, you can get all the data sources on a site, or get the data sources for a specific project. -The data source resources for Tableau Server are defined in the `DatasourceItem` class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, and connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the `DatasourceItem` class. +The data source resources for Tableau Server are defined in the `DatasourceItem` class. The class corresponds to the data source resources you can access using the Tableau Server REST API. For example, you can gather information about the name of the data source, its type, its connections, and the project it is associated with. The data source methods are based upon the endpoints for data sources in the REST API and operate on the `DatasourceItem` class.
    @@ -318,7 +318,7 @@ Name | Description :--- | :--- `datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. `filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. -`no_extract` | (Optional) Specifies whether to download the file without the extract. When the data source has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. The default is to include the extract, if present (`no_extract=False`). +`no_extract` | (Optional) Specifies whether to download the file without the extract. When the data source has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. The default is to include the extract, if present (`no_extract=False`). Available starting with Tableau Server REST API version 2.5. **Exceptions** @@ -546,7 +546,8 @@ The `DatasourceItem` for the data source that was added or appened to. ... project_id = '3a8b6148-493c-11e6-a621-6f3499394a39' - file_path = 'C:\\temp\\WorldIndicators.tde' + file_path = r'C:\temp\WorldIndicators.tde' + # Use the project id to create new datsource_item new_datasource = TSC.DatasourceItem(project_id) @@ -591,19 +592,21 @@ An updated `DatasourceItem`. **Example** -```py -# from server-client-python/test/test_datasource.py +```py +# import tableauserverclient as TSC +# server = TSC.Server('http://SERVERURL') +# sign in ... + +# get the data source item to update + datasource = server.datasources.get_by_id('1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b') + +# do some updating + datasource.name = 'New Name' - ... +# call the update method with the data source item + updated_datasource = server.datasources.update(datasource) - single_datasource = TSC.DatasourceItem('test', '1d0304cd-3796-429f-b815-7258370b9b74') - # need to specify the ID - this is a workaround. - single_datasource._id = '9dbd2263-16b5-46e1-9c43-a76bb8ab65fb' - single_datasource._tags = ['a', 'b', 'c'] - single_datasource._project_name = 'Tester' - updated_datasource = self.server.datasources.update(single_datasource) - ... ``` @@ -667,7 +670,7 @@ The group resources for Tableau Server are defined in the `GroupItem` class. The GroupItem(name) ``` -The `GroupItem` class contains the members or attributes for the view resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. +The `GroupItem` class contains the attributes for the group resources on Tableau Server. The `GroupItem` class defines the information you can request or query from Tableau Server. The class members correspond to the attributes of a server request or response payload. Source file: models/group_item.py @@ -686,6 +689,8 @@ Name | Description ```py newgroup = TSC.GroupItem('My Group') + + # call groups.create() with new group ``` @@ -735,17 +740,17 @@ None. ```py # Adding a user to a group -# Using the second group on the site, aleady have all_groups +# +# get the group item + all_groups, pagination_item = server.groups.get() + mygroup = all_groups[1] + # The id for Ian is '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba' -# add Ian to the second group - server.groups.add_user(all_groups[1], '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba') +# add Ian to the group + server.groups.add_user(mygroup, '59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba') -# populate the GroupItem with the users - pagination_item = server.groups.populate_users(all_groups[1]) - for user in all_groups[1].users : - print(user.name) ``` @@ -883,7 +888,7 @@ Returns a list of `GroupItem` objects and a `PaginationItem` object. Use these # get the groups on the server all_groups, pagination_item = server.groups.get() - # print the names of the groups + # print the names of the first 100 groups for group in all_groups : print(group.name, group.id) ```` @@ -932,14 +937,14 @@ None. A list of `UserItem` objects are added to the group (`group_item.users`). ... # get the group - mygroup = server.groups.get_by_id('1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d') - + all_groups, pagination_item = server.groups.get() + mygroup = all_groups[1] # get the user information pagination_item = server.groups.populate_users(mygroup) -# print the information about the first connection item +# print the names of the users for user in mygroup.users : print(user.name) @@ -2806,7 +2811,7 @@ Name | Description :--- | :--- `workbook_id` | The ID for the the `WorkbookItem` that you want to download from the server. `filepath` | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default is `Filepath=None`. -`no_extract` | (Optional) Specifies whether to download the file without the extract. When the workbook has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading workbooks that have large extracts. The default is to include the extract, if present (`no_extract=False`). +`no_extract` | (Optional) Specifies whether to download the file without the extract. When the workbook has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading workbooks that have large extracts. The default is to include the extract, if present (`no_extract=False`). Available starting with Tableau Server REST API version 2.5. From 248a172c47d596160b96f42b605856ae35909c96 Mon Sep 17 00:00:00 2001 From: d45 <3d.hagen@gmail.com> Date: Fri, 21 Apr 2017 15:34:37 -0700 Subject: [PATCH 17/17] Ran spellcheck, fixed misc errors --- docs/docs/api-ref.md | 90 +++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 42 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index c35897bdd..76b09eae6 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -128,7 +128,7 @@ auth.sign_out() ``` Signs you out of the current session. -The `sign_out()` method takes care of invalidating the authentiction token. For more information, see [Sign in and Out](sign-in-out). +The `sign_out()` method takes care of invalidating the authentication token. For more information, see [Sign in and Out](sign-in-out). REST API: [Sign Out](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Sign_Out%3FTocPath%3DAPI%2520Reference%7C_____78){:target="_blank"} @@ -166,7 +166,7 @@ ConnectionItem() The `ConnectionItem` class corresponds to workbook and data source connections. -In the Tableau Server REST API, there are separate endopoints to query and update workbook and data source connections. +In the Tableau Server REST API, there are separate endpoints to query and update workbook and data source connections. **Attributes** @@ -174,7 +174,7 @@ Name | Description :--- | : --- `datasource_id` | The identifier of the data source. `datasource_name` | The name of the data source. -`id` | The identifer of the connection. +`id` | The identifier of the connection. `connection_type` | The type of connection. `username` | The username for the connection. `password` | The password used for the connection. @@ -242,7 +242,7 @@ Name | Description `datasource_type` | The type of data source, for example, `sqlserver` or `excel-direct`. `id` | The identifier for the data source. You need this value to query a specific data source or to delete a data source with the `get_by_id` and `delete` methods. `name` | The name of the data source. If not specified, the name of the published data source file is used. -`project_id` | The identifer of the project associated with the data source. When you must provide this identifier when create an instance of a `DatasourceItem` +`project_id` | The identifier of the project associated with the data source. When you must provide this identifier when create an instance of a `DatasourceItem` `project_name` | The name of the project associated with the data source. `tags` | The tags that have been added to the data source. `updated_at` | The date and time when the data source was last updated. @@ -286,7 +286,7 @@ Removes the specified data source from Tableau Server. Name | Description :--- | :--- -`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to delete from the server. +`datasource_id` | The identifier (`id`) for the `DatasourceItem` that you want to delete from the server. **Exceptions** @@ -316,7 +316,7 @@ REST API: [Download Datasource](http://onlinehelp.tableau.com/current/api/rest_a Name | Description :--- | :--- -`datasource_id` | The identifier (`id`) for the the `DatasourceItem` that you want to download from the server. +`datasource_id` | The identifier (`id`) for the `DatasourceItem` that you want to download from the server. `filepath` | (Optional) Downloads the file to the location you specify. If no location is specified (the default is `Filepath=None`), the file is downloaded to the current working directory. `no_extract` | (Optional) Specifies whether to download the file without the extract. When the data source has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading data sources that have large extracts. The default is to include the extract, if present (`no_extract=False`). Available starting with Tableau Server REST API version 2.5. @@ -462,7 +462,7 @@ Name | Description Error | Description :--- | :--- -`Datasource item missing ID. Datasource must be retrieved from server first.` | Raises an errror if the datasource_item is unspecified. +`Datasource item missing ID. Datasource must be retrieved from server first.` | Raises an error if the datasource_item is unspecified. **Returns** @@ -533,7 +533,7 @@ Error | Description **Returns** -The `DatasourceItem` for the data source that was added or appened to. +The `DatasourceItem` for the data source that was added or appended to. **Example** @@ -552,7 +552,7 @@ The `DatasourceItem` for the data source that was added or appened to. # Use the project id to create new datsource_item new_datasource = TSC.DatasourceItem(project_id) - # publish data source (specifed in file_path) + # publish data source (specified in file_path) new_datasource = server.datasources.publish( new_datasource, file_path, 'CreateNew') @@ -582,7 +582,9 @@ Name | Description **Exceptions** -`Datasource item missing ID. Datasource must be retrieved from server first.` : Raises an errror if the datasource_item is unspecified. Use the `Datasources.get()` method to retrieve that identifies for the data sources on the server. +Error | Description + :--- | : --- +`Datasource item missing ID. Datasource must be retrieved from server first.` | Raises an error if the datasource_item is unspecified. Use the `Datasources.get()` method to retrieve that identifies for the data sources on the server. **Returns** @@ -635,7 +637,7 @@ For more information, see [Filter and Sort](filter-sort). Filter(field, operator, value) ``` -The `Filter` class corresponds to the *filter expresions* in the Tableau REST API. +The `Filter` class corresponds to the *filter expressions* in the Tableau REST API. @@ -823,7 +825,7 @@ REST API: [Delete Group](http://onlinehelp.tableau.com/current/api/rest_api/en-u Name | Description :--- | :--- -`group_id` | The identifier (`id`) for the the group that you want to remove from the server. +`group_id` | The identifier (`id`) for the group that you want to remove from the server. **Exceptions** @@ -867,7 +869,7 @@ REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/ Name | Description :--- | :--- -`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific groups, you could specify the name of the group or the group id. +`req_option` | (Optional) You can pass the method a request object that contains additional parameters to filter the request. For example, if you were searching for a specific group, you could specify the name of the group or the group id. **Returns** @@ -919,7 +921,7 @@ Name | Description **Exceptions** -`Group item missing ID. Group must be retrieved from server first.` : Raises an errror if the `group_item` is unspecified. +`Group item missing ID. Group must be retrieved from server first.` : Raises an error if the `group_item` is unspecified. **Returns** @@ -983,7 +985,7 @@ Name | Description Error | Description :--- | :--- -`Group must be populated with users first.` | Raises an errror if the `group_item` is unpopulated. +`Group must be populated with users first.` | Raises an error if the `group_item` is unpopulated. **Returns** @@ -1214,7 +1216,9 @@ Error | Description Returns the updated project information. -See [ProjectItem class]() +See [ProjectItem class](#projectitem-class) + +**Example** ```py # import tableauserverclient as TSC @@ -1222,16 +1226,17 @@ See [ProjectItem class]() # sign in, etc ... - + # get list of projects all_project_items, pagination_item = server.projects.get() - print([prj.name for prj in all_project_items]) + # update project item #7 with new name, etc. - all_projects[7].name ='New name' - all_projects[7].description = 'New description' + my_project = all_projects[7] + my_project.name ='New name' + my_project.description = 'New description' # call method to update project - updated_proj = server.projects.update(all_projects[7]) + updated_project = server.projects.update(my_project) @@ -1296,6 +1301,7 @@ You can use the `Sort` and `RequestOptions` classes to filter and sort the follo - Users - Datasources +- Groups - Workbooks - Views @@ -1329,7 +1335,7 @@ Name | Description #### RequestOptions.Field class -The `RequestOptions.Field` class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, see [Fitering and Sorting](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_filtering_and_sorting.htm%3FTocPath%3DConcepts%7C_____7){:target="_blank"} in the Tableau REST API. +The `RequestOptions.Field` class corresponds to the fields used in filter expressions in the Tableau REST API. For more information, see [Filtering and Sorting](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_filtering_and_sorting.htm%3FTocPath%3DConcepts%7C_____7){:target="_blank"} in the Tableau REST API. **Attributes** @@ -1494,7 +1500,7 @@ Resource | Description ```py ServerInfoItem(product_version, build_number, rest_api_version) ``` -The `ServerInfoItem` class contains the builid and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class. +The `ServerInfoItem` class contains the build and version information for Tableau Server. The server information is accessed with the `server_info.get()` method, which returns an instance of the `ServerInfo` class. **Attributes** @@ -1587,7 +1593,7 @@ Attribute | Description `content_url` | The path to the site. `admin_mode` | (Optional) For Tableau Server only. Specify `ContentAndUsers` to allow site administrators to use the server interface and **tabcmd** commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify `ContentOnly` to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.) `user_quota`| (Optional) Specifies the maximum number of users for the site. If you do not specify this value, the limit depends on the type of licensing configured for the server. For user-based license, the maximum number of users is set by the license. For core-based licensing, there is no limit to the number of users. If you specify a maximum value, only licensed users are counted and server administrators are excluded. -`storage_quota` | (Optional) Specifes the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again. +`storage_quota` | (Optional) Specifies the maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again. `disable_subscriptions` | (Optional) Specify `true` to prevent users from being able to subscribe to workbooks on the specified site. The default is `false`. `subscribe_others_enabled` | (Optional) Specify `false` to prevent server administrators, site administrators, and project or content owners from being able to subscribe other users to workbooks on the specified site. The default is `true`. `revision_history_enabled` | (Optional) Specify `true` to enable revision history for content resources (workbooks and datasources). The default is `false`. @@ -1640,7 +1646,7 @@ REST API: [Create Site](https://onlinehelp.tableau.com/current/api/rest_api/en-u Name | Description :--- | :--- -`site_item` | The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass the the `create` method. +`site_item` | The settings for the site that you want to create. You need to create an instance of `SiteItem` and pass the `create` method. **Returns** @@ -1763,7 +1769,7 @@ Returns the `SiteItem`. sites.get_by_name(site_name) ``` -Queries the site with the specifed name. +Queries the site with the specified name. REST API: [Query Site](https://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Query_Site){:target="_blank"} @@ -1931,13 +1937,13 @@ sort(field, direction) Name | Description :--- | :--- `field` | Sets the field to sort on. The fields are defined in the `RequestOption` class. -`direction` | The direction to sort, either asscending (`Asc`) or descending (`Desc`). The options are defined in the `RequestOptions.Direction` class. +`direction` | The direction to sort, either ascending (`Asc`) or descending (`Desc`). The options are defined in the `RequestOptions.Direction` class. **Example** ```py -# create an new instance of a request option object +# create a new instance of a request option object req_option = TSC.RequestOptions() # add the sort expression, sorting by name and direction @@ -1975,7 +1981,7 @@ The `UserItem` class contains the members or attributes for the view resources o Name | Description :--- | :--- -`auth_setting` | (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for tis attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. +`auth_setting` | (Optional) This attribute is only for Tableau Online. The new authentication type for the user. You can assign the following values for tis attribute: `SAML` (the user signs in using SAML) or `ServerDefault` (the user signs in using the authentication method that's set for the server). These values appear in the **Authentication** tab on the **Settings** page in Tableau Online -- the `SAML` attribute value corresponds to **Single sign-on**, and the `ServerDefault` value corresponds to **TableauID**. `domain_name` | The name of the site. `external_auth_user_id` | Represents ID stored in Tableau's single sign-on (SSO) system. The `externalAuthUserId` value is returned for Tableau Online. For other server configurations, this field contains null. `id` | The id of the user on the site. @@ -2067,7 +2073,7 @@ Returns information about the users on the specified site. To get information about the workbooks a user owns or has view permission for, you must first populate the `UserItem` with workbook information using the [populate_workbooks(*user_item*)](#populate-workbooks-user) method. -REST API: [Get Uers on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} +REST API: [Get Users on Site](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_ref.htm#Get_Users_on_Site%3FTocPath%3DAPI%2520Reference%7C_____41){:target="_blank"} **Parameters** @@ -2078,7 +2084,7 @@ Name | Description **Returns** -Returns a list of `UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. +Returns a list of `UserItem` objects and a `PaginationItem` object. Use these values to iterate through the results. **Example** @@ -2180,7 +2186,7 @@ Name | Description Error | Description :--- | : --- -`User item missing ID.` | Raises an errror if the `user_item` is unspecified. +`User item missing ID.` | Raises an error if the `user_item` is unspecified. **Returns** @@ -2229,7 +2235,7 @@ REST API: [Remove User from Site](http://onlinehelp.tableau.com/current/api/rest Name | Description :--- | : --- -`user_id` | The identifier (`id`) for the the user that you want to remove from the server. +`user_id` | The identifier (`id`) for the user that you want to remove from the server. **Exceptions** @@ -2285,7 +2291,7 @@ Name | Description Error | Description :--- | : --- -`User item missing ID.` | Raises an errror if the `user_item` is unspecified. +`User item missing ID.` | Raises an error if the `user_item` is unspecified. **Returns** @@ -2433,7 +2439,7 @@ REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/r Name | Description :--- | :--- -`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. +`view_item` | The view item specifies the `view.id` and `workbook.id` that identifies the preview image. **Exceptions** @@ -2636,7 +2642,7 @@ Publish a workbook to the specified site. **Note:** The REST API cannot automatically include extracts or other resources that the workbook uses. Therefore, - a .twb file that usess data from an Excel or csv file on a local computer cannot be published, + a .twb file that uses data from an Excel or csv file on a local computer cannot be published, unless you package the data and workbook in a .twbx file, or publish the data source separately. For workbooks that are larger than 64 MB, the publish method automatically takes care of chunking the file in parts for uploading. Using this method is considerably more convenient than calling the publish REST APIs directly. @@ -2649,7 +2655,7 @@ REST API: [Publish Workbook](http://onlinehelp.tableau.com/current/api/rest_api/ Name | Description :--- | :--- -`workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that inlcudes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class). +`workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that includes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class). `file_path` | The path and name of the workbook to publish. `mode` | Specifies whether you are publishing a new workbook (`CreateNew`) or overwriting an existing workbook (`Overwrite`). You cannot appending workbooks. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. `connection_credentials` | (Optional) The credentials (if required) to connect to the workbook's data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embeded or OAuth is used). @@ -2713,7 +2719,7 @@ Name | Description Error | Description :--- | :--- -`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. Use the `workbooks.get()` or `workbooks.get_by_id()` methods to retreive the workbook item from the server. +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an error if the `workbook_item` is unspecified. Use the `workbooks.get()` or `workbooks.get_by_id()` methods to retrieve the workbook item from the server. ```py @@ -2809,7 +2815,7 @@ REST API: [Download Workbook](http://onlinehelp.tableau.com/current/api/rest_api Name | Description :--- | :--- -`workbook_id` | The ID for the the `WorkbookItem` that you want to download from the server. +`workbook_id` | The ID for the `WorkbookItem` that you want to download from the server. `filepath` | (Optional) Downloads the file to the location you specify. If no location is specified, the file is downloaded to the current working directory. The default is `Filepath=None`. `no_extract` | (Optional) Specifies whether to download the file without the extract. When the workbook has an extract, if you set the parameter `no_extract=True`, the extract is not included. You can use this parameter to improve performance if you are downloading workbooks that have large extracts. The default is to include the extract, if present (`no_extract=False`). Available starting with Tableau Server REST API version 2.5. @@ -2868,7 +2874,7 @@ Name | Description Error | Description :--- | :--- -`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. You can retreive the workbook items using the `workbooks.get()` and `workbooks.get_by_id()` methods. +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an error if the `workbook_item` is unspecified. You can retrieve the workbook items using the `workbooks.get()` and `workbooks.get_by_id()` methods. **Returns** @@ -2931,7 +2937,7 @@ Name | Description Error | Description :--- | :--- -`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an errror if the `workbook_item` is unspecified. +`Workbook item missing ID. Workbook must be retrieved from server first.` | Raises an error if the `workbook_item` is unspecified. **Returns** @@ -2984,7 +2990,7 @@ REST API: [Query View Preview Image](http://onlinehelp.tableau.com/current/api/r Name | Description :--- | :--- -`view_item` | The view item specifies the the `view.id` and `workbook.id` that identifies the preview image. +`view_item` | The view item specifies the `view.id` and `workbook.id` that identifies the preview image.