Data Sources Methods
Using the data sources methods of the Tableau Server REST API you can:
- Publish, update metadata, delete, or refresh the extract of a data source of a site
- Add and delete tags of a data source
- Get a list of data sources and the details of each
- Get and update the connection information for a data source
- Get the revision history of a data source or remove specific revisions
- Download the current data source or one of its past revisions
- Incrementally update specified portions of data from a live-to-Hyper connection.
- Download an encrypted keychain for a data source that is migrating to another site.
- Upload an encrypted keychain for a data source migrated to another site.
This functionality relates to the UI elements and concepts described at: Connect to Your Data(Link opens in a new window).
The Tableau Server Client library(Link opens in a new window), a Python wrapper for the REST API, offers the following related items: Data Sources(Link opens in a new window); and Populate connections for Data Sources(Link opens in a new window).
Add Tags to Data Source
Adds one or more tags to the specified data source.
URI
PUT /api/api-version/sites/site-id/datasources/datasource-id/tags
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to add tags to. |
Request Body
<tsRequest>
<tags>
<tag label="tag" />
... additional tags ...
</tags>
</tsRequest>
Attribute Values
datasource-id | The data source to add the tag to. If the data source is already tagged with a tag that's included in the request body, those tags are ignored and the data source retains them. If the <tags> element is empty, no new tags are added to the data source. |
tag | The text of the tag. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the data source (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<tags>
<tag label="tag"/>
... additional new tags ...
... existing tags ...
</tags>
</tsResponse>
Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400075 | Error adding tags | There was a problem adding tags to the specified data source. |
403 | 403004 | Adding tags forbidden |
A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty. |
404 | 404000 | Site not found |
The site ID in the URI is not for an existing site. |
404 | 404004 | Data source not found | The data source ID in URI doesn't correspond to an existing data source. |
404 | 404009 | Data source ID mismatch | The request body contains a data source ID (which is optional) and it doesn't match the ID in the URI. |
404 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-datasource.xml
Content of add-tags-to-datasource.xml:
<tsRequest>
<tags>
<tag label="GDP" />
<tag label="Health" />
</tags>
</tsRequest>
Example response:
<tsResponse version-and-namespace-settings>
<tags>
<tag label="GDP"/>
<tag label="Health"/>
<tag label="Spending"/>
</tags>
</tsResponse>
Delete Data Source
Deletes the specified data source from a site. When a data source is deleted, its associated data connection is also deleted. Workbooks that use the data source are not deleted, but they will no longer work properly.
URI
DELETE /api/api-version/sites/site-id/datasources/datasource-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to delete. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can delete a data source for which they have Read (view) and Delete permissions (either explicitly or implicitly).
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Deletion forbidden | A non-administrator user called this method but doesn't have Read (view) and Delete permission for the data source. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source in the site. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Delete Tag from Data Source
Deletes a tag from the specified data source.
URI
DELETE /api/api-version/sites/site-id/datasources/datasource-id/tags/tag-name
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to remove the tag from. |
tag-name | The name of the tag to remove from the data source. |
Request Body
None
Permissions
Tableau Server users who are not server administrators, site administrators, or data source owners can delete a tag from a data source only if they are project leaders or if they originally added the tag.
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400077 | Error deleting tag | There was a problem deleting the tag from the specified data source. |
403 | 403004 | Deleting tags forbidden | A non-administrator user called this method but doesn't have permission to delete a tag from the specified data source. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404007 | Tag not found | The tag in the URI doesn't exist for the specified data source. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Download Data Source
Downloads a data source in .tdsx
format.
URI
GET /api/api-version/sites/site-id/datasources/datasource-id/content
GET /api/api-version/sites/site-id/datasources/datasource-id/content?includeExtract=extract-value
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to download. |
extract-value | (Optional) The extract-value is a Boolean value (False or True ). When the data source specified for download has an extract, if you add the parameter ?includeExtract=False , the extract is not included when you download the data source. You can use this parameter to improve performance if you are downloading workbooks or data sources that have large extracts. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can download a data source only if they have ExportXml permission for the data source (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:datasources:download
Response Code
200
Response Body
The data source content in .tdsx
format (Content-Type: application/octet-stream
).
The response will have the following content disposition header:
Content-Disposition: name="tableau_datasource"; filename="datasource-filename"
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403028 | Read forbidden | A non-administrator user attempted to download a data source, but the caller doesn't have Read permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > my-datasource.tdsx
The response is a file that contains the data source.
Download Data Source Encrypted Keychain
Gets an encrypted version of the embedded credentials from the data source. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.
Version: Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/datasources/datasource-luid/retrieveKeychain
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions.
|
site-luid | The LUID for the site. |
datasource-luid | The LUID of the data source to download the encrypted keychain from. |
Request Body
<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>d56023b5-8f8b-4241-aa74-8974ced85827</destinationSiteLuid> <destinationServerUrl>http://example.com</destinationServerUrl> </tsRequest>
{ "destinationSiteUrlNamespace": "site1", "destinationSiteLuid": "d56023b5-8f8b-4241-aa74-8974ced85827", "destinationServerUrl": "http://localhost" }
Request Attributes
destinationSiteUrlNamespace
|
(Required) The site name on Tableau Cloud. |
destinationSiteLuid
|
(Required) The site ID on Tableau Cloud. |
destinationServerUrl
|
(Required) The destination Tableau Cloud URL. |
cURL Request Example
curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/retrieveKeychain" --header "Content-Type: application/xml" --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86" --data "<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace><destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid><destinationServerUrl>http://example.com</destinationServerUrl></tsRequest>"
Response Code
200
Response Body
<tsResponse>
<associatedUserLuidList/>
<encryptedKeychainList>
<encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain>
</encryptedKeychainList>
</tsResponse>
{
"associatedUserLuidList": [],
"encryptedKeychainList": {
"encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y="
}
}
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
401 | 401002 | Unauthorized Access |
The authentication token provided in the request header was invalid or has expired. |
403 | 403054 | Unauthorized Access | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.
Download Data Source Revision
Downloads a specific version of a data source prior to the current one in .tdsx
format. To down load the current version of a data source use the Download Data Source method.
Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.
URI
GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to download. |
revision-number | The revision number of the data source to download. To determine what versions are available, call Get Data Source Revisions. |
Request Body
None
Permissions
Tableau Server users who are site administrators can download data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:
- A site role of ExplorerCanPublish.
- Read (view), Write (save), and Download (save as) permissions for the specified data source.
- Save (write) permissions for the project that contains the data source.
Response Code
200
Response Body
The data source content in .tdsx
format (Content-Type: application/octet-stream
).
The response will have the following content disposition header:
Content-Disposition: name="tableau_datasource"; filename="datasource-filename"
Version
Version 2.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403028 | Read forbidden | A non-administrator user attempted to download a data source, but the caller doesn't have required permissions. |
403 | 403053 | Version history not enabled | version history is not enabled for the specified site. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404024 | Data source revision not found | The revision number in the URI doesn't correspond to an existing data source revision. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Get Data Source Revisions
Returns a list of revision information (history) for the specified data source.
Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.
To get a specific version of the data source from revision history, use the Download Data Source Revision method.
URI
GET /api/api-version/sites/site-id/datasources/datasource-id/revisions
GET /api/api-version/sites/site-id/datasources/datasource-id/revisions?pageSize=page-size&pageNumber=page-number
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source to get revisions for. |
datasource-id | The ID of the data source to get revisions for. |
page-size | (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results. |
page-number | (Optional) The offset for paging. The default is 1. For more information, see Paginating Results. |
Request Body
None
Permissions
Tableau Server users who are site administrators can get data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:
- A site role of ExplorerCanPublish.
- Read (view), Write (save), and Download (save as) permissions for the specified data source.
- Save (write) permissions for the project that contains the data source.
Response Code
200
Response Body
<tsResponse>
<pagination pageNumber="pageNumber" pageSize="page-size"
totalAvailable="total-available" />
<revisions>
<revision revisionNumber="1" publishedAt="date" deleted="false">
<publisher id="publisher-id" name="publisher-name"/>
</revision>
<revision revisionNumber="2" publishedAt="date" deleted="false">
</revision>
<revision revisionNumber="3" publishedAt="date" deleted="false" current="true" sizeInBytes="size>
<publisher id="publisher-id" name="publisher-name"/>
</revision>
</revisions>
</tsResponse>
If the revision element includes the attribute deleted="true"
, the data source has been deleted and cannot be downloaded using the
Download Data Source Revision method.
If a user has been deleted from the site, no <publisher>
element is included in the <revision>
element.
Version
Version 2.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400006 | Invalid page number | The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size. |
400 | 400007 | Invalid page size | The page size parameter is not an integer, or is less than one. |
403 | 403014 | Page size limit exceeded | The specified page size is larger than the maximum page size. |
403 | 403053 | Version history not enabled | version history is not enabled for the specified site. |
403 | 403054 | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. | |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. | |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Publish Data Source
Publishes a data source on the specified site, or appends data to an existing data source. To make other changes to a published data source, call Update Data Source or Update Data Source Connection.
Version: Available in API 2.0 and later. Version overview
License: Available for Tableau Server and Tableau Cloud.
Permissions:
You can publish a data source if you have implicit or explicit
Publish permissions for the data source, or are a Tableau administrator.
Note: The queryTaggingEnabled
attribute is returned only for administrator users.
Permissions Overview
JWT Access Scope:
tableau:datasources:create
Access Scopes Overview:
Cloud(Link opens in a new window) |
Server-Windows(Link opens in a new window) |
Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.
This method is used in two ways. You can call it to publish a data source in a single request. To do that, you include the content of the data source file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make data source publication asynchronous.
Alternatively, you can publish a data source in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Data Source. In this case, Publish Data Source doesn't contain the file to publish.
Extracts with multiple table options
Starting in v2021.4, you can publish multi table Hyper extract files created using the
Hyper API(Link opens in a new window).
The data must include a single
fact table(Link opens in a new window) containing the foreign keys that relate the tables to each other. The Hyper API infers the data object model, but
does not perform any validation, such as referential integrity checking. If the Hyper API can’t infer the data object model of a
Hyper extract, for instance, because there is more than one fact table, then attempting to publish the extract will fail.
Prior to v2021.4, there was no way to append data to an extract with multiple tables using the REST API.
Data Sources stored locally
When you publish a data source from your local computer to the server, you must make sure that the server has all the
components that are required in order for other users to see and interact with the data source. For example, if the data
source is based on an Excel spreadsheet, you typically publish a packaged data source (.tdsx
file) that contains
all the components for that data source.
Working with Parquet files
- When publishing a Parquet file to a data source through a live-to-Hyper connection, the files are converted to Hyper files.
You may want to publish a copy of your original Parquet file to retain that data in its native format.
- A data source with a live-to-Hyper connection to data in a Hyper file converted from Parquet can only have a single connection.
- When incrementally updating that data from that connection, using the Update Hyper in Data Source method, the Parquet file is not
converted to Hyper.
For more information, see Publishing Resources.
URI
POST /api/api-version/sites/site-luid/datasources
POST /api/api-version/sites/site-luid/datasources?overwrite=overwrite-flag&asJob=asJob-value
POST /api/api-version/sites/site-luid/datasources?append=append-flag
POST /api/api-version/sites/site-luid/datasources?uploadSessionId=upload-session-id&datasourceType=datasource-file-type&overwrite=overwrite-flag&append=append-flag
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site to publish to. |
overwrite-flag | true to overwrite a data source that has the same name, or false
to fail if the specified data source already exists. The default is false. If overwrite-flag
is set to true but the data source doesn't already exist, the operation succeeds.
You can include both the overwrite and append parameters in a request, but they cannot both be true. |
asJob-value | A Boolean value that is used to publish data sources asynchronously. If you set this value to false (the default), the publishing process runs as a synchronous process. If a data source is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job. |
append-flag | true to append the data being published to an existing data source that has the same name. The default
is false. If append-flag
is set to true but the data source doesn't already exist, the operation fails.
In order to append data to a published data source on Tableau Server, both the source file and the published file must be
an extract with the file extension If an extract was stored using the multiple tables option, you can't append data to it. You can include both the overwrite and append parameters in a request, but they cannot both be true. |
upload-session-luid | If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session LUID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published. |
datasource-file-type | hyper, tds, tdsx, or tde the kind of file that you are uploading. This value is required if you are calling Publish Data Source in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request. |
Request Body
The content type in the header of requests to publish a data source must use the mixed multipart content type with a boundary string definition,
in the form of:
Content-Type: multipart/mixed; boundary=boundary-string
.
Publishing a file in the request body
--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
<datasource name="Sales"
useRemoteQueryAgent="False"
description="Sales Data Source">
<connectionCredentials name="janedoe"
password="xxxxxx"
embed="True" />
<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
</datasource>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_datasource"; filename="Sales.TDSX"
Content-Type: application/octet-stream
content-of-datasource-file
--boundary-string--
a file previously uploaded
--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
<datasource name="Sales" >
<connectionCredentials name="janedoe" password="xxxxxx"
embed="False" oAuth="True" />
<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
</datasource>
</tsRequest>
--boundary-string--
Publishing a file in the request body
Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
"the_JSON" : {
"foo" : "bar"
}
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
"datasource": {
"name": "Sales",
"useRemoteQueryAgent": "True",
"description": "Sales Data Source",
"connectionCredentials": {
"name": "janedoe",
"password": "xxxxxx",
"embed": "True"
},
"project": {
"id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
}
}
}
----------------------my_boundary_string--
a file previously uploaded
Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
"the_JSON" : {
"foo" : "bar"
}
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
"datasource": {
"name": "Sales",
"connectionCredentials": {
"name": "janedoe",
"password": "xxxxxx",
"embed": "True",
"oAuth": "True"
},
"project": {
"id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
}
}
}
----------------------my_boundary_string--
Request Attributes
boundary-string
|
(Required) A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value
must be declared as a header that has this format:
|
datasource name
|
(Required) The name to assign to the data source when it is saved on the server. |
datasource useRemoteQueryAgent
|
(Optional) When true , this flag will allow your Tableau Cloud site to use Tableau Bridge clients(Link opens in a new window). Bridge allows you to maintain data sources with live connections to supported on-premises data sources.
|
datasource description
|
(Optional) A description of the datasource. |
connectionCredentials
|
The <connectionCredentials> element is required if the data source requires credentials.
If the data source does not require credentials, Tableau will ignore this element if it is present.
|
project
|
The LUID of the project to assign the data source to. If the project is not specified, the data source will be published to the default project. |
datasource-file-name
|
The file name (including extension) of the data source file to upload. This attribute is used in the request body only if the request also includes the content of the data source file; it is not used if you are committing a file uploaded using previous requests. |
content of datasource file
|
The content of the data source file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB. |
askDataEnablement
|
This attribute is not available in API 3.12 and later (Tableau Cloud September 2021 / Server 2021.3). |
cURL Example
curl "http://MY_SERVER/api/3.4/sites/ff2a8360-3c2b-4b05-a793-7607c602e1fb/datasources" -X POST -H "X-Tableau-Auth:6fSulU7ET8yjpHteQj56MQ|LrkEdTHcmPkWFcD8wOEy29hlVXm8iPo4" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-datasource.xml" -F "tableau_datasource=@data-source.tds"
Content of publish-datasource.xml:
<tsRequest>
<datasource name="datasource1" description="This is a data source named datasource1." >
<project id="522dc5c5-e1da-47b9-8e07-f02929ff5ceb" />
</datasource>
</tsRequest>
Response Code
201
Response Body
<tsResponse>
<datasource
id="75b71d2f-e8d3-42af-b654-d953659326ee"
name="Sales"
contentUrl="mySite"
description="Sales Data Source"
useRemoteQueryAgent="True"
webpageUrl="https://my_server/#/datasources/222"
type="excel-direct"
createdAt="2016-02-12T23:36:09Z"
updatedAt="2020-12-16T15:33:03Z"
isCertified="False"
certificationNote="This is a certification note."
encryptExtracts="True">
<project
id="56c86f04-b834-4a08-a561-86497bb4b2df"
name="Visualization"/>
<owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613"/>
<tags/>
</datasource>
</tsResponse>
{
"datasource": {
"id": "75b71d2f-e8d3-42af-b654-d953659326ee",
"name": "Sales",
"contentUrl": "mySite",
"description": "Sales Data Source",
"useRemoteQueryAgent": "True",
"webpageUrl": "https://my_server/#/datasources/222",
"type": "excel-direct",
"createdAt": "2016-02-12T23:36:09Z",
"updatedAt": "2020-12-16T15:33:03Z",
"isCertified": "False",
"certificationNote": "This is a certification note.",
"encryptExtracts": "True",
"project": {
"id": "56c86f04-b834-4a08-a561-86497bb4b2df",
"name": "Visualization"
},
"owner": {
"id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
},
"tags": []
}
}
The
createdAt
and
updatedAt
attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Response Headers
Location: /api/3.24/sites/site-id/datasources/id-from-server
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set. |
400 | 400000 | Missing data source | There is no attachment in the request for the data source. |
400 | 400008 | Invalid overwrite value | The overwrite parameter must be set to true or false. |
400 | 400008 | Invalid append value | The append parameter must be set to true or false. |
400 | 400008 | Invalid embed value | The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false. |
400 | 400010 | Invalid data source filename | The name of the data source file did not end with the suffix .hyper , .tds , .tdsx , or .tde . |
400 | 400010 | Missing or invalid file type | The request included an uploadSessionId parameter but no file type, or the file type was something other than hyper, tds, tdsx, or tde. |
400 | 400010 | Unexpected attachments | The message had both a uploadSessionId parameter and an attachment, or the message contained more than one attachment. |
400 | 400011 | Publishing error | The data source could not be published for some other reason than those specified earlier. |
400 | 400019 | Malformed request body | The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set. |
400 | 400055 | Incompatible overwrite and append values | The overwrite and append parameter cannot both be set to true. |
400 | 400129 | Invalid Ask Data enablement | The enablement setting in the request body is not valid for the current server configuration. |
403 | 403007 | Insufficient publishing permission | A non-administrator user attempted to publish a data source, but the caller doesn't have sufficient project permissions. |
403 | 403007 | Unlicensed publishing forbidden | A non-administrator user who is unlicensed attempted to publish a data source. This is disallowed for all projects (including the default project). |
403 | 403007 | Overwrite forbidden | A data source with the specified name already exists and the overwrite parameter was not set to true. |
403 | 403007 | Problem connecting to data source | There was a problem connecting to a data source. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server. |
403 | 403008 | Insufficient storage quota | The data source could not be published because there is not enough storage remaining on the server to accommodate its size. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The append parameter is true but the data source name specified in the request body does not correspond to an existing data source. |
404 | 404005 | Project not found | The project ID in the request body doesn't correspond to an existing project on the site. |
404 | 404015 | File upload not found | The file upload session ID in the request body doesn't correspond to an existing file upload on the site. |
405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.
Query Data Source
Returns information about the specified data source.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
GET /api/api-version/sites/site-id/datasources/datasource-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The site that contains the data source. |
datasource-id | The ID of the data source to get. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:content:read
Response Code
200
Response Body
<tsResponse>
<datasource id="datasource-id"
certificationNote="certification-note"
name="datasource-name"
description="data-source-description"
type="datasource-type"
contentUrl="datasource-content-url"
createdAt="datetime-created"
updatedAt="datetime-updated"
encryptExtracts="encryptExtracts"
hasExtracts="has-extracts-flag"
isCertified="is-certified-flag"
useRemoteQueryAgent="use-remote-query-agent-flag"
webpageUrl="web-page-url" >
<project id="project-id" name="project-name" />
<owner id="datasource-owner-id" />
<tags>
<tag label="tag"/>
... additional tags ...
</tags>
<askData enablement="enablement-setting"/>
</datasource>
</tsResponse>
The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Read forbidden | A non-administrator user attempted to query a data source, but the caller doesn't have Connect permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" name="Activity rates and healthy living"
certificationNote="This is a note about the datasource certification."
contentUrl="activity-dates-and-healthy-living"
encryptExtracts="true"
description="The Activity and Health data source."
isCertified="true"
type="excel-direct"
createdAt="2011-03-30T22:32:35Z"
updatedAt="2016-01-13T01:00:02Z">
useRemoteQueryAgent="false"
webpageUrl="https://MYSERVER/#/datasources/4414"
<project id="1f2f3e4e5-d6d7-c8c9-b0b1-a2a3f4f5e6e" name="default"/>
<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
<tags>
</tags>
<askData enablement="Enabled"/>
</datasource>
</tsResponse>
Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.
Query Data Sources
Returns a list of published data sources on the specified site, with optional parameters for specifying the paging of large results. To get a list of data sources embedded in a workbook, use the Query Workbook Connections method.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
GET /api/api-version/sites/site-id/datasources
GET /api/api-version/sites/site-id/datasources?pageSize=page-size&pageNumber=page-number
GET /api/api-version/sites/site-id/datasources?filter=filter-expression
GET /api/api-version/sites/site-id/datasources?sort=sort-expression
GET /api/api-version/sites/site-id/datasources?fields=field-expression
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data sources. |
page-size | (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results. |
page-number | (Optional) The offset for paging. The default is 1. For more information, see Paginating Results. |
filter-expression | (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name and updatedAt . You can
include multiple filter expressions. For more information, see Filtering and Sorting.
|
sort-expression | (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting. |
field-expression | (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as
_all_ or _default_ , and you can specify individual fields for the data sources or other supported resources. You can
include multiple field expressions in a request. For more information, see Using Fields in the Rest API.
|
Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&
).
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<pagination pageNumber="pageNumber" pageSize="page-size"
totalAvailable="total-available" />
<datasources>
<datasource id="datasource1-id"
description="data-source-description"
name="datasource-name"
size="datasource-size"
type="datasource-type"
contentUrl="datasource-content-url"
createdAt="datetime-created"
updatedAt="datetime-updated"
encryptExtracts="encrypt-extracts-flag"
hasExtracts="has-extracts-flag"
isCertified="is-certified-flag"
useRemoteQueryAgent="use-remote-query-agent-flag"
webpageUrl="datasource-webpage-url" >
<project id="project-id" name="project-name" />
<owner id="datasource-owner-id" />
<tags>
<tag label="tag"/>
... additional tags ...
</tags>
</datasource>
... additional data sources ...
</datasources>
</tsResponse>
The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400006 | Invalid page number | The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size. |
400 | 400007 | Invalid page size | The page size parameter is not an integer, or is less than one. |
403 | 403014 | Page size limit exceeded | The specified page size is larger than the maximum page size. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
<datasources>
<datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b"
name="Sample - Coffee Chain (Access)"
contentUrl="coffee-chain"
description="The Sample - Coffee Chain data source."
type="msaccess"
createdAt="2011-03-30T22:32:35Z"
updatedAt="2016-01-13T01:00:02Z"
encryptExtracts="false"
isCertified="false"
useRemoteQueryAgent="false"
webpageUrl="https://my-server.com/#/site/my-site/datasources/1275708" >
<project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Default"/>
<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
<tags>
<tag label="test"/>
</tags>
</datasource>
</datasources>
</tsResponse>
Query Data Source Connections
Returns a list of data connections for the specified data source.
URI
GET /api/api-version/sites/site-id/datasources/datasource-id/connections
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to return connection information about. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can query a data source only if
they have Read (view) permission for the data source (either explicitly or implicitly).
queryTaggingEnabled
is returned only for administrator users.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:content:read
Response Code
200
Response Body
<tsResponse>
<connections>
<connection id="connection-id" type="connection-type"
serverAddress="server-address" serverPort="port"
userName="connection-user-name"
queryTaggingEnabled="query-tagging-enabled"
authenticationType="authentication-type"
useOAuthManagedKeychain="using-OAuth-managed-keychain-or-not /> />
< ... additional connections ... >
</connections>
</tsResponse>
Version
Version 2.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403021 | Read forbidden | A user who is not a server administrator user attempted to query the data source connections, but the caller doesn't have Read permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404011 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<connections>
<connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" type="dataengine" />
<connection id="374371c0-ffe9-4e16-b48e-6b868e3026ca" type="dataengine" />
<connection id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" type="dataengine" />
</connections>
</tsResponse>
Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.
Remove Data Source Revision
Removes a specific version of a data source from the specified site.
The content is removed, and the specified revision can no longer be downloaded using Download Data Source Revision.
If you call Get Data Source Revisions, the revision that's been removed is listed with the attribute IsDeleted="true"
.
Note: Calling this method permanently removes the specified data source revision.
URI
DELETE /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the group. |
datasource-id | The ID of the data source to remove the revision for. |
revision-number | The revision number of the data source to remove. To determine what versions are available, call Get Data Source Revisions. |
Request Body
None
Permissions
Tableau Server users who are site administrators can remove data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can remove data source revisions if they have all of the following:
- A site role of ExplorerCanPublish.
- Read (view), Write (save), and Download (save as) permissions for the specified data source.
- Save (write) permissions for the project that contains the data source.
Response Code
204
Response Body
None
Version
Version 2.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Deletion forbidden | A non-administrator user attempted to remove a data source revision, but the caller doesn't have required permissions. |
403 | 403053 | Version history not enabled | version history is not enabled for the specified site. |
403 | 403055 | Cannot delete head revision | The head (first) version cannot be deleted. To remove the data source, call Delete Data Source. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404006 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404024 | Data source revision not found | The revision number in the URI doesn't correspond to an existing data source revision. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Update Data in Hyper Connection
Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has multiple connections.
A live-to-Hyper connection has a Hyper or Parquet formatted file/database as the origin of its data.
For all connections to Parquet files, and for any data sources with a single connection generally, you can use the
Update Data in Hyper Data Source method
without specifying the connection-id
.
A request for this method must include an upload-session-id
for a Hyper file payload containing an upload of the most
current data from the data source for your published live-to-Hyper data. Use
Initiate File Upload(Link opens in a new window) and
Append to File Upload(Link opens in a new window) methods
to form the payload and acquire upload-session-id.
For details and examples, see Update Data in Published Live-to-Hyper Data Sources.
Note:
While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and large
changes in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests are
limited by the server configuration setting api.server.update_uploaded_file.max_size_in_mb
. Starting in
Tableau Server 2022.1 / Tableau Cloud March 2022, the default for this setting is 100MB. In previous versions, the limit was set to 10MB.
Where heavy incremental update traffic is expected, we recommend you use a chunking strategy to limit the size of each update, and
fine tune max_size_in_mb
value to optimize performance for your exact conditions.
URI
PATCH /api/api-version/sites/site-id/datasources/datasource-id/connections/connection-iddata?uploadSessionId=upload-session-id
Parameter Values
api-version | The version of the API to use, such as 3.24 .
For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to update. |
connection-id | The ID of the connection. To determine what connections are available for a data source, call Query Data Source Connections. |
upload-session-id | The upload session ID. A user-generated identifier that is unique to a request. If the server receives more than one request with the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests. |
Request Body
This method supports only JSON content-type for the request body.
{"actions": [
{"action": action-type",
"source-schema": "source-schema-name",
"source-table": "source-table-name",
"target-schema": "target-schema-name",
"target-table": "target-table-name",
"condition": {conditional-declaration"}
. . . more action definition . . .}
}
{. . . more actions . . .}
]}
Attribute Values
actions-type | (Required) The definition of the operation(s) to perform on the data in the target hyper file. |
source-schema-name | (Optional) The name of the source database schema for the data to be updated. A value is not required unless there are multiple schemas in the database. |
source-table-name | (Required) The name of the source database table containing the data to be updated. |
target-schema-name | (Optional) The name of the target hyper file schema of the data to be updated from the source database. A value is not required unless there are multiple schemas in the database. |
target-table-name | (Required) The name of the table containing the data to be updated in the target hyper file. |
condition | (Required for insert , upsert , and delete )A declaration that defines a
comparison operation between source and target data or between source or target data and a user provided constant.
For details and examples, see Update Data in Published
Live-to-Hyper Data Sources. |
An action
is an operation to be performed on specified target data. Multiple different actions can be
defined as a batch in a request. The supported actions are:
-
insert
- Inserts rows from a named source-table in your data source into a named target-table in your published Hyper. A simplified example is:{"action": "insert", "source-table": "added_users", "target-table": "current_users"}
-
update
– Updates existing tuples from a namedsource-table
in your data source into a namedtarget-table
in your published Hyper. The tuples to be updated are defined in a condition declaration. A simplified example is:{"action": "update", "target-table": "my_data", "source-table": "uploaded_table", "condition": {"op": "eq", "target-col": "row_id", "source-col": "update_row_id"} }
-
upsert
- Updates a tuple inside thetarget-table
, if such a tuple exists. If no such tuple exists, a new tuple will be inserted. The tuples to be updated are defined in a condition declaration. A simplified example is:{"action": "upsert", "target-table": "my_data", "source-table": "uploaded_table", "condition": {"op": "gt", "target-col": "row_id", "source-col": "update_row_id"} }
-
replace
– Deletes all tuples from atarget-table
and inserts all data from asource-table
with a matching schema. A simplified example is:{"action": "replace", "source-table": "added_users", "target-table": "current_users"}
-
delete
– Deletes tuples from a target-table. The tuples to be deleted are defined in a condition declaration. A simplified example is:{"action": "delete", "target-table": "my_extract_table", "source-table": "deleted_row_id_table", "condition": {"op": "gt", "target-col": "id", "source-col": "deleted_id"} }
For more information, see Update Data in Published Live-to-Hyper Data Sources.
Permissions
The user calling this method must be the data source owner and must have the overwrite permission on it.
Request Header
In addition to the typical authentication token, the following fields must be specified as part of the request header:
content-type: application/json
- This endpoint accepts JSON only.-
RequestID
- A user-generated identifier that uniquely identifies a request. If the server receives more than one request with the same id within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests, which prevents executing the same job more than once could be caused by network anomalies or client crashes.
Response Code
200
Response Body
The response body returns the job-id, which specifies the ID of the async job that will carry out the data operations described in the action batch. This returned "job-id" can be used to query the status of the update job(Link opens in a new window) or to cancel a scheduled job(Link opens in a new window).
(job-id: "scheduled-job-luid"}
Version
Version 2o21.2 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed JSON. |
400 | 400008 | Invalid parameter value | A parameter in the request body is missing or invalid. |
403 | 403062 | Update data source multiple connections forbidden | A connection ID is required because the data source has multiple connections. Consider using Update Data in Hyper Connection to specify the connection. (This error does not apply to that Connection method) |
403 | 403032 | Update forbidden | A non-administrator user tried to update a data source, but the caller doesn't have Write permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source LUID in the request body doesn't correspond to an existing data source. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404008 | Operation not supported | The operation requested is not supported, the source data for the connection must be a Hyper file/database. |
404 | 404020 | Connection not found | No resource was found for the specified connection and data source. (This error does not apply to Update Data in Hyper Data Source) |
405 | 405000 | Invalid request method | Request type was not PATCH. |
409 | 409015 | Data source name conflict | The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive. |
409 | 409094 | Data update job already exists | A data update job for the datasource is already queued or in progress. |
For more information, see Handling Errors.
Update Data in Hyper Data Source
Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has a single connection.
A live-to-Hyper connection has a Hyper or Parquet formatted file/database as the origin of its data.
For data sources with multiple connections, you can specify which to update using the Update Data in Hyper Data Source method.
A request for this method must include an upload-session-id
for a Hyper file payload containing an upload of the most
current data from the data source for your published live-to-Hyper data. Use
Initiate File Upload(Link opens in a new window) and
Append to File Upload(Link opens in a new window) methods
to form the payload and acquire upload-session-id.
For details and examples, see Update Data in Published Live-to-Hyper Data Sources.
Note:
While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and large
changes in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests are
limited by the server configuration setting api.server.update_uploaded_file.max_size_in_mb
. Starting in
Tableau Server 2022.1 / Tableau Cloud March 2022, the default for this setting is 100MB. In previous versions, the limit was set to 10MB.
Where heavy incremental update traffic is expected, we recommend you use a chunking strategy to limit the size of each update, and
fine tune max_size_in_mb
value to optimize performance for your exact conditions.
Working with Parquet files
- When publishing a Parquet file to a data source through a live-to-Hyper connection, the files are converted to Hyper files.
You may want to publish a copy of your original Parquet file to retain that data in its native format.
- A data source with a live-to-Hyper connection to data in a Hyper file converted from Parquet can only have a single connection.
- When incrementally updating that data from that connection, using the Update Hyper in Data Source method, the Parquet file is not
converted to Hyper.
URI
PATCH /api/api-version/sites/site-id/datasources/datasource-id/data?uploadSessionId=upload-session-id
Parameter Values
api-version | The version of the API to use, such as 3.24 .
For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to update. |
upload-session-id | The upload session ID. A user-generated identifier that is unique to a request. If the server receives more than one request with the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests. |
Request Body
This method supports only JSON content-type for the request body.
{"actions": [
{"action": action-type",
"source-schema": "source-schema-name",
"source-table": "source-table-name",
"target-schema": "target-schema-name",
"target-table": "target-table-name",
"condition": {conditional-declaration"}
. . . more action definition . . .}
}
{. . . more actions . . .}
]}
Attribute Values
actions-type | (Required) The definition of the operation(s) to perform on the data in the target hyper file. |
source-schema-name | (Optional) The name of the source database schema for the data to be updated. A value is not required unless there are multiple schemas in the database. |
source-table-name | (Required) The name of the source database table containing the data to be updated. |
target-schema-name | (Optional) The name of the target hyper file schema of the data to be updated from the source database. A value is not required unless there are multiple schemas in the database. |
target-table-name | (Required) The name of the table containing the data to be updated in the target hyper file. |
condition | (Required for insert , upsert , and delete )A declaration that defines a
comparison operation between source and target data or between source or target data and a user provided constant.
For details and examples, see Update Data in Published
Live-to-Hyper Data Sources. |
An action
is an operation to be performed on specified target data. Multiple different actions can be
defined as a batch in a request. The supported actions are:
-
insert
- Inserts rows from a named source-table in your data source into a named target-table in your published Hyper. A simplified example is:{"action": "insert", "source-table": "added_users", "target-table": "current_users"}
-
update
– Updates existing tuples from a namedsource-table
in your data source into a namedtarget-table
in your published Hyper. The tuples to be updated are defined in a condition declaration. A simplified example is:{"action": "update", "target-table": "my_data", "source-table": "uploaded_table", "condition": {"op": "eq", "target-col": "row_id", "source-col": "update_row_id"} }
-
upsert
- Updates a tuple inside thetarget-table
, if such a tuple exists. If no such tuple exists, a new tuple will be inserted. The tuples to be updated are defined in a condition declaration. A simplified example is:{"action": "upsert", "target-table": "my_data", "source-table": "uploaded_table", "condition": {"op": "gt", "target-col": "row_id", "source-col": "update_row_id"} }
-
replace
– Deletes all tuples from atarget-table
and inserts all data from asource-table
with a matching schema. A simplified example is:{"action": "replace", "source-table": "added_users", "target-table": "current_users"}
-
delete
– Deletes tuples from a target-table. The tuples to be deleted are defined in a condition declaration. A simplified example is:{"action": "delete", "target-table": "my_extract_table", "source-table": "deleted_row_id_table", "condition": {"op": "gt", "target-col": "id", "source-col": "deleted_id"} }
For more information, see Update Data in Published Live-to-Hyper Data Sources.
Permissions
The user calling this method must be the data source owner and must have the overwrite permission on it.
Request Header
In addition to the typical authentication token, the following fields must be specified as part of the request header:
content-type: application/json
- This endpoint accepts JSON only.-
RequestID
- A user-generated identifier that uniquely identifies a request. If the server receives more than one request with the same id within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests, which prevents executing the same job more than once could be caused by network anomalies or client crashes.
Response Code
200
Response Body
The response body returns the job-id, which specifies the ID of the async job that will carry out the data operations described in the action batch. This returned "job-id" can be used to query the status of the update job(Link opens in a new window) or to cancel a scheduled job(Link opens in a new window).
(job-id: "scheduled-job-luid"}
Version
Version 2o21.2 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed JSON. |
400 | 400008 | Invalid parameter value | A parameter in the request body is missing or invalid. |
403 | 403062 | Update data source multiple connections forbidden | A connection ID is required because the data source has multiple connections. Consider using Update Data in Hyper Connection to specify the connection. (This error does not apply to that Connection method) |
403 | 403032 | Update forbidden | A non-administrator user tried to update a data source, but the caller doesn't have Write permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source LUID in the request body doesn't correspond to an existing data source. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404008 | Operation not supported | The operation requested is not supported, the source data for the connection must be a Hyper file/database. |
404 | 404020 | Connection not found | No resource was found for the specified connection and data source. (This error does not apply to Update Data in Hyper Data Source) |
405 | 405000 | Invalid request method | Request type was not PATCH. |
409 | 409015 | Data source name conflict | The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive. |
409 | 409094 | Data update job already exists | A data update job for the datasource is already queued or in progress. |
For more information, see Handling Errors.
Update Data Source
Updates the owner, project or certification status of the specified data source.
Version: Available in API Version 2.0 and later. Version Overview
License:No additional license required.
Permissions: You can update data source details if you are a Tableau administrator. Specific properties can be updated by other users depending on the type of update action and the permissions granted to the user . . . learn more | Permissions Overview
JWT Access Scope:
tableau:datasources:update
Access Scopes Overview:
Cloud(Link opens in a new window) |
Server-Windows(Link opens in a new window) |
Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.
URI
PUT /api/api-version/sites/site-id/datasources/datasource-id
Starting in 2021.2, you can also modify (insert, update, upsert, replace and delete) data in a published data source that is a live-to-Hyper connection. To do this, use the Update Data in Hyper Data Source method, or for data sources with multiple connections, use the Update Data in Hyper Connection method. For more information, see UpdateData in Published Live-to-Hyper Data Sources.
Path Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site that contains the data source. |
datasource-luid | The LUID of the data source to update. |
Request Body
<tsRequest>
<datasource name="Sales"
isCertified="true"
certificationNote="This is a certification note."
encryptExtracts="false">
<project id="56c86f04-b834-4a08-a561-86497bb4b2df"/>
<owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613"/>
<askData enablement="true [REMOVED IN API 3.12]"/>
</datasource>
</tsRequest>
{
"datasource": {
"name": "Sales",
"isCertified": "true",
"certificationNote": "This is a certification note.",
"encryptExtracts": "false",
"project": {
"id": "56c86f04-b834-4a08-a561-86497bb4b2df"
},
"owner": {
"id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
},
"askData": {
"enablement": "true [REMOVED IN API 3.12]"
}
}
}
Request Attributes
datasource name
|
(Optional) The new name of a the data source. |
project
|
(Optional) The LUID of a project to add the data source to. |
owner
|
(Optional) The LUID of a user to assign the data source to as owner. |
datasource certification-status
|
(Optional) A Boolean value that indicates whether the data source is certified. To learn more about data source certification, see Use Certified and Recommended Data Sources and Tables. |
datasource certification-note
|
(Optional) A note that provides more information on the certification of the data source, if applicable. |
datasource encryptExtracts
|
(Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods. |
askDataEnablement
|
This attribute is removed in API 3.12 and later (Tableau Cloud September 2021 / Server 2021.3).
(Optional) Determines if a data source allows use of Ask Data. The value can be
If |
Any combination of the attributes inside the <datasource> element is valid. Only the attributes and child elements that are included result in updates to the data source. If no attributes or nested elements are included, no update is made.
If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.
If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.
Permissions Details
Users who are server administrators or site administrators can change the owner for a data source.
Users who are not server administrators can move a data source from one project to another if they own the data source or the current (source) project, or are a project leader for the current project, and they have Write permission for the destination project.
Users can change certification status and the certification note if they are server administrators, site administrators, or project leaders for the current project.
Users can modify the name of the data source if: they have server or site administrator permissions, or the site role of Creator or higher and access to the data source with the overwrite capability.
cURL Example
curl --location --request GET "https://MY_SERVER/api/3.16/sites/a946d998-2ead-4894-bb50-1054a91dcab3/datasources" \ --header "X-Tableau-Auth: b09KVmT7QxuLVLv1En7iMg"oxKwSGTYT0WKRes5xk3dgI4gIkG3TM8W"a946d998-2ead-4894-bb50-1054a91dcvv8" \ --header "Content-Type: application/xml" \ --data-raw "<tsRequest/> <datasource name='Sales'/> >datasource/> >tsRequest/>"
Response Code
200
Response Body
<tsResponse>
<datasource name="Sales" id="75b71d2f-e8d3-42af-b654-d953659326ee"
contentUrl="mySite" type="excel-direct"
createdAt="2016-02-12T23:36:09Z" updatedAt="2020-12-16T15:33:03Z"
isCertified="false"
certificationNote="This is a certification note."
encryptExtracts="false">
<project id="56c86f04-b834-4a08-a561-86497bb4b2df" />
<owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613" />
<job id="65348c74-7818-4eb8-b2a1-9f3f5f588870" />
<askData enablement="true [REMOVED IN API 3.12]" />
</datasource>
</tsResponse>
{
"datasource": {
"name": "Sales",
"id": "75b71d2f-e8d3-42af-b654-d953659326ee",
"contentUrl": "mySite",
"type": "excel-direct",
"createdAt": "2016-02-12T23:36:09Z",
"updatedAt": "2020-12-16T15:33:03Z",
"isCertified": "false",
"certificationNote": "This is a certification note.",
"encryptExtracts": "false",
"project": {
"id": "56c86f04-b834-4a08-a561-86497bb4b2df"
},
"owner": {
"id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
},
"job": {
"id": "65348c74-7818-4eb8-b2a1-9f3f5f588870"
},
"askData": {
"enablement": "true [REMOVED IN API 3.12]"
}
}
}
The
createdAt
and
updatedAt
attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400008 | Invalid parameter value | A user attempted to rename a datasource to a name containing only spaces, or to a name with more 255 characters. |
400 | 400129 | Invalid Ask Data enablement | The requested enablement setting in the request body does not correspond to the site configuration. |
403 | 403027 | Owner update forbidden | A non-administrator user tried to change the owner for the data source. |
403 | 403030 | Project update forbidden | A non-administrator user tried to change the project for the data source, but the caller doesn't have Write permission for the project. |
403 | 403032 | Update forbidden | A non-administrator user tried to update a data source, but the caller doesn't have Write permission. |
403 | 403141 | Update forbidden | A user attempted to update a data source that they do not have permissions to update. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | Owner not found | The owner ID in the request body doesn't correspond to an existing owner. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
404 | 404005 | Project not found | The project ID in the request body doesn't correspond to an existing project. |
405 | 405000 | Invalid request method | Request type was not PUT or PATCH. |
409 | 409015 | Data source name conflict | The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive. |
For more information, see Handling Errors.
Update Data Source Connection
Updates the server address, port, username, or password for the specified data source connection.
Version: Available in API Version 2.3 . . . learn more | Version Overview
License: Available for Tableau Server and Tableau Cloud.
Permissions: Users who are server administrators or site administrators can change the connection for a data source or enable query tagging(Link opens in a new window). Users who are not server administrators can update a data source only. . . learn more | Permissions overview
JWT Access Scope: tableau:datasources:update
access scope details
URI
PUT /api/api-version/sites/site-id/datasources/datasource-id/connections/connection-id
Path Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site that contains the data source. |
datasource-luid | The LUID of the data source to update. |
connection-luid | The LUID of the connection to update. To determine what connections are available for a data source, call Query Data Source Connections. |
Request Body
<tsRequest>
<connection
serverAddress="newAddress"
serverPort="newPort"
userName="Jane Doe"
password="xxxxxx"
embedPassword="false"
queryTaggingEnabled="false" />
</tsRequest>
{
"connection": {
"serverAddress": "newAddress",
"serverPort": "newPort",
"userName": "Jane Doe",
"password": "xxxxxx",
"embedPassword": "false",
"queryTaggingEnabled": "false"
}
}
Request Attributes
connection serverAddress
|
(Required) The new server for the connection. |
connection serverPort
|
(Required) The new port for the connection |
connection userName
|
(Required) The new username for the connection. |
connection password
|
(Required) The new password for the connection. |
embedPassword
|
True to embed the password; otherwise, False . |
queryTaggingEnabled
|
In API 3.23 (Tableau Cloud June 2024 / Server 2024.2) and later:
using For API 3.22 or earlier: |
Any combination of the attributes inside the <connection> element is valid. If no attributes are included, no update is made.
Permissions Details
Users who are server administrators or site administrators can change the connection for a data source or enable query tagging(Link opens in a new window). Users who are not server administrators can update a data source only. If they have Write (save) permission for the data source and if they have write permission for the project.
Version Details
Version 2.3 and later. (A different version of this method was available in earlier versions of the REST API. For details, see Update Data Source Connection(Link opens in a new window) in the REST API version 9.3 documentation.) For more information, see REST API and Resource Versions.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:datasources:update
Response Code
200
Response Body
<tsResponse>
<connection id="90365b4d-978f-425b-bb53-66a984bab34v"
serverAddress="newAddress"
serverPort="newPort"
userName="Jane Doe"
queryTaggingEnabled="false" />
</tsResponse>
{
"connection": {
"id": "90365b4d-978f-425b-bb53-66a984bab34v",
"serverAddress": "newAddress",
"serverPort": "newPort",
"userName": "Jane Doe",
"queryTaggingEnabled": "false"
}
}
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
403 | 403023 | Update forbidden | A non-administrator user tried to update a data source, but the caller doesn't have Write permission. |
403 | 403027 | Owner update forbidden | A non-administrator user tried to change connection information, but the caller doesn't have Write permission. |
403 | 403062 | Unsupported operation | The data source contains multiple connections, but the URI did not include /connections/connection-id to indicate which
connection should be updated. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl --location --request PUT "https://MY_SERVER/api/3.16/sites/a946d998-2ead-4894-bb50-1054a91dcab3/datasources/75b71d2f-e8d3-42af-b654-d953659326ee/connections/90365b4d-978f-425b-bb53-66a984bab10c" \ --header "X-Tableau-Auth: TimrTnJ3QqSzqA7bg65WMQ"3F3Gfr186RJTCovRpYyyw5KuNU3saxuu"a946d998-2ead-4894-bb50-1054a91dcab3" \ --header "Content-Type: application/xml" \ --data-raw "<tsRequest> <connection queryTaggingEnabled='true' /> </tsRequest>"
Update Data Source Now
Runs an extract refresh on the specified data source.
Note: This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).
This method runs an extract refresh for the specified data source, with no need to associate that extract refresh with a scheduled task.
This method is the equivalent of selecting a data source using the Tableau Server UI, and then selecting Refresh Extracts from the menu
(also known as a "manual refresh"), however, the REST method always runs a full refresh even if the refresh type is set to incremental. Similar to a manual refresh, if the extract is a .tde
file, it will be converted to a
.hyper
file as a result of the refresh. To learn more about extract upgrades to the .hyper
file format, see
Extract Upgrade to .hyper Format.
URI
POST /api/api-version/sites/site-id/datasources/datasource-id/refresh
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the data source. |
datasource-id | The ID of the data source to refresh. |
Request Body
<tsRequest>
</tsRequest>
Permissions
Users who are not server administrators or site administrators can only refresh extracts for data sources if they own the data source, or if they are the project leader for the project.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:tasks:run
Response Code
202
Response Body
<tsResponse>
<job id="job-id" mode="Asynchronous" type="RefreshExtract" createdAt="date-time">
<extractRefreshJob>
<datasource id="datasource-id" name="datasource-name" />
</extractRefreshJob>
</tsResponse>
Version
Version 2.8 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
401 | 401000 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
403 | 403032 | Update Forbidden | A non-administrator user attempted to update a data source, but the caller doesn't have sufficient permissions. |
404 | 404000 | Site not found | The site ID in the URI is unknown. |
404 | 404004 | Data source not found | The data source ID in the URI is unknown. |
405 | 405000 | Invalid request method | Request type was not POST. |
409 | 409093 | Operation already in Queue | The extract refresh job is already in the queue. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/datasources/89a82d78-664f-45a1-8256-d4d2961a070b/refresh" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"
Content of empty-tsrequest.xml:
<tsRequest>
</tsRequest>
Example response:
<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-2.8.xsd">
<job id="20cf4ddc-6d73-4733-89ec-8d336669bd56" mode="Asynchronous" type="RefreshExtract" createdAt="2017-12-06T22:58:52Z">
<extractRefreshJob>
<datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" name="World Indicators Extract" />
</extractRefreshJob>
</job>
</tsResponse>
Upload Data Source Encrypted Keychain
Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.
Version: Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
URI
PUT /api/api-version/sites/site-luid/datasources/datasource-luid/applykeychain
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions.
|
site-luid | The LUID for the site. |
datasource-luid | The LUID of the data source to download the encrypted keychain from. |
Request Body
<tsRequest> <associatedUserLuidMapping/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain> </encryptedKeychainList> </tsRequest>
{ "associatedUserLuidMapping": [], "encryptedKeychainList": { "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=" } }
Request Attributes
associatedUserLuidMapping
|
(Required) The user IDs from the source site mapped to destination site user IDs. |
encryptedKeychainList
|
(Required) List of encrypted keychains from the source Tableau Server. |
cURL Request Example
curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/applykeychain" --header "Content-Type: application/xml" --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86" --data "<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid> <destinationServerUrl>http://example.com</destinationServerUrl> </tsRequest>"
Response Code
200
Response Body
None.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
401 | 401002 | Unauthorized Access |
The authentication token provided in the request header was invalid or has expired. |
403 | 403054 | Unauthorized Access | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.