REST API for Oracle Analytics Cloud

Update a connection

put

/api/20210901/catalog/connections/{connectionId}

Modify one or more properties of an existing connection in an Analytics instance. The PUT operation overwrites only the properties you include in the payload. Any connection properties you exclude from the payload remain unchanged. Username and Password are mandatory. The PUT operation doesn't allow you to change the connection type.

Request

Path Parameters

connectionId(required): string(byte)

The ID of the connection with Base64 encoding. For example, if your connection has the object ID 'user'.'connId', enter the Base64 encoded value, J3VzZXInLidjb25uSWQn

Supported Media Types

application/json

Root Schema : schema

Type: object

Response

200 Response

Successful operation.

400 Response

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

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).

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).

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"
    ]
}

404 Response

Not Found. The requested resource was not found.

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).

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.

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"
    ]
}

Examples

These examples show you how to update connection parameters for an existing connection to Oracle Autonomous Data Warehouse (ADW).

Example 1 - Update a wallet-less (TLS) connection to Oracle ADW
Example 2 - Update a connection to Oracle ADW that uses a credentials wallet file (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 Update a wallet-less (TLS) connection to ADW

In this example, you modify the username and password for an existing connection to Oracle ADW called oracle_adw_walletless. The object ID of the connection is 'admin'.'oracle_adw_walletless', which has the Base64 encoded connectionId value J2FkbWluJy4nb3JhY2xlX2Fkd193YWxsZXRsZXNzJw==. The request includes a simple JSON body (application/json).

cURL Example

First, determine the connectionId of the connection you want to update. When you create a connection, the connectionId is returned in the response body. If you didn't make a note of this, you can obtain the Object ID of the connection you want to update and Base64 encode this value to determine the connectionId. To obtain the Object ID, navigate to the Inspect Connection dialog in Oracle Analytics Cloud.

Next, include the connection properties you want to update in the request payload. For example, if you want to update the username and password, the payload looks like this.

{
  "version": "2.0.0", 
  "type": "connection", 
  "content": {   
  "connectionParams": {
        "username": "NEWADMIN",
        "password": "<<updated-password>>"   
        } 
   }
}

Run the cURL command with the JSON payload.

curl -i \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' a
  --request PUT 'https://<hostname>/api/20210901/catalog/connections/J2FkbWluJy4nb3JhY2xlX2Fkd193YWxsZXRsZXNzJw==' \
  --data "{  \
          "version": "2.0.0",    \
          "type": "connection",  \
          "content": {            \
            "connectionParams": {     \
              "username": "NEWADMIN",  \
              "password": "<<updated-password>>" \      
             }   
           }
       }"

Example of Response Header

Not applicable.

Example of Response Body

If successful, the response body returns the 200 response code. For example:

Status 200

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

In this example, you update a connection named oracle_adw_with_wallet with the object ID 'admin'.'oracle_adw_with_wallet'. The request body for this connection type can include multipart/form-data. You update the wallet file updated-cwallet.sso and you also modify the username and password parameters for the connection.

cURL Example

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

Base64 encode the connection's object ID value to determine the connectionId. In this example, the connectionId is: J2FkbWluJy4nb3JhY2xlX2Fkd193aXRoX3dhbGxldCc=

Next, include the connection properties you want to update in the request payload. If you want to update username and password, the payload looks like this.

{
  "version": "2.0.0", 
  "type": "connection", 
  "content": {   
  "connectionParams": {
        "username": "NEWADMIN",
        "password": "<<<updated-password>>>>",   
        } 
   }
}

Run the cURL command including the updated wallet file (updated-cwallet.sso) and the connection properties you want to update.

curl -i \
 --header 'Authorization: Bearer <token>' \
 --request PUT 'https://<hostname>/api/20210901/catalog/connections/J2FkbWluJy4nb3JhY2xlX2Fkd193aXRoX3dhbGxldCc=' \
 --form 'cert=@"/Users/admin/Downloads/Wallet_adw/updated-cwallet.sso"' \
 --form 'connectionParams="{     \
          "version": "2.0.0",    \
          "type": "connection",  \
          "content": {           \
          "connectionParams": {            \
             "username": "NEWADMIN",       \
             "password": "<<<<password>>>>" \
             } \
          }"'

Example of Response Header

Not applicable.

Example of Response Body

If successful, the response body returns the 200 response code. For example:

Status 200