DocsICP FilingConsole
Documentation

AddAgenticDataSource

Updated at:
Copy as MD
Product
My Favorites

Creates a data source accessible by the Agent data gateway.

Operation description

Enter the connection and authentication information for the data source. The connection is automatically tested before saving. If the test succeeds, the data source is created and metadata synchronization starts.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request syntax

POST  HTTP/1.1

Request parameters

Parameter

Type

Required

Description

Example
InstanceSource

string

Yes

The source of the data source. Valid values:

  • RDS: An ApsaraDB instance.

  • PUBLIC_OWN: A self-managed database on the Internet.

  • ECS_OWN: A self-managed database on an ECS instance.

  • GATEWAY: A database accessed through Database Gateway.

  • VPC_IDC: A database accessed through a VPC or data center.

RDS
InstanceResourceId

string

No

The ID of the cloud resource instance. This parameter is required when you select an existing cloud instance. You can leave this parameter empty when you enter an endpoint.

rm-bp1234567890
Alias

string

No

The display name of the data source. If you do not specify this parameter, the server generates a name.

demo_mysql
CatalogName

string

No

The name of the metadata catalog. If you do not specify this parameter, the name is automatically generated. The name can be up to 128 characters in length. It must start with a Chinese character, a letter, or an underscore, and can contain digits and hyphens. It cannot contain only digits.

demo_catalog
DbType

string

Yes

The type of the data source. Use uppercase letters. Do not pass numbers. Valid values: MYSQL, POSTGRESQL, ORACLE, SQLSERVER, MARIADB, POLARDB, POLARDB_POSTGRESQL, POLARDB_ORACLE, OCEANBASEX, DRDS, ADB_MYSQL, ADB_POSTGRESQL, CLICKHOUSE, SELECTDB, STARROCKS, HOLOGRES, MAXCOMPUTE, ES_REST, and TRINO.

MYSQL
Host

string

No

Optional. The domain name or IP address of the database. Do not include the protocol, path, or port. You can leave this parameter empty if you select an existing cloud instance and the address is automatically populated.

mysql.example.com
Port

integer

No

Optional. The service port of the database. You can leave this parameter empty if you select an existing cloud instance and the port is automatically populated.

3306
Schema

string

No

Optional. For ADB_POSTGRESQL, DRDS, POSTGRESQL, and POLARDB_POSTGRESQL, enter the database name. For ORACLE, enter the SID or service name, and prefix the service name with a forward slash (/). For POLARDB_ORACLE, enter the SID. For MAXCOMPUTE, enter the project name. Leave this parameter empty for other types.

postgres
SnowflakeWarehouse

string

No

The name of the Snowflake compute warehouse. This parameter takes effect only when DbType is set to SNOWFLAKE.

WAREHOUSE
SnowflakeRole

string

No

The name of the Snowflake role. This parameter takes effect only when DbType is set to SNOWFLAKE.

ROLE
AuthType

integer

No

Optional. The authentication type. Valid values:

  • -1: No authentication required.

  • 0: Username and password.

  • 1: Password only.

  • 2: Password-free.

0
AuthAccount

string

No

The logon username. You can leave this parameter empty for authentication methods that do not require a username.

db_user
AuthPassword

string

No

The logon password. This is sensitive information. Do not record or disclose it.

P@ss****
UseSsl

integer

No

Specifies whether to use SSL. Valid values:

  • 1: Enable.

  • 0: Disable.

  • -1: Use the default setting. Only ADB_MYSQL, CLICKHOUSE, MARIADB, MYSQL, OCEANBASEX, POLARDB, SELECTDB, and STARROCKS support SSL. Leave this parameter empty for other types.

1
RoleArn

string

No

The complete ARN of the Resource Access Management (RAM) role. Specify this parameter when you use a RAM role to access the data source. Leave this parameter empty in other scenarios.

acs:ram::123456789012****:role/DataSourceRole
KmsSecret

string

No

The name of the credential. Specify this parameter when you use Key Management Service (KMS) to manage database credentials. Leave this parameter empty in other scenarios.

datasource-secret
EnvType

string

No

The environment type. Valid values: product, pre, dev, test, sit, uat, pet, and stag.

product
SyncAlias

integer

No

Specifies whether to use the cloud instance name as the data source name. Valid values:

  • 1: Yes.

  • 0: No. This parameter takes effect only when you select a cloud database instance.

0
CreateMode

string

No

The entry method. Valid values:

  • INSTANCE_ID: Select an existing cloud instance.

  • HOST_PORT: Enter the endpoint and port. If you do not specify this parameter, HOST_PORT is used.

HOST_PORT
PolicyId

string

No

Optional. The ID of the data access security policy. This policy is used to control the access and protection rules for the data source.

sp-usr-example
VpcId

string

No

The ID of the destination VPC. Specify this parameter when you access MaxCompute through a VPC. Leave this parameter empty in other scenarios.

vpc-bp1234567890
ZoneId

string

No

The ID of the destination zone. Specify this parameter when you access MaxCompute through a VPC. Leave this parameter empty in other scenarios.

cn-hangzhou-h
VSwitchId

string

No

The ID of the destination vSwitch. Specify this parameter when you access MaxCompute through a VPC. Leave this parameter empty in other scenarios.

vsw-bp1234567890

Specify InstanceSource and DbType as required by the API model. Other parameters are optional based on the registration method.

Response elements

Element

Type

Description

Example

object

The response.

Data

object

The details of the created data source.

Alias

string

The display name of the data source.

demo_mysql
AuthAccount

string

The logon username for the data source. This parameter is empty if username authentication is not used.

db_user
AuthPassword

string

The masked value of the password or token. The actual value is not returned.

P@ss****
AuthType

integer

The authentication method. Valid values:

  • -1: no authentication required

  • 0: username and password

  • 1: password only

  • 2: password-free

0
CatalogName

string

The name of the metadata catalog associated with the data source.

demo_catalog
CreateMode

string

The registration method of the data source. Valid values:

  • INSTANCE_ID: select an existing cloud instance

  • HOST_PORT: register by endpoint and port

HOST_PORT
DataSourceUuid

string

The unique identifier of the data source.

cn-hangzhou_a1b2c3d4e5f6
DbType

string

The type of the data source. Valid values: MYSQL, POSTGRESQL, ORACLE, SQLSERVER, MARIADB, POLARDB, POLARDB_POSTGRESQL, POLARDB_ORACLE, OCEANBASEX, DRDS, ADB_MYSQL, ADB_POSTGRESQL, CLICKHOUSE, SELECTDB, STARROCKS, HOLOGRES, MAXCOMPUTE, ES_REST, and TRINO.

MYSQL
EnvType

string

The environment type. Valid values: product, pre, dev, test, sit, uat, pet, and stag.

product
GmtCreate

string

The time when the data source was created. The time is in the yyyy-MM-dd HH:mm:ss format.

2026-10-13 14:30:00
GmtModified

string

The time when the data source was last modified. The time is in the yyyy-MM-dd HH:mm:ss format.

2026-10-13 14:35:00
Host

string

The endpoint of the data source. A masked value may be returned in sensitive scenarios.

mysql.example.com
InstanceResourceId

string

The ID of the cloud resource instance. This parameter may be empty for data sources registered by endpoint.

rm-bp1234567890
InstanceSource

string

The source of the data source. Valid values:

  • RDS: An ApsaraDB instance.

  • PUBLIC_OWN: A self-managed database on the Internet.

  • ECS_OWN: A self-managed database on an ECS instance.

  • GATEWAY: A database accessed through Database Gateway.

  • VPC_IDC: A database accessed through a VPC or data center.

RDS
KmsSecret

string

The name of the KMS-managed credential. This parameter is empty if KMS is not used. This is sensitive information.

datasource-secret
PolicyId

string

The ID of the data access security policy in use. This parameter is empty if no policy is configured.

sp-usr-example
Port

integer

The connection port of the data source.

3306
RegionId

string

The region where the data source resides.

cn-hangzhou
ResourceAccountId

string

The ID of the Alibaba Cloud account to which the resource belongs.

123456789012****
RoleArn

string

The ARN of the RAM role used to access the data source. This parameter is empty if role authorization is not used.

acs:ram::123456789012****:role/DataSourceRole
Schema

string

The name of the connection target. For ADB_POSTGRESQL, DRDS, POSTGRESQL, and POLARDB_POSTGRESQL, this indicates the database name. For ORACLE, this indicates the SID or service name. For POLARDB_ORACLE, this indicates the SID. For MAXCOMPUTE, this indicates the project. For other types, this parameter is usually empty.

postgres
State

integer

The status of the data source. Valid values:

  • 0: normal

  • -1: deleted

  • -2: disabled

0
SyncAlias

integer

Indicates whether the cloud instance name is used as the data source name. Valid values:

  • 1: yes

  • 0: no

0
UseSsl

integer

The SSL settings. Valid values:

  • 1: enabled

  • 0: disabled

  • -1: default settings

1
ErrorCode

string

The error code returned when the call fails. This parameter is empty if the call is successful.

InvalidParameter
ErrorMessage

string

The error message returned when the call fails. This parameter is empty if the call is successful.

The parameter is invalid
RequestId

string

The request ID, which is used to trace the call.

request-1234567890
Success

boolean

Indicates whether the call was successful.

Returns the information about the created data source.

Examples

Success response

JSON format

{
  "Data": {
    "Alias": "demo_mysql",
    "AuthAccount": "db_user",
    "AuthPassword": "P@ss****",
    "AuthType": 0,
    "CatalogName": "demo_catalog",
    "CreateMode": "HOST_PORT",
    "DataSourceUuid": "cn-hangzhou_a1b2c3d4e5f6",
    "DbType": "MYSQL",
    "EnvType": "product",
    "GmtCreate": "2026-10-13 14:30:00",
    "GmtModified": "2026-10-13 14:35:00",
    "Host": "mysql.example.com",
    "InstanceResourceId": "rm-bp1234567890",
    "InstanceSource": "RDS",
    "KmsSecret": "datasource-secret",
    "PolicyId": "sp-usr-example",
    "Port": 3306,
    "RegionId": "cn-hangzhou",
    "ResourceAccountId": "123456789012****",
    "RoleArn": "acs:ram::123456789012****:role/DataSourceRole",
    "Schema": "postgres",
    "State": 0,
    "SyncAlias": 0,
    "UseSsl": 1
  },
  "ErrorCode": "InvalidParameter",
  "ErrorMessage": "参数不合法。",
  "RequestId": "request-1234567890",
  "Success": false
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.