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

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.20`. 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 a list of database connections found in the specified virtual connection and information about them.

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.20`. 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.

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

URI Parameter Values

api-version	The version of the API to use, such as `3.20`. 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`	(Optional) The new server for the database connection.
`connection serverPort`	(Optional) The new port for the database connection
`connection userName`	(Optional) The new username for the database connection.
`connection password`	(Optional) 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

Copy

<tsResponse>
  <virtualConnectionConnections>
    <connection 
      id="connection-id" 
      serverAddress="server-address" 
      serverPort="port-number"
      userName="connection-user-name"
      password="password"/>
  </virtualConnectionConnections>
</tsResponse>

Copy

{
  "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.

Thanks for your feedback!

Tableau REST API Help

Virtual Connections Methods

List Virtual Connections

URI

URI Parameter Values

Request Body

cURL Request Example

Response Code

Response Body

Errors

List Virtual Connection Database Connections

URI

URI Parameter Values

Request Body

cURL Request Example

Response Code

Response Body

Errors

Update Virtual Connection Database Connections

URI

URI Parameter Values

Request Body

Request Attributes

cURL Request Example

Response Code

Response Body

Errors