Using VizQL Data Service with Postman

🕐 7 min read

• Step 1: Set up your authentication method
• Step 2: Get the Postman collection and environment files
• Step 3: Import Postman collection and environment files
• Step 4: Configure your environment variables
• Step 5: Run a sample VDS query

Postman is a popular collaboration platform for application programming interface (API) development. It provides tools for designing, testing, and managing APIs, making it easier for you to work with and understand the functionality of APIs.

Postman provides a way for you to import and use the VizQL Data Service (VDS) collection of methods, along with the environment variables needed to send a request.

To use VDS with Postman, perform the following steps.

Step 1: Set up your authentication method

If you haven’t already done so, create either a personal access token or a connected app. For more information, see Authentication.

Step 2: Get the Postman collection and environment files

Go to the VizQL Data Service API Postman Collection GitHub repository and download the following files:

• VizQL Data Service (Dev Preview).postman_collection.json: This file contains the collection of VDS methods. It has the main request (query-datasource), a way to get information about your datasource (read-metadata), and a health check (simple-request).
• VizQL Data Service Environment (Dev Preview).postman_environment.json: This is the VDS environment. It contains all the variables you must modify (for example, credentials, cloud site, and datasource) to use the VDS methods.

Step 3: Import Postman collection and environment files

1. Create a Postman account. If you already have a Postman account, skip this step.

2. Sign in to your Postman account.

3. Import the JSON files you downloaded in Step 1.

   • In Postman, select Import in the sidebar.
   • Choose the JSON files you downloaded in the previous step and select Import. This uploads the JSON files to your Postman workspace.

Step 4: Configure your environment variables

1. In the Postman sidebar, click Environments. This action displays all the variables you use for VDS.

2. Update the following variables. Enter information for either your PAT or your JWT where noted.

   Tip: The JWT variables noted in the following table are required unless you use a PAT or enter the JWT directly in the credential-jwt header. We recommend that you use the JWT variables rather than the header directly because Postman automatically generates the JWT for you with each request.

   Variable	Description
   tableau-server-name	The URL of your cloud host. For example, 10ax.online.tableau.com.
   site-id	The name of your site. This is the human readable site name as you see in the URL and not site LUID. For example, vizqldataserviceapipreview.
   credential-key	(Only required for PAT) The name of the PAT you created earlier in Tableau Cloud. For example, token-for-vds.
   credential-value	(Only required for PAT) The value of your PAT, which you can get in Tableau by going to My Account Settings > Personal Access Tokens, choosing the token, and selecting Copy Secret.
   datasource	The data source name. See Get Data Source Information for more. The default is SuperstoreDatasource.
   tableau-username	(Only required for JWT) This is your Tableau Cloud username.
   connected-app-client-id	(Only required for JWT) Your Tableau Cloud site’s connected app client ID. Get or create it and the following values by clicking Settings, then Connected Apps on your Tableau Cloud site.
   connected-app-secret-id	(Only required for JWT) This is your Tableau Cloud site’s connected app secret ID.
   connected-app-secret-value	(Only required for JWT) This is your Tableau Cloud site’s connected app secret value.
   credential-jwt	An alternative to using connected apps is to generate the JWT yourself. When generating your own JWT, ensure that the JWT contains the scope tableau:viz_data_service:read. Place your generated JWT as the value for this variable to authenticate.

3. Select Save.
4. In the sidebar, set the environment to be active.

Step 5: Run a sample VDS query

Run the following query to verify that your environment is configured correctly.

1. In the Collections area, click the dropdown next to query-datasource. This shows you all of the example queries.

2. Choose simple-query. This query contains a connection object, which contains the environment variables you specified in the current selected environment, a list of columns, and some metadata.

   {
    "connection": {
      "tableauServerName": "",
      "protocol": "",
      "siteId": "",
      "datasource": ""
    },
    "query": {
      "columns": [
          {
              "columnName": "Category",
              "sortPriority": 1
          },
          {
              "columnName": "Sub-Category",
              "sortPriority": 2
          },
          {
              "columnName": "Product Name (group)",
              "sortPriority": 3
          },
          {
              "columnName": "Product Name",
              "sortPriority": 4
          },
          {
              "columnName": "Sales",
              "function": "AVG",
              "maxDecimalPlaces": 3
          }
      ],
      "metadata": {
          "returnFormat": "OBJECTS"
      }
    }
   }
   

3. Select Send the request to get back the response data.

If your response contains data, you’re ready to create your own queries.

If you received an error, check that your environment variables are correct and that the cloud site you’re trying to access is up and running. Then try sending the request again.