Jump to

• Request
• Response
• Examples

Create a connection

post

/api/20210901/catalog/connections

Create a new connection for an Analytics instance.

Request

There are no request parameters for this operation.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation.

Body ()

Root Schema : CreateConnectionDetails

Type: object

Show Source

• connectionId(required): string
  The ID of the connection with Base64 encoding. To be used as a parameter when retrieving details, verifying, modifying or deleting this connection.

{
    "type":"object",
    "properties":{
        "connectionId":{
            "type":"string",
            "description":"The ID of the connection with Base64 encoding. To be used as a parameter when retrieving details, verifying, modifying or deleting this connection."
        }
    },
    "required":[
        "connectionId"
    ]
}

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

401 Response

Unauthorized (missing or expired credentials, and so on).

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

403 Response

Forbidden (missing permissions for operation, request denied for unspecified reason, and so on).

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

409 Response

Conflict (operation results in constraint violation, the operation is incompatible with the current state, and so on).

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Body ()

Root Schema : Error

Type: object

Show Source

• code(required): string
  Short error code that defines the error, meant for programmatic parsing.
• message(required): string
  Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

Back to Top

Examples

These examples show you how to create a connection to Oracle Autonomous Data Warehouse (ADW) from your Oracle Analytics instance.

• Example 1 - Create a wallet-less (TLS) connection to Oracle ADW
• Example 2 - Create a connection to Oracle ADW that uses a credentials wallet file cwallet.sso (Mutual TLS)

Note:

The JSON payload described in this topic is specific to Oracle ADW. The JSON payload format is different for other data sources. See Sample JSON Payloads for Supported Data Sources.

Example 1 Create a wallet-less (TLS) connection to ADW

In this example, you create a connection named oracle_adw_walletless. The request includes a simple JSON body (application/json).

cURL Example

First, create a JSON file that contains the properties required to create the connection. For example, create a JSON file called create_adw_walletless_connection.json that contains a payload that looks like this.

{
      "version": "2.0.0",
      "type": "connection",
      "name": "oracle_adw_walletless",
      "description": "Sample Oracle ADW connection without a wallet created using Connections API",
      "content": {    
        "connectionParams": {
           "connectionType": "oracle-autonomous-data-warehouse",
           "connectionString": "(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.us-ashburn-1.oraclecloud.com))(connect_data=(service_name=abcdefg1hijkl2m_adwwalletless_high.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes)))",
           "username": "ADMIN",
           "password": "<<password>>",
           "systemConnection": false,        
           "remoteData": false,
           "sslType": "ServerSideSSL"
       }
     }
}

Then run the cURL command calling the JSON file (for example, create_adw_walletless_connection.json):

curl -i \
 --header 'Authorization: Bearer <token>' \
 --header 'Content-Type: application/json' \
 --request POST 'https://<hostname>/api/20210901/catalog/connections' \
 --data @create_adw_walletless_connection.json

Example of Response Header

Not applicable.

Example of Response Body

Make a note of the Base64 encoded connectionId in the response body. Later on, you can use this value to update or delete this connection.

{"connectionID":"J0FkbWluJy4nb3JhY2xlX2Fkd193YWxsZXRsZXNzJw=="}

Example 2 Create a connection to ADW that uses a wallet file (Mutual TLS)

In this example, you create a connection named oracle_adw_with_wallet. The request body includes multipart/form-data, that is, requires both a wallet file cwallet.sso and ADW connection parameters.

cURL Example

Obtain the credentials wallet file from Oracle Autonomous Data Warehouse. See Download Client Credentials (Wallets).

Determine the properties required to create the connection. The payload looks like this.

{
    "version": "2.0.0",
    "type": "connection",
    "name": "oracle_adw_with_wallet",
    "description":
      "Sample Oracle ADW connection with a wallet created using Connections API",   
      "content": {
       "connectionParams": {
         "connectionType": "oracle-autonomous-data-warehouse",
         "connectionString": "(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps) (port=1522)(host=adb.us-ashburn-1.oraclecloud.com))(connect_data=(service_name=abcdefg1hijkl2m_walletadw_high.adwc.oraclecloud.com/))(security=(ssl_server_dn_match=yes)))",
         "username": "ADMIN",
         "password": "<<password>>",
         "remoteData": "false",   
         "systemConnection": false,
         "sslType": "ClientSideSSL"    
        }
      }
 }

Run the cURL command including the wallet file (cwallet.sso) and the connection properties.

curl -i \
 --header 'Authorization: Bearer <token>' \
 --request POST 'https://<hostname>/api/20210901/catalog/connections'  \
 --form 'cert=@"/Users/scott/Downloads/Wallet_adw/cwallet.sso"'        \
 --form 'connectionParams= "{ \
    "version": "2.0.0",       \
    "type": "connection",     \
    "name": "oracle_adw_with_wallet", \
    "description":  \
      "Sample Oracle ADW connection with a wallet created using Connections API",  \
      "content": {   \
       "connectionParams": { \
         "connectionType": "oracle-autonomous-data-warehouse",\
         "connectionString": "(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps) (port=1522)(host=adb.us-ashburn-1.oraclecloud.com))(connect_data=(service_name=abcdefg1hijkl2m_walletadw_high.adwc.oraclecloud.com/))(security=(ssl_server_dn_match=yes)))", \
         "username": "ADMIN", \
         "password": "<<password>>", \
         "remoteData": "false",      \
         "systemConnection": false,  \
         "sslType": "ClientSideSSL"  \  
      }
   }
 }'

Example of Response Header

Not applicable.

Example of Response Body

Make a note of the Base64 encoded connectionId in the response body. Later on, you can use this value to update or delete this connection.

{"connectionID":"J2FkbWluJy4nb3JhY2xlX2Fkd193aXRoX3dhbGxldCc="}

Back to Top