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

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.

VariableDescription
<TENANT>The hostname for the initial tenant created during account onboarding. Such as tenantname.region.qlikcloud.com.
<ACCESS_TOKEN>A bearer token for authorizing https requests to the <TENANT> tenant. Can be an API key, or a token generated via an OAuth client.
<SPACE_NAME>The name of the space you’ll create data connections in.
<SPACE_ID>The ID of the space <SPACE_NAME>.
<CONNECTION_ID>The ID for the data connection created in <SPACE_NAME>.
<CONNECTION_NAME>The ID for the data connection to be created in <SPACE_NAME>.
<CRED_USERNAME>A username for <CONNECTION_NAME>, for use with username and password authentication, or with certificate or OAuth when alternative credentials are provided in replacement of <CRED_PASSWORD>.
<CRED_PASSWORD>A password for <CONNECTION_NAME>, for use with username and password authentication.
<CRED_OAUTH>An OAuth code for <CONNECTION_NAME>, for use with interactive OAuth - must be copied from an interactive session.
<CRED_CERTIFICATE>A base64 encoded certificate or key file for <CONNECTION_NAME>, for use with cerficate or service account key file authentication.
<CRED_FINGERPRINT>The fingerprint for a public key (for example, SHA256:P8B+630peO/No+Ktb8irH0NdQkcWXwhBxYexd99bMiQ=).

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:

Data sourceData source ID
RESTrest
Microsoft SQL Servermssql
Databricksdatabricks
Google Big Querygbq
Amazon S3 Web Storage v1File_AmazonS3Connector
Amazon S3 Web Storage v2File_AmazonS3ConnectorV2
Amazon S3 Metadata v1AmazonS3Connector
Amazon S3 Metadata v2AmazonS3ConnectorV2
Google Cloud Storage Web StorageFile_GoogleCloudStorageConnector
Google Cloud Storage MetadataGoogleCloudStorageConnector
SFTPFile_FileTransferConnector
SFDCsfdc

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?

Was this page helpful?