Virtual Connections Methods
Virtual connections are a centralized way to share access to databases and tables, allowing for convenient reuse. A virtual connection has one or more database connections, where server locations, database names, and credentials are defined. Each database connection accesses one database or file. Associated data policies provide security for workbooks, data sources, and flows that use virtual connections.
Using the virtual connections methods of the Tableau Server REST API you can:
- Get a list of virtual connections and details for each.
- Get and update the connection information for a virtual connection.
This functionality relates to the UI elements and concepts described at: Use a Virtual Connection(Link opens in a new window).
Add Tags to Virtual Connection
Adds tags to a virtual connection.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the View permission for the virtual connection and your site role must be at least Explorer. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-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-luid | The LUID for the site. |
virtualconnection-luid | The LUID for the virtual connection. |
Request Body
<tsRequest>
<tags>
<tag label="tag" />
<!-- ...additional tag elements... -->
</tags>
</tsRequest>
Attribute Values
tag | The text of the tag. |
cURL Request Example
curl --location --request PUT 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/tags' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
Contents of data.xml.
<tsRequest>
<tags>
<tag label="Office" />
<!-- ...additional tag elements... -->
</tags>
</tsRequest>
Response Code
200
Response Body
<tsResponse>
<tags>
<tag label="tag"/>
<!-- ...additional tags... -->
</tags>
</tsResponse>
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 | 400049 | Error adding tags | There was a problem adding tags to the specified virtual connection. |
403 | 403004 | Adding tags forbidden | The user doesn't have permissions to add tags to the virtual connection. |
404 | 404000 | Site not found | The site ID in the URI is not for an existing site. |
404 | 404006 | Virtual connection not found | The virtual connection ID in URI doesn't correspond to an existing virtual connection. |
404 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Add Virtual Connection Permissions
Adds permissions to the specified virtual connection for a user or group. You can specify multiple sets of permissions using one call.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
URI
PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions
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 virtual connection. |
virtualconnection‑id | The ID of the virtual connection to set permissions for. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<!-- ...additional granteeCapability sets... -->
</permissions>
</tsRequest>
Attribute Values
user-id | The LUID of the user to add permissions for. A request does not need to include both a user and a group grantee. |
group-id | The LUID of the group to add permissions for. A request does not need to include both a user and a group grantee. |
capability-name |
The capability to assign. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. For more information, see Permissions. |
capability-mode | Allow to allow the capability, or Deny to deny it. |
Permissions
You must be an administrator or have the ChangePermissions permission for the virtual connection (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:permissions:update
Response Code
200
Response Body
<tsResponse>
<permissions>
<virtualConnection id="virtualconnection-luid"
name="virtual-connection-name">
<owner id="user-luid"/>
</virtualConnection>
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-luid" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional granteeCapability sets ... -->
</permissions>
</tsResponse>
Version
Version 3.23 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 | 400009 | Invalid capability | The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. |
403 | 403004 | Permissions setting forbidden | The user tried to change permissions for a virtual connection but doesn't have the permission to change them. |
404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
404 | 404012 | Group not found | The group specified in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
404 | 404014 | Capability not found | A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
405 | 405000 | Invalid request method | Request type was not PUT. |
400 | 409004 | Invalid LUID | The virtual connection LUID in the URI was not found. |
For more information, see Handling Errors.
Example
curl --location --request PUT 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest>
<permissions>
<granteeCapabilities>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
<capabilities>
<capability name="read" mode="allow" />
</capabilities>
</granteeCapabilities>
</permissions>
</tsRequest>'
Delete Tag from Virtual Connection
Deletes a tag from a virtual connection.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the View permission for the virtual connection and your site role must be at least Explorer. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-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-luid | The LUID for the site. |
virtualconnection-luid | The LUID for the virtual connection. |
tag-name | The text of the tag. |
Request Body
None
cURL Request Example
curl --location --request DELETE 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/tags/office' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Response Code
204
Response Body
None
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400077 | Error deleting tag | There was a problem deleting the tag from the specified virtual connection. |
403 | 403004 | Deleting tags forbidden | The user doesn't have permissions to add delete tags from the virtual connection. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404004 | Virtual connection not found | The virtual connection ID in the URI doesn't correspond to an existing virtual connection. |
404 | 404007 | Tag not found | The tag in the URI doesn't exist for the specified virtual connection. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Delete Virtual Connection
Deletes a virtual connection.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the Delete permission for the virtual connection and your site role must be at least Creator. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
DELETE /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid
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. |
virtualconnection-luid | The LUID for the virtual connection. |
Request Body
None
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl --request DELETE 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Response Code
204
Response Body
None
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | User not authorized. | Check to make sure the user has the required permissions. |
404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
409 | 409122 | Generic error | An unknown error occurred. |
For more information, see Handling Errors.
Delete Virtual Connection Permission
Removes the specified virtual connection permission for the specified group or user.
URI
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/users/user-id/capability-name/capability-mode
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 virtual connection. |
virtualconnection‑id | The ID of the virtual connection to remove the permission for. |
group-id | The LUID of the group to remove the permission for. A request does not need to include both a user and a group grantee. |
user-id | The LUID of the user to remove the permission for. A request does not need to include both a user and a group grantee. |
capability-name |
The capability to remove the permission for. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. |
Request Body
None
Permissions
You must be an administrator or have the Delete permission for the virtual connection (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:permissions:delete
Response Code
204
Response Body
None
Version
Version 3.23 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. |
403 | 403004 | Permissions setting forbidden | The user tried to change permissions for a virtual connection but doesn't have the permission to change them. |
404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
404 | 404012 | Group not found | The group ID in the URI doesn't correspond to an existing group. |
404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
404 | 404014 | Capability not found | A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
400 | 409004 | Invalid LUID | The virtual connection LUID in the URI was not found. |
For more information, see Handling Errors.
Example
curl --location --request DELETE 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/read/allow' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Download Virtual Connection
Downloads a JSON-representation of a virtual connection.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the Overwrite permission for the virtual connection and your site role must be at least Creator. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
GET /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid
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. |
virtualconnection-luid | The LUID for the virtual connection. |
Request Body
None
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd" -X GET -H "Content-Type: application/xml" -H "X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"
Response Code
200
Response Body
<tsResponse>
<virtualConnection name="virtualconnection-name">
<project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"/>
<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
<content>virtualconnection-as-json</content>
</virtualConnection>
</tsResponse>
{
"virtualConnection": {
"project": {
"id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
},
"owner": {
"id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
},
"content": "virtualconnection-as-json",
"name": "virtualconnection-name"
}
}
The response body contains the project LUID, owner LUID, and a content element (for XML output) or content property (for JSON output) containing the virtual connection schema rendered as JSON.
If the response is XML, the content element is unescaped JSON.
If the response is JSON, the content property is escaped JSON.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400200 | Generic error | An unknown error occurred. |
403 | 403174 | User not authorized. | Check to make sure the user has the required permissions. |
404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
For more information, see Handling Errors.
Download Virtual Connection Revision
Downloads a JSON-representation of an earlier revision of a virtual connection.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the Overwrite permission for the virtual connection and your site role must be at least Creator. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
GET /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid/revisions/revision-number
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. |
virtualconnection-luid | The LUID for the virtual connection. |
revision-number | The revision number (revisionNumber) of the virtual connection, as returned by the Get Virtual Connection Revisions method. This is an integer, not a LUID. |
Request Body
None
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/revisions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Response Code
200
Response Body
<tsResponse>
<virtualConnection name="virtualconnection-name">
<project id="project-luid"/>
<owner id="owner-luid"/>
<content>virtualconnection-as-json</content>
</virtualConnection>
</tsResponse>
{
"virtualConnection": {
"project": {
"id": "project-luid"
},
"owner": {
"id": "owner-luid"
},
"content": "virtualconnection-as-json",
"name": "virtualconnection-name"
}
}
The response body contains the project LUID, owner LUID, and a content element (for XML output) or content property (for JSON output) containing the virtual connection schema rendered as JSON.
If the response is XML, the content element is unescaped JSON.
If the response is JSON, the content property is escaped JSON.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400200 | Generic error | An unknown error occurred. Check to make sure the revision number is a revision and not the active virtual connection. |
403 | 403174 | User not authorized. | Check to make sure the user has the required permissions. |
404 | 404049 | Virtual connection not found | Check the virtual connection LUID. Check that the revision number exists. |
For more information, see Handling Errors.
List Virtual Connection Revisions
Lists revisions for a virtual connection.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the Overwrite permission for the virtual connection and your site role must be at least Creator. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
Note: This method can only succeed 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-luid/virtualconnections/virtual-connection-luid/revisions
GET /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/revisions/?pageSize=page-size&pageNumber=page-number
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. |
virtual-connection-luid | The LUID for the virtual connection. |
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
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/revisions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3 '
Response Code
200
Response Body
<tsResponse>
<pagination pageNumber="page-number" pageSize="page-size" totalAvailable="page-count"/>
<revisions>
<revision revisionNumber="revision-number" publishedAt="datetime" deleted="deleted-flag" current="current-flag">
<publisher id="publisher-luid" name="publisher-username"/>
</revision>
<revision revisionNumber="revision-number" publishedAt="datetime" deleted="deleted-flag" current="current-flag">
<publisher id="publisher-luid" name="publisher-username"/>
</revision>
<!-- ...Additional revisions... -->
</revisions>
</tsResponse>
"pagination": {
"pageNumber": "page-number",
"pageSize": "page-size",
"totalAvailable": "page-count"
},
"revisions": {
"revision": [
{
"publisher": {
"id": "publisher-luid",
"name": "publisher-username"
},
"revisionNumber": "revision-number",
"publishedAt": "datetime",
"deleted": deleted-flag,
"current": current-flag
},
{
"publisher": {
"id": "publisher-luid",
"name": "publisher-username"
},
"revisionNumber": "revision-number",
"publishedAt": "datetime",
"deleted": deleted-flag,
"current": current-flag
},
{
...Additional revisions...
}
]
}
}
The current
property of a revision shows false
for all revisions except for the currently active virtual connection revision, in which case it shows true
.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400058 | Generic error | An unknown error occurred. |
403 | 403054 | User not authorized. | User doesn't have permissions to revisions on this virtual connection. Check the user's permissions. |
403 | 403173 | User not authorized. | User forbidden from listing virtual connection revisions. Check the user's permissions and site role. |
403 | 403053 | Revision history is disabled on the site. | Check the revision history setting. |
404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
For more information, see Handling Errors.
List Virtual Connections
Returns a list of available virtual connection names and IDs.
Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1) and later. Version Overview
License: Requires Tableau Data Management(Link opens in a new window).
Permissions: By default, all users can view virtual connections. Permissions Overview
JWT Access Scope: Not available.
URI
GET /api/api-version/sites/site-luid/virtualconnections
GET /api/api-version/sites/site-luid/virtualconnections/?pageSize=page-size&pageNumber=page-number
GET /api/api-version/sites/site-luid/virtualconnections/?filter=filter-expression
GET /api/api-version/sites/site-luid/virtualconnections/?sort=sort-expression
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 that contains the virtual connection. |
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 virtual connections to return. You can filter on predefined fields such as
name , tags , and createdAt . 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 virtual connection 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. |
Request Body
None
cURL Request Example
curl --location --request GET "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections" \ --header "X-Tableau-Auth: 3bl3fJb0T6qxhaCqneNhWg"Nmv6zrJfYeiiovCuEs2grrBAZlREbRGl"a946d998-2ead-4894-bb50-1054a91dcab3"
Response Code
200
Response Body
<tsResponse>
<pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available" />
<virtualConnections>
<virtualConnection
createdAt="datetime-created"
hasExtracts="has-extracts-flag"
id="virtual-connection-luid"
isCertified="is-certified-flag"
name="virtualconnection-name"
updatedAt="datetime-updated"
webpageUrl="web-page-url"/>
</virtualConnections>
</tsResponse>
{
"pagination": {
"pageNumber": "page-number",
"pageSize": "page-size",
"totalAvailable": "total-available"
},
"virtualConnections": {
"virtualConnection": {
"createdAt": "datetime-created",
"hasExtracts": "has-extracts-flag",
"id": "virtual-connection-luid",
"isCertified": "is-certified-flag",
"name": "virtualconnection-name",
"updatedAt": "datetime-updated",
"webpageUrl": "web-page-url"
}
}
}
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 | 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 virtual connections at the requested page size. |
400 | 400007 | Invalid page size | The page size parameter is not an integer, or is less than one. |
400 | 400008 | Invalid parameter value | A parameter in the request body is missing or invalid. |
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.
List Virtual Connection Database Connections
Returns information about database connections in the specified virtual connection
Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1) and later. Version Overview
License: Requires Tableau Data Management(Link opens in a new window).
Permissions: Users who are not administrators can query a virtual connection only if they have explicit or implicit [Connect] (view) permission for the virtual connection. Permissions Overview
JWT Access Scope: Not available.
URI
GET /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/connections
GET /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/connections?pageSize=page-size&pageNumber=page-number
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 that contains the virtual connection. |
virtual-connection-luid | The LUID for the virtual connection that includes the database connections. |
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
cURL Request Example
curl --location --request GET "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections/26bc30d8-90d6-4af1-922d-ac285e7b08fb/connections?X-Tableau-Auth =3bl3fJb0T6qxhaCqneNhWg"Nmv6zrJfYeiiovCuEs2grrBAZlREbRGl"a946d998-2ead-4894-bb50-1054a91dcab3"
Response Code
200
Response Body
<tsResponse>
<pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" />
<virtualConnectionConnections>
<connection
id="connection-id"
serverAddress="server-address"
dbClass="database-type"
serverPort="port-number"
userName="connection-user-name"/>
</virtualConnectionConnections>
</tsResponse>
{
"pagination": {
"pageNumber": "pageNumber",
"pageSize": "page-size",
"totalAvailable": "total-available"
},
"virtualConnectionConnections": {
"connection": {
"id": "connection-id",
"serverAddress": "server-address",
"dbClass": "database-type",
"serverPort": "port-number",
"userName": "connection-user-name"
}
}
}
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 virtual connections at the requested page size. |
400 | 400007 | Invalid page size | The page size parameter is not an integer, or is less than one. |
401 | 401002 | Unauthorized | The authentication token provided in the request header was invalid or has expired. |
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.
Publish Virtual Connection
Publishes a downloaded JSON-representation of a virtual connection.
If the virtual connection does not exist, it will be published as a new virtual connection. If it already exists, and you've chosen to overwrite it, the virtual connection will be published as a revision of the existing virtual connection.
The virtual connection can be published as a draft or as an active virtual connection.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the Overwrite permission for the virtual connection and your site role must be at least Creator. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
POST /api/api-version/sites/site-luid/virtualconnections
POST /api/api-version/sites/site-luid/virtualconnections?publishAsDraft=publish-as-draft-flag
POST /api/api-version/sites/site-luid/virtualconnections?overwrite=overwrite-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 for the site. |
publish-as-draft-flag |
(Optional, boolean) Defaults to true.
Note: The publishAsDraft URI parameter is case sensitive. If the virtual connection contains an extract, the publishAsDraft parameter value is ignored and the virtual connection is published as a draft. Note: If you are using the REST API to publish a virtual connection as a draft, note the virtual connection's LUID ( |
overwrite-flag |
(Optional, boolean) Defaults to false.
|
Request Body
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="virtualconnection-name"> <project id="project-luid"/> <owner id="owner-luid"/> <content>virtualconnection-as-json</content> </virtualConnection> </tsRequest>
(Use the icon in the top right corner to copy the text.)
{ "virtualConnection": { "project": { "id": "project-luid" }, "owner": { "id": "owner-luid" }, "content": "virtualconnection-as-json", "name": "virtualconnection-name" } }
Request Attributes
virtualconnection-name | The name of the virtual connection you are publishing. If publishing an existing virtual connection as a revision, the virtual connection name is ignored. |
project-luid | The LUID of the project you are publishing to. |
owner-luid |
This attribute is required, but is ignored. |
virtualconnection-as-json |
The virtual connection schema rendered as JSON, as obtained using the Download Virtual Connection or Download Virtual Connection Revision method. The schema appears in the content element (for XML output) or content property (for JSON output). Note: Changing the downloaded schema and then using it with this method isn't supported. When using the Publish Virtual Connection method, we recommend using the virtual connection schema format that matches the format you used for downloading it. This is important because the virtual connection schema returned by the download methods have escape characters in them if the output was JSON. If you download and publish using different formats, you will have to make changes to JSON representation of the virtual connection. In other words:
For more information on the difference between using XML and using JSON with the REST API, see Fundamentals of the Tableau Server REST API. |
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl --location 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections?overwrite=true&publishAsDraft=false' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
Content of data.xml:
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="Batters"> <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"/> <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/> <content>virtualconnection-as-json</content> </virtualConnection> </tsRequest>
Note: Replace virtualconnection-as-json content in the above example with the virtual connection schema you downloaded using the Download Virtual Connection method.
Response Code
201
Response Body
<tsResponse>
<virtualConnection id="virtualconnection-luid" name="virtualconnection-name">
<project id="project-luid"/>
</virtualConnection>
</tsResponse>
{
"virtualConnection": {
"project": {
"id": "project-luid"
},
"id": "virtualconnection-luid",
"name": "virtualconnection-name"
}
}
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400201 | Generic error | An unknown error occurred. |
403 | 403175 | User not authorized. | Check to make sure the user has the required permissions. |
For more information, see Handling Errors.
List Virtual Connection Permissions
Returns a list of permissions for a specific virtual connection.
URI
GET /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions
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 virtual connection. |
virtualconnection‑id | The ID of the virtual connection to get permissions for. |
Request Body
None
Permissions
You must be an administrator or have the Read (View) permission for the virtual connection (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:permissions:read
Response Code
200
Response Body
<tsResponse>
<permissions>
<parent id="project-luid"
type="Project"/>
<virtualConnection id="virtualconnection-luid"
name="virtualconnection-name">
<owner id="owner-luid"/>
</virtualConnection>
<granteeCapabilities>
<group id="group-luid"/>
<capabilities>
<capability name="capability-name"
mode="capability-mode"/>
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="user-luid"/>
<capabilities>
<capability name="capability-name"
mode="capability-mode"/>
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<!-- ...additional granteeCapability sets... -->
</permissions>
</tsResponse>
Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).
Version
Version 3.23 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404004 | Virtual Connection not found | The virtual connection ID in the URI doesn't correspond to an existing virtual connection. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl --location 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Update Virtual Connection
Updates a virtual connection's name, owner, project, or certification status.
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: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the Overwrite permission for the virtual connection and your site role must be at least Creator. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
PUT /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid
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. |
virtualconnection-luid | The LUID for the virtual connection. |
Request Body
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="virtualconnection-name" isCertified="certified-flag" certificationNote="certification-message"> <project id="project-luid"/> <owner id="owner-luid"/> </virtualConnection> </tsRequest>
(Use the icon in the top right corner to copy the text.)
{ "virtualConnection": { "name": "virtualconnection-name", "isCertified": "certified-flag", "certificationNote": "certification-message", "project": { "id": "project-luid" }, "owner": { "id": "owner-luid" } } }
Request Attributes
virtualconnection-name | The name of the virtual connection. |
certification-flag | Boolean. If true, the virtual connection is certified. If false, it won't. |
certification-message | The certification label's message. |
project-luid | The LUID of the project the virtual connection is located in. |
owner-luid |
The LUID of the user that owns the virtual connection. |
Request attributes that are different from the virtual connection's current properties result in updating the virtual connection.
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl --request PUT 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
Contents of data.xml.
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="Batters" isCertified="true" certificationNote="Approved by Marketing"> <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"/> <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/> </virtualConnection> </tsRequest>
Response Code
200
Response Body
<tsResponse>
<virtualConnection id="virtualconnection-luid"
isCertified="certified-flag"
name="virtualconnection-name">
<project id="project-luid"/>
<owner id="owner-luid"/>
</virtualConnection>
</tsResponse>
{
"virtualConnection": {
"project": {
"id": "project-luid"
},
"owner": {
"id": "owner-luid"
},
"id": "virtualconnection-luid",
"isCertified": certified-flag,
"name": "virtualconnection-luid"
}
}
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400203 | Generic error | An unknown error occurred. |
403 | 403004 | User not authorized to change virtual connection | Check to make sure the user has the required permissions. |
403 | 403176 | User not authorized to change virtual connection's owner | Check to make sure the user has the required permissions. |
403 | 403177 | User not authorized to move assets into the target project. | Check to make sure the user has the required permissions. |
403 | 403178 | User not authorized to move the virtual connection | Check to make sure the user has the required permissions. |
404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
409 | 409124 | A virtual connection with the chosen name already exists in the project. | Try a different virtual connection name. |
For more information, see Handling Errors.
Update Virtual Connection Database Connections
Updates the server address, port, username, or password for the specified database connection in a virtual connection.
Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1) and later. Version Overview
License: Requires Tableau Data Management(Link opens in a new window).
Permissions: Users who are administrators or have the site role of Creator or higher can update a database connection. Permissions Overview
JWT Access Scope: Not available.
URI
PUT /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/connections/connection-id/modify
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 that contains the virtual connection. |
virtual-connection-luid | The LUID for the virtual connection that includes the database connections. |
connection-id | The ID of the database connection. To determine what connections are in a virtual connection, call List Virtual Connection Database Connections(Link opens in a new window). |
Request Body
<tsRequest>
<connection
serverAddress="server-address"
serverPort="port-number"
userName="test"
password="password" />
</tsRequest>
{
"connection": {
"serverAddress": "server-address",
"serverPort": "port-number",
"userName": "test",
"password": "password"
}
}
Request Attributes
connection serverAddress
|
The new server for the database connection. |
connection serverPort
|
The new port for the database connection |
connection userName
|
The new username for the database connection. |
connection password
|
The new password for the database connection. |
cURL Request Example
curl --location --request PUT "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections/26bc30d8-90d6-4af1-922d-ac285e7b08fb/connections/26bc30d8-90d6-4af1-922d-ac285e7b08fb"
Response Code
200
Response Body
<tsResponse>
<virtualConnectionConnections>
<connection
id="connection-id"
serverAddress="server-address"
serverPort="port-number"
userName="connection-user-name"
password="password"/>
</virtualConnectionConnections>
</tsResponse>
{
"virtualConnectionConnections": {
"connection": {
"id": "connection-id",
"serverAddress": "server-address",
"serverPort": "port-number",
"userName": "connection-user-name",
"password": "password"
}
}
}
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 | The authentication token provided in the request header was invalid or has expired. |
403 | 403004 | Operation unauthorized | The user isn’t authorized to perform the task. |
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 PUT. |
For more information, see Handling Errors.