API Connections Create v3

D toc

Create the specified connection.

Info
NOTE: In this release, you cannot create SQL DW connections via the API. Please create these connections through the application. This known issue will be fixed in a future release.

For more information on connections, see CLI for Connections.

Version: v3

Required Permissions

D s api auth

Request

Request Type: POST

Endpoint:

Code Block
/v3/connections/

Request Body - Relational Connection:

For relational connections, the request body should look like the following. All properties are required unless noted.

Info

NOTE: Relational connections require the creation and installation of an encryption key file on the

D s item

item	node

. This file must be present before the connection is created. See Create Encryption Key File.

This example creates a SQL Server connection of basic type. A valid username/password combination must be specified in the credentials property.

Code Block

{
     "name": "sqlserver",
     "description": "",
     "isGlobal": false,
     "type": "jdbc",
     "host": "sqlserver.example.com",
     "port": 1433,
     "vendor": "sqlserver",
     "params": {
       "connectStrOpts": ""
     },
     "ssl": false,
     "credentialType": "basic",
     "credentials": [
        {
          "username": "<username>",
          "password": "<password>"
        }
     ]
}

Property Description

name Display name of the connection

description (Optional) Display description for the connection

isGlobal (Optional) If true, the connection is available to all users. The default is false.

type

For more information on the value to insert for the connection, see Connection Types.

host Host name of the relational server to which to connect.

port Port number for the relational server. The default value varies between database vendors. For more information, please see the documentation provided with your database distribution.

vendor

For more information on the value to insert for the connection, see Connection Types.

params (Optional) Set of JSON parameters that are passed to the database when initializing the connection. Depending on the database vendor, you may be required to submit via this parameter the name of the default database. You can also pass in optional parameters through the ConnecStrOpts parameter. For more information, see CLI for Connections.

ssl

(Optional) If set to true, the connection is made over SSL. The default is false.

Info
NOTE: If you connect over SSL, you must modify the hostname value to use HTTPS.

Info
NOTE: SSL connections to SQL Server are not supported.

credentialType

Set this value to one of the following:

basic - Simple username/password to be provided in the credentials property.
conf - Use the connection credentials stored in
D s triconf
.
custom - Connection credentials are specified in the params property, such as using key-value parameters to specify access credentials.

credentials (Optional) If credentialType=basic, this property must contain the username and password to use to connect to the relational source.

Request Body - Hive Connection:

You can create create only one public connection to Hive.

Code Block

{
  "host": "hadoop",
  "port": 10000,
  "vendor": "hive",
  "params": {
      "jdbc": "hive2",
      "connectStrOpts": "",
      "defaultDatabase": ""
  },
  "ssl": false,
  "name": "hiveAPI",
  "description": "Hive conn via API",
  "type": "jdbc",
  "isGlobal": true,
  "credentialType": "conf",
  "credentialsShared": true
}

The following property values are specific to Hive connections.

Property Description

host

Set this value to hadoop to integrate with the Hive instance for the Hadoop cluster to which the

D s platform

is connected.

params

Connection parameters for the Hive instance.

Info

NOTE: The following parameter entry is required for Hive:

Code Block
"jdbc": "hive2",

Others are optional.

type Set this value to jdbc.

isGlobal

Info
NOTE: For Hive connections, this value must be set to `true`.

credentialType Set this value to conf.

For more information, see Configure for Hive.

Request Body - Redshift Connection:

Code Block

{
  "host": "redshift.example.net",
  "port": 5439,
  "vendor": "redshift",
  "params": {
      "connectStrOpts": "",
      "defaultDatabase": "dev",
      "extraLoadParams": "BLANKSASNULL EMPTYASNULL TRIMBLANKS TRUNCATECOLUMNS"
  },
  "ssl": true,
  "name": "redshift",
  "description": "Redshiftconn",
  "type": "jdbc",
  "isGlobal": true,
  "credentialType": "custom",
  "credentialsShared": true,
  "credentials": [
    {"key":"user","value":"<userId>"},
    {"key":"password","value":"<PWD>"},
    {"key":"iamRoleArn","value":"<IAM_role_ARN>"}
  ]
}

The following property values are specific to Redshift connections.

Property Description

params

A default database value is required.

The extraLoadParams value is used when you publish results to Redshift. For more information on these values, see http://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html.

type Set this value to jdbc.

credentialType Set this value to custom. Credentials are specified below.

credentials

username and password must be specified in this key-value format, although the value for either can be an empty string.

Info
NOTE: `iamRoleArn` is optional. For more information, see Configure for EC2 Role-Based Authentication.

For more information on parameters and credentials, see Create Redshift Connections.

Response

Response Status Code - Success: 201 - Created

Response Body Example:

Code Block

{
    "connectString": "jdbc:sqlserver://sqlserver.example.com:1433",
    "id": 5,
    "host": "sqlserver.example.com",
    "port": 1433,
    "vendor": "sqlserver",
    "params": {
        "connectStrOpts": ""
    },
    "ssl": false,
    "name": "sqlserver",
    "description": "",
    "type": "jdbc",
    "createdBy": 1,
    "isGlobal": false,
    "credentialType": "basic",
    "createdAt": "2017-07-05T18:00:19.165Z",
    "updatedAt": "2017-07-05T18:00:19.165Z",
    "updatedBy": 1,
    "credentials": [
        {
            "username": "<username>"
        }
    ]
}

Reference

For more information on the response body properties, see API Connections Get v3.

Page tree

Versions Compared

Old Version 6

New Version Current

Key

Required Permissions

Request

Response

Reference