Create data connections

Overview

In this topic, you are going to learn how to create a new analytics data connection to common data sources. These can be used with Qlik Sense to create analytics within the Qlik Cloud platform.

Some analytics data connections can also be used with Qlik Cloud Data Integration. Learn more about this capability, supported data sources and more here.

Requirements

• You have an understanding of analytics data connections and their supporting APIs.
• cURL for running the inline examples.
• Appropriate space or tenant level role to delete the connection. Review space access control for more information on which permissions a user needs to create, modify, and access analytics data connections.

Note: The cURL examples in this tutorial show the command syntax for Windows Command Prompt. If you are using another command line interface, different syntax may be required for line continuation. You may also need to adjust the number and type of quotes surrounding the parameters and their values.

Variable substitution and vocabulary

Throughout this tutorial, variables will be used to communicate value placement. The variable substitution format is <VARIABLE_NAME>. Here is a list of variables referred to in this tutorial.

Construct connection properties

The parameters required to create a new data connection will differ depending on the data source. When creating a connection via API for the first time, you will need to look up the specification for the API to determine the properties you can send with the request.

Note: If you wish to copy connection properties from an existing data connection, you can retrieve this definition using the dcaas API. Review the update data connection topic to learn how to do this.

Identify the data source ID

Currently, only the creation of connections to data sources listed below are supported. To create a new connection, you must know the data source ID (listed as datasourceId), which is the internal identifier indicating the driver that Qlik Cloud should use to contact the data source.

Supported data sources and associated data source IDs:

Note: When creating new connections to Amazon S3, you should use the newer v2 drivers, File_AmazonS3ConnectorV2 and AmazonS3ConnectorV2. The v1 drivers remain supported for backwards compatibility reasons.

Retrieve data source properties

Using the datasourceId, you can retrieve the data source properties using the connection specification endpoint. To retrieve the specification for the File_AmazonS3ConnectorV2 connector:

curl -L 'https://<TENANT>/api/v1/dcaas/actions/data-connections/api-specs?dataSourceId=File_AmazonS3ConnectorV2' ^
-H 'Accept: application/json' ^
-H 'Authorization: Bearer <ACCESS_TOKEN>'

The response will contain all available properties, a description for each, and in some cases some example enumerations:

{
    "x-qlik-connector-provider": "QvWebConnectorPackage.exe",
    "x-qlik-connector-version": "4.37.1-26-g4784756",
    "connectionProperties": {
        "type": "object",
        "properties": {
            "accessKey": {
                "type": "string",
                "description": "Amazon S3 access key."
            },
            "secretKey": {
                "type": "string",
                "description": "Amazon S3 secret key."
            },
            "region": {
                "type": "string",
                "default": "us-east-1",
                "enum": [
                    "af-south-1",
                    "ap-east-1",
                    "ap-northeast-1",
                    "ap-northeast-2",
                    "ap-northeast-3",
                    "ap-south-1",
                    "ap-southeast-1",
                    "ap-southeast-2",
                    "ca-central-1",
                    "cn-north-1",
                    "cn-northwest-1",
                    "eu-central-1",
                    "eu-north-1",
                    "eu-south-1",
                    "eu-west-1",
                    "eu-west-2",
                    "eu-west-3",
                    "me-south-1",
                    "sa-east-1",
                    "us-east-1",
                    "us-east-2",
                    "us-west-1",
                    "us-west-2",
                    "us-gov-east-1",
                    "us-gov-west-1"
                ],
                "description": "Amazon S3 region code. (Default=us-east-1). (enum values are case sensitive)"
            },
            "bucketName": {
                "type": "string",
                "description": "The bucket name e.g. 'my-bucket'. You are strongly advised not to use sensitive naming for bucket names and object keys. GovCloud users should follow secure naming practices for buckets and object keys, to avoid using export-controlled and other sensitive data."
            }
        }
    }
}

From this response you can see that you are able to provide values for accessKey, secretKey, region, bucketName, and storeSseHeader. Which values you need to pass will vary depending on connector configuration and S3 bucket configuration.

Create data connection with non-interactive authentication

If you are using interactive OAuth for authentication, or you wish to use seperated credentials (where each user brings their own), you should review using interactive auth or seperated credentials with data connections.

This example creates a S3 v2 connection file connection to a bucket called bucket-name in AWS's us-east-1 region. The request includes the data source ID against which the connection will be created, File_AmazonS3ConnectorV2; the target space ID for the new connection; and the connection name and credentials.

curl -L 'https://<TENANT>/api/v1/dcaas/actions/data-connections' ^
-H 'Content-Type: application/json' ^
-H 'Authorization: Bearer <ACCESS_TOKEN>' ^
-d '{
    "dataSourceId": "File_AmazonS3ConnectorV2",
    "connectionName": "<CONNECTION_NAME>",
    "spaceId": "<SPACE_ID>",
    "connectionProperties": {
        "accessKey": "<CRED_USERNAME>",
        "secretKey": "<CRED_PASSWORD>",
        "region": "us-east-1",
        "bucketName": "bucket-name"
    }
}'

If successful, the system will return a http 201 created code and the newly created data connection:

{
    "dataSourceId": "File_AmazonS3ConnectorV2",
    "connectionId": "<CONNECTION_ID>",
    "connectionName": "<CONNECTION_NAME>",
    "userId": "6422bbf043af68ebe8abbb71",
    "tenantId": "Hj5p89bylz1r2AUC6joLNuHzVx5Ya8cF",
    "createdAt": "2023-08-10T10:49:56.914Z",
    "updatedAt": "2023-08-10T10:49:56.914Z",
    "tags": [],
    "credentialsId": "5d7deb43-2a41-4ed3-81f9-0d02c37d8a89",
    "spaceId": "<SPACE_ID>"
}

This response includes the new <CONNECTION_ID>, as well as the ID of the associated credentials, which is useful when using separated credentials.

Example creation requests

For sample connections for common configurations, visit examples.

Next steps

Now that you know how to create a data connection, why not look at how to update existing data connections?