Extract and Encryption Methods

Extracts(Link opens in a new window) are saved subsets of data that you can use to improve performance, or to take advantage of Tableau functionality not available or supported in your original data).

Using the extract methods of the Tableau Server REST API you can:

  • Create an extract from a published data source (used by all workbooks in a site that consume the data source)
  • Create extracts from the data sources of a published workbook (includes embedded data sources and embedding of published data sources for workbook-specific extract configuration).
  • Delete the extract of a data source.
  • Delete the extracts of a workbook.
  • Enable encryption and decryption of extracts on a site when you use Create Site or Update Site methods.
  • Set the scope of encryption to be all extracts on a site, or allow the users to use Publish Data Source, Publish Workbook, Update Data Source, or Update Workbook methods to enable or disable encryption for each workbook or data source on a site.
  • Encrypt and decrypt extracts on a site
  • Reencrypt extracts on a site with new security keys

This functionality relates to the UI elements and concepts described at: Extract Your Data(Link opens in a new window).

About Extract Encryption

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).

The extract encryption mode is set at the site level. To set the mode, use the Create Site or Update Site methods with the extractEncryptionMode attribute. The extract encryption modes are:

  • enforced: enforce encryption of all extracts on the site.
  • enabled: allow users to specify to encrypt all extracts associated with specific published workbooks or data sources.
  • disabled: disable extract encryption on the site.

To get the site extract encryption mode, use the Query Site method, which shows the extractEncryptionMode attribute in its response body.

When the site extract encryption mode is set to enforced, all content is encrypted. You can use the reencrypt-extracts method to reencrypt all extracts on a site.

When the site extract encryption mode is set to enabled, users can decide to encrypt or decrypt the extracts associated with specific published workbooks or data sources. To do this, use the Publish Data Source, Publish Workbook, Update Data Source, or Update Workbook methods with the encryptExtracts attribute. Set the encryptExtracts attribute to true to encrypt the extracts. The user must be the owner or administrator. To get the extract encryption status, use the Query Data Source or Query Workbook methods, which show the encryptExtracts attribute in the response body.

When the site extract encryption mode is set to enabled, the owner or administrator can encrypt, decrypt, and reencrypt all extracts associated with workbooks or data sources on a site.

When the site extract encryption mode is set to disabled, all encrypted extracts will be decrypted. Depending on the number and size of extracts, this operation may consume significant server resources.

Create an Extract for a Data Source

Create an extract for a data source in a site. Optionally, encrypt the extract if the site and workbooks using it are configured to allow it.

URI

POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract

POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract?encrypt=encryption-flag

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
datasource-id The LUID of the datasource.
encryption-flag If true, then Tableau will attempt to encrypt the created extracts. If false, or no encrypt parameter is appended to the URI, then the extract won't be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when encrypt equals true and encryption is disabled in the site or workbook.

Request Body

None

Permissions

Extracts for data sources can be created by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

Response Code

200

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
    <extractCreationJob>
	  <datasource id="datasource-id" name="datasource-name" />
  </extractCreationJob>
</tsResponse>

Version

Version 3.5 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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"

Response body:

<tsResponse>
  <job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
    <extractCreationJob>
        <datasource id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_DATASOURCE_NAME"/>
      <jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
    </extractCreationJob>
  </job>
</tsResponse>  

Delete the Extract from a Data Source

Delete the extract of a data source in a site.

URI

POST /api/api-version/sites/site-id/datasources/datasource-id/deleteExtract

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
datasource-id The LUID of the datasource whose extract is to be deleted.

Permissions

Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

Response Code

204 No Content

Response Body

None.

Version

Version 3.5 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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"

Response body:

None.

Create Extracts for Embedded Data Sources in a Workbook

Create extracts for all embedded data sources of a workbook. Optionally, encrypt the extracts if the site and workbook using them are configured to allow it.

When you create an extract for a data source in a workbook, the extract is available only to the workbook and may have configuration specific to the workbook, such as hiding of unused fields.

You can create workbook extracts for both embedded and published data sources used by the workbook. When you create a workbook data source for a published data source, then refreshing the workbook extract will retrieve any changes to data from the published datasource, or from the published data source's extract if it is using one.

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).

URI

POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract

POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract?encrypt=encryption-flag

Path Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
workbook-id The LUID of the workbook.
encryption-flag If true, then Tableau will attempt to encrypt the created extracts. If false, or no encrypt parameter is appended to the URI, then the extract won't be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when encrypt equals true and encryption is disabled in the site or workbook.

Request Body

<tsRequest>
  <datasources includeAll="extract-all-datasources-flag">
	<datasource id="datasource-id" />
  </datasources>
</tsRequest>

Request Parameter Values

api-version Boolean. If true, then create extracts for all datasources embedded in a workbook. If false (default), then a datasource must be specified in the request.
datasource-id LUID of the embedded data source to be extracted.
extract-all-datasources-flag Boolean. If true, then all data sources in the workbook will have an extract created for them. If false, then a data source must be supplied in the request.

Permissions

Extracts for data sources embedded in a workbook can be created by Tableau server or site administrators, and users who own the workbook, or are an owner or leader of the project where the workbook resides.

Response Code

200

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
    <extractCreationJob>
      <workbook id="workbook-id" name="workbook-name" />
	</extractCreationJob>
  </job>
</tsResponse>

Version

Version 3.5 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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@create-extracts-for-workbook.xml"

Content of create-extracts-for-workbook.xml

<tsResponse>
  <datasources includeAll="false" />
    <datasource id="6b4cf715-c90b-49d6-be85-920a47bae433" />
  </datasources>
</tsRequest>

Response body:

<tsResponse>
  <job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
	<extractCreationJob>
	  <workbook id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_WORKBOOK_NAME"/>
	  <jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
    </extractCreationJob>
  </job>
</tsResponse>

Delete Extracts of Embedded Data Sources from a Workbook

Delete all extracts of embedded data sources in a workbook.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

URI

POST /api/api-version/sites/site-id/workbookss/workbook-id/deleteExtract

Path Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
datasource-id The LUID of the workbook containing the extract to be deleted.

Permissions

Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

Request Body

<tsRequest>
  <datasources includeAll="true"/>
</tsRequest>

Request Parameter Values

None.

Response Code

200

Response Body

None.

Version

Version 3.5 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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@delete-extracts-for-workbook.xml"

Content of create-extracts-for-workbook.xml

<tsResponse>
  <datasources includeAll="true" />
</tsRequest>

Response body:

None. Response code is 200.

Encrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).

Encrypts all extracts on a site.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

URI

POST /api/api-version/sites/site-id/encrypt-extracts

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site.

Request Body

None

Permissions

Tableau Server administrators can call this method.

Response Code

200

Response Body

None

Version

Version 3.5 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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Decrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).

Decrypts all extracts on a site.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

URI

POST /api/api-version/sites/site-id/decrypt-extracts

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site.

Request Body

None

Permissions

Tableau Server administrators can call this method.

Response Code

200

Response Body

None

Version

Version 3.5 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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Reencrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).

Reencrypt all extracts on a site with new encryption keys. If no site is specified, extracts on the default site will be reencrypted.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

URI

POST /api/api-version/sites/site-id/reencrypt-extracts

Parameter Values

api-version The version of the API to use, such as 3.9. For more information, see REST API and Resource Versions.
site-id The ID of the site.

Request Body

None

Permissions

Tableau Server administrators can call this method.

Response Code

200

Response Body

None

Version

Version 3.5 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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.


Thanks for your feedback! There was an error submitting your feedback. Please try again.