API Connections Create v4

Release 6.8.2

Contents:

Expand all Collapse all

For the latest updates on available API endpoints and documentation, see api.trifacta.com.

This is the latest version of the APIs.

Contents:

Create the specified connection. For more information on connections, see Connection Types.

Version: v4

Required Permissions

NOTE: Each request to the Designer Cloud Powered by Trifacta® platform must include authentication credentials. See https://api.trifacta.com/ee/6.8/index.html#section/Authentication.

Request

Request Type: POST

Endpoint:

/v4/connections/

Request Body - Relational Connection:

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

NOTE: Relational connections require the creation and installation of an encryption key file on the Alteryx 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 credentials type. A valid username/password combination must be specified in the credentials property.

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

Property	Description
name	Display name of the connection
description	(Optional) Display description for the connection
vendorName	Set this value to the name of the vendor. For more information, see Connection Types.
type	For more information on the value to insert for the connection, see Connection Types.
isGlobal	(Optional) If `true`, the connection is available to all users. The default is `false`.
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	Set this value to the vendor value. For more information, 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.
ssl	(Optional) If set to `true`, the connection is made over SSL. The default is `false`. NOTE: If you connect over SSL, you must modify the hostname value to use HTTPS. 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. `aws` - AWS-specific credentials. Used for Redshift connections. `conf` - Use the connection credentials stored in `trifacta-conf.json`. `sshKey` - Use an SSH key as your password. Used for SFTP connections. `kerberosDelegate` - Connection uses the Kerberos-delegated principal to connect to the database. No credentials are submitted as part of the connection definition. This method requires additional configuration. See Enable SSO for Relational Connections. `kerberosImpersonation` - Connection uses the Kerberos impersonation principal for the user to connect to the database. No credentials are submitted as part of the connection definition. For more information, see Configure for Kerberos Integration. `azureTokenSso` - Connect to Azure-hosted resources using the Azure Single Sign On (SSO) token for the authenticating user. For more information, see Configure SSO for Azure AD.
credentialsShared	If the connection is a global connection, the credentials to connect can be shared with other users when this property is `true`. Otherwise, other users must provide their own credentials.
disableTypeInference	By default, the Designer Cloud Powered by Trifacta platform attempts to infer types when data is imported. For schematized sources, you may prefer to disable type inference, instead using the types provided by the source. When this setting is `true`, initial type inference by the platform is disabled for all data read through this connection.
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.

{
    "connectParams": {
        "vendor": "hive",
        "vendorName": "hive",
        "host": "hadoop",
        "port": "10000",
        "jdbc": "hive2",
        "defaultDatabase": "default"
    },
    "id": 1,
    "host": "hadoop",
    "port": 10000,
    "vendor": "hive",
    "params": {
        "jdbc": "hive2",
        "connectStringOptions": "",
        "defaultDatabase": "default"
    },
    "ssl": false,
    "vendorName": "hive",
    "name": "hive",
    "description": "Hive connection",
    "type": "jdbc",
    "isGlobal": true,
    "credentialType": "conf",
    "credentialsShared": true,
    "disableTypeInference": false,
    "credentials": []
}

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 Designer Cloud Powered by Trifacta platform is connected.
`port`	By default, this value should be `10000`.
`params`	Connection parameters for the Hive instance. NOTE: The following parameter entry is required for Hive: "jdbc": "hive2", Others are optional.
`type`	Set this value to `jdbc`.
`isGlobal`	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:

{
    "connectParams": {
        "vendor": "redshift",
        "vendorName": "redshift",
        "host": "redshift.example.com",
        "port": "5439",
        "defaultDatabase": "dev",
        "extraLoadParams": "BLANKSASNULL EMPTYASNULL TRIMBLANKS TRUNCATECOLUMNS"
    },
    "host": "redshift.example.com",
    "port": 5439,
    "vendor": "redshift",
    "params": {
        "connectStrOpts": "",
        "defaultDatabase": "dev",
        "extraLoadParams": "BLANKSASNULL EMPTYASNULL TRIMBLANKS TRUNCATECOLUMNS"
    },
    "ssl": false,
    "vendorName": "redshift",
    "name": "redshift2",
    "description": "Redshift connection",
    "type": "jdbc",
    "isGlobal": true,
    "credentialType": "custom",
    "credentialsShared": true,
    "disableTypeInference": false,
    "credentials": [
      {"key":"user","value":"<username>"},
      {"key":"password","value":"<password>"},
      {"key":"iamRoleArn","value":"<IAM_role_ARN>"}
  ]
}

The following property values are specific to Redshift connections.

Property	Description
`connectParams`	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. 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.

Request Body - Snowflake Connection:

{
  "vendor": "snowflake",
  "vendorName": "snowflake",
  "credentialType": "custom",
  "description": "",
  "host": "mysnowflakehost",
  "name": "snowflake",
  "type": "jdbc",
  "params": {
    "connectStrOpts": "",
    "warehouse": "LOAD_WH",
    "stage": "PUBLIC.MY_STAGE",
    "database": "DEFAULT_DB"
    "stageDatabase": "DB_STAGE",
  },
  "credentials": [
    {
      "key": "username",
      "value": "myuser"
    },
    {
      "key": "password",
      "value": "<my_pwd>"
    }
  ]
}

The following property values are specific to Snowflake connections.

NOTE: In Snowflake connections, property values are case-sensitive. Snowflake-related locations are typically specified in capital letters.

Property	Description
`vendor`	Set this value to `snowflake`.
`vendorName`	Set this value to `snowflake` .
`type`	Set this value to `jdbc`.
`params.warehouse`	Set this value to the Snowflake warehouse to use for this connection.
`params.stage`	(optional) If you are using a Snowflake stage, specify the value in the form of `SCHEMA.NAME` of the S3 bucket that is used for staging. Your stage database must include a schema named `PUBLIC`.
`params.database`	Set this value to the default Snowflake database to use for this connection.
`params.stageDatabase`	(optional) If you are using a Snowflake stage, you can optionally specify a database other than the default one to use for your stage. If no stage database is specified, then the default database is used to host the stage.
`credentials`	`username` and `password` must be specified in this key-value format, although the value for either can be an empty string.

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

Request Body - SFTP Connection:

{
    "connectParams": {
        "vendor": "sftp",
        "vendorName": "sftp",
        "host": "sftp.example.com",
        "port": "22"
    },
    "host": "sftp.example.com",
    "port": 22,
    "vendor": "sftp",
    "params": {},
    "ssl": false,
    "vendorName": "sftp",
    "name": "sftp",
    "description": "My SFTP connection",
    "type": "jdbc",
    "isGlobal": false,
    "credentialType": "sshKey",
    "credentialsShared": true,
    "disableTypeInference": false,
    "credentials": [
        {
            "username": "<my_username>",
            "sshkey": "<my_ssh_key>",

        }
    ]
    }
}

The following property values are import to SFTP connections.

Property	Description
`vendor`	Set this value to `sftp`.
`vendorName`	Set this value to `sftp`.
`type`	Set this value to `jdbc`.
`host`	Specify the host name. Do not include the `sftp://` protocol identifier.
`ssl`	For SFTP connections, set this value to `false`.
`credentialType`	Set this value to one of the following: `basic` - Username and password must be specified in the `credentials` section. `sshKey` - Username and SSH key must be specified in the `credentials` section.
`credentials`	(Basic credential type) `username` and `password` must be specified in key-value format, although the value for either can be an empty string. (SSH credential type) Username and SSH key must be specified in the key-value format shown above.

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

Response

Response Status Code - Success: 201 - Created

Response Body Example:

{
    "connectParams": {
        "vendor": "sqlserver",
        "vendorName": "sqlserver",
        "host": "sqlserver.example.com",
        "port": "1433"
    },
    "id": 26,
    "host": "sqlserver.example.com",
    "port": 1433,
    "vendor": "sqlserver",
    "params": {
        "connectStrOpts": ""
    },
    "ssl": false,
    "vendorName": "sqlserver",
    "name": "sqlserver_test2",
    "description": "",
    "type": "jdbc",
    "isGlobal": false,
    "credentialType": "basic",
    "credentialsShared": true,
    "uuid": "fa7e06c0-0143-11e8-8faf-27c0392328c5",
    "disableTypeInference": false,
    "createdAt": "2018-01-24T20:20:11.181Z",
    "updatedAt": "2018-01-24T20:20:11.181Z",
    "credentials": [
        {
            "username": "<username>"
        }
    ],
    "creator": {
        "id": 1
    },
    "updater": {
        "id": 1
    }
}

Reference

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

Send Feedback

Page tree

API Connections Create v4

Required Permissions

Request

Response

Reference