创建数据源

在 NineData 中创建一个新的数据源连接配置。

请求地址：/openapi/v1/datasource/create

请求方法：POST

请求参数

参数	类型	是否必选	说明	示例
datasourceType	String	是	数据源类型。必须传入下表中的枚举值；具体值是否可用取决于目标 NineData 环境当前启用的类型。	mysql
name	String	是	指定数据源名称。	示例 MongoDB
username	String	条件必填	使用数据库账号认证时必填；具体要求取决于数据源类型和认证方式。	<username>
password	String	条件必填	使用数据库账号认证时必填；具体要求与 username 相同。	<password>
host	String	条件必填	使用连接地址接入时必填；云数据源通过实例 ID 接入时使用 instanceId，不传 host。	<DB_HOST>
port	Integer	条件必填	使用 host 接入且目标类型需要端口时必填；实例 ID、URL 或多节点 hostAndPorts 模式按对应字段传入。	27017
envId	String	否	所属环境。可通过查询环境信息获取。	<envId>
regionId	String	否	为该数据源指定所属地域。您需要调用查询地区信息接口获取 regionId。	<regionId>
networkType	String	条件必填	连接方式。取值：public、gateway、ssh、private；与 gatewayId、tunnelId、sshConfig 联动。	public
masterName	String	否	主节点名称，适用于包含主节点的数据源。	master-1
hostAndPorts	String	否	逗号分隔的多节点 host:port 组合，例如 Redis Sentinel 或 Cluster。	host1:port1,host2:port2
instanceId	String	条件必填	选择云数据源实例 ID 接入时必填；该模式下使用实例 ID，不传 host 和 port。	<instanceId>
instanceType	String	条件必填	使用云数据源实例接入时必填，用于指定云实例类型。	RDS
cloudInstanceType	String	条件必填	使用云数据源时必填，用于指定实例 ID 或连接地址等接入模式。	instance
vendorRegionId	String	条件必填	使用云数据源时必填，用于指定云厂商地域。	cn-hangzhou
serverVersion	String	否	数据库服务版本。	8.0
gatewayId	String	条件必填	networkType 为 gateway 时必填。	<gatewayId>
tunnelId	String	条件必填	networkType 为 private 时必填，用于指定私网连接。	<tunnelId>
accessId	String	条件必填	使用云数据源时必填，用于指定云厂商访问凭证。	<accessId>
env	String	否	环境标识，由请求参数决定。	<environment>
sshConfig	Object	条件必填	networkType 为 ssh 时必填，用于指定 SSH 连接配置。字段结构见 SSHConfig 结构。	{}
sslConfig	Object	否	SSL 加密传输配置。支持的字段和数据源类型见 SSLConfig 结构。	{"securityConfig":"REQUIRED"}
extraConfig	Object	否	数据源专属配置。不同类型数据源的专有参数放在该对象中，详见下文。	{"authDB":"admin"}

参数必填规则

是否必选列说明通用请求要求；实际请求还要根据 datasourceType、networkType 和接入模式组合字段。请仅传入当前场景需要的字段：

场景	必填字段或传参规则
所有创建请求	datasourceType、name。datasourceType 还必须是目标 NineData 环境当前启用的枚举值。
使用连接地址接入	host 必填；目标数据源需要端口时，port 必填。使用 URL 或多节点地址时，按数据源类型传入 host、hostAndPorts 等对应字段。
使用云数据源实例 ID 接入	accessId、vendorRegionId、instanceType、cloudInstanceType、instanceId 必填；该模式不传 host 和 port。
使用数据库账号认证	username、password 同时必填。若目标数据源的认证方式不需要数据库账号密码，则按该数据源类型的要求省略。
networkType=gateway	gatewayId 必填。
networkType=private	tunnelId 必填。
networkType=ssh	sshConfig 必填。
需要指定环境或接入地域	传入 envId 或 regionId。当前控制台创建数据源表单会要求选择环境和接入地域；使用 API 时请按目标环境的接口校验结果传入。

未触发条件的字段不要使用空字符串代替，也不要同时传入互斥的接入字段。例如，使用 instanceId 接入时不要再传 host 和 port；使用 gateway、private 或 ssh 时，分别只传对应的连接配置。

datasourceType 支持的枚举值如下：

数据源	datasourceType
MySQL	mysql
SQL Server	sqlserver
Oracle	oracle
PostgreSQL	postgresql
ClickHouse	clickhouse
Elasticsearch	elasticsearch
OpenSearch	opensearch
Trino	trino
ShardingJDBC	sharding_jdbc
ShardingProxy	sharding_proxy
Kafka	kafka
Redis	redis
MongoDB	mongodb
Doris	doris
SelectDB	selectdb
StarRocks	starrocks
OceanBase Oracle	oceanbaseoracle
OceanBase MySQL	oceanbasemysql
Amazon Redshift	redshift
Greenplum	greenplum
YMatrix	ymatrix
DB2	db2
SingleStore	singlestore
Klustron	klustron
Kingbase	kingbase
Kingbase Oracle	kingbaseoracle
Dameng（达梦）	dameng
DWS	dws
Hive	hive
ADB PostgreSQL	adbpostgresql
openGauss	opengauss
GaussDB	gaussdb
PanWeiDB	panweidb
GBase	gbase
GBase 8a	gbase8a
TiDB	tidb
Sybase	sybase
GreatSQL	greatsql
TDSQL MySQL	tdsqlmysql
TDSQL Oracle	tdsqloracle
DataHub	datahub
ElastiCache	elasticache
VectorDB	vectordb
VastBase	vastbase
Lindorm MySQL	lindormmysql
GoldenDB	goldendb
PegaDB	pega
Milvus	milvus
Chroma	chroma
Qdrant	qdrant
Pinecone	pinecone
Weaviate	weaviate
MariaDB	mariadb
PolarDB Oracle	polardboracle
PolarDB-X	polardbx
PolarDB-X Centralized	polardbxcentralized
DRDS	drds
SQL Database	sqldatabase
Memorystore	memorystore
HANA	hana
YashanDB	yashandb
YashanDB MySQL	yashandbmysql
MaxCompute	maxcompute
HaishanDB	haishandb

可用的数据源类型随版本和部署环境而异。传入目标环境未启用的值时，接口返回 INVALID_PARAMETER。

数据源类型与 extraConfig 明细

datasourceType 决定 extraConfig 中可使用的专有字段。下表列出参考附录中已确认的映射；— 表示该类型没有专有 extraConfig 字段。具体类型是否可用，以目标 NineData 环境当前启用的类型为准。

数据源类型（datasourceType）	extraConfig 专有字段
MySQL（mysql）	mysqlConnectionType
Oracle（oracle）	serviceName、sid、role
PostgreSQL（postgresql）	authDB、clientTimezone
Kafka（kafka）	kafkaAuthorization
Redis（redis）	redisDeploymentType；哨兵模式的 masterName 是顶层字段，不属于 extraConfig
MongoDB（mongodb）	mongoDBDeploymentType、authDB、readPreference、serverSelectionTimeoutMS、cluster
Doris（doris）、SelectDB（selectdb）、StarRocks（starrocks）	dorisUserBeHostPorts
OceanBase Oracle（oceanbaseoracle）	serviceName、sid、sysTenantUsername、sysTenantPassword
OceanBase MySQL（oceanbasemysql）	mysqlConnectionType、sysTenantUsername、sysTenantPassword
Amazon Redshift（redshift）	authDB
Greenplum（greenplum）	authDB
DB2（db2）	dbName
GaussDB（gaussdb）	gaussDBInstanceType、gaussDBBigVersion
GBase（gbase）	serverName
GBase 8a（gbase8a）	connectionType、host
MariaDB（mariadb）	mysqlConnectionType
PolarDB Oracle（polardboracle）	clientTimezone
PolarDB-X（polardbx）	mysqlConnectionType、clientTimezone
PolarDB-X Centralized（polardbxcentralized）	mysqlConnectionType
DRDS（drds）	mysqlConnectionType
Memorystore（memorystore）	redisDeploymentType
HANA（hana）	databaseName
YashanDB（yashandb）	serviceName、sid
Hive（hive）	hadoopAuthConfig
其他当前支持类型	—；按顶层字段和目标环境接口校验结果传参

补充说明：当前环境的 GET /openapi/v1/datasource/list 只读响应中，部分类型还会返回版本或类型专属字段，例如 useCompression、beHostsEnable、dorisMapping；SSL 响应中还可能出现 tlsAllowInvalidCertificates、tlsAllowInvalidHostnames、tlsInsecure。这些字段属于响应扩展，不纳入本文通用创建请求字段清单；如需传入创建接口，请先以目标环境的接口定义为准。

extraConfig 对象结构

extraConfig 是 JSON Object，键名区分大小写。创建数据源时按 datasourceType 传入对应的专有字段。

参数	类型	是否必选	说明
clientTimezone	String	否	客户端时区，例如 +08:00 或 -05:00。
mysqlConnectionType	String	否	MySQL 连接方式。可选值： single：单机直连，写法为 <DB_HOST> + port。 failover：MySQL 容灾连接，自动切换可用节点，写法为 <HOST_1>:<PORT_1>,<HOST_2>:<PORT_2>。 replication：MySQL 读写分离连接，写法为 <HOST_1>:<PORT_1>,<HOST_2>:<PORT_2>。
mongoDBDeploymentType	String	否	MongoDB 部署方式。取值：standalone、replicaSet、shardedCluster，默认 standalone。
authDB	String	条件必填	MongoDB 的认证库；PostgreSQL、Greenplum、Amazon Redshift 的默认数据库。MongoDB 创建时必填。
readPreference	String	否	MongoDB 读偏好。取值：primary、primaryPreferred、secondary、secondaryPreferred、nearest、default。
serverSelectionTimeoutMS	Integer	否	MongoDB 服务选择超时时间，默认 10000。
redisDeploymentType	String	否	Redis 部署方式。取值：single、sentinel、cluster。
kafkaAuthorization	String	否	Kafka 认证方式。取值：PLAINTEXT、SASL/PLAIN、SASL/SCRAM-SHA-256、SASL/SCRAM-SHA-512。
serviceName	String	条件必填	Oracle 服务名。与 sid 二选一。
sid	String	条件必填	Oracle SID。与 serviceName 二选一。
role	String	否	Oracle 权限角色。取值：SYSDBA、SYSOPER、default。
dbName	String	是	DB2 数据库名。
databaseName	String	否	数据库名，适用于需要在 extraConfig 中指定数据库名的数据源。
gaussDBInstanceType	String	否	GaussDB 实例类型。取值：centralized、distributed。
gaussDBBigVersion	String	否	GaussDB 大版本。取值：GaussDB 8.x、GaussDB 3.x。
serverName	String	否	GBase 服务名，默认 gbaseserver。
clientCharset	String	否	客户端字符集。
connectionType	String	否	GBase 8a 连接方式。取值：standalone、multi，兼容旧值 single；主从模式必填。
host	String	否	GBase 8a connectionType=multi 时的备节点地址，多个地址使用分号（;）分隔。
sysTenantUsername	String	条件必填	OceanBase 系统租户账号。
sysTenantPassword	String	条件必填	OceanBase 系统租户密码。
dorisUserBeHostPorts	Array	否	Doris、SelectDB 或 StarRocks 的 BE 节点列表。元素结构为 {"host":"<BE_HOST>","port":"8040"}。
hadoopAuthConfig	Object	条件必填	Hive 认证配置。authMethod=KERBEROS 时，在该对象中传入 Kerberos 认证信息，顶层 username、password 可不传。
cluster	Object	否	MongoDB 集群拓扑。包含 clusterId 和必填的 nodeList，结构见下文。

Redis 和 Kafka 的特殊规则：

• redisDeploymentType=sentinel 时，顶层 masterName 必填，host 传哨兵节点地址列表。
• redisDeploymentType=cluster 时，host 传集群节点地址列表，port 可以不传。
• kafkaAuthorization 为 SASL/PLAIN、SASL/SCRAM-SHA-256 或 SASL/SCRAM-SHA-512 时，顶层 username、password 用作 Kafka 认证账号密码；取值为 PLAINTEXT 或不传时，可以不传顶层账号密码。

extraConfig.cluster 结构

参数	类型	是否必选	说明
clusterId	String	否	集群 ID。
nodeList	Array	是	集群节点列表。

nodeList 元素结构如下：

参数	类型	是否必选	说明
nodeId	String	否	节点 ID。
nodeHost	String	是	节点地址。
nodePort	Integer	是	节点端口。
connectHost	String	否	可连接地址，缺省使用 nodeHost。
connectPort	Integer	否	可连接端口，缺省使用 nodePort。
username	String	否	节点账号。

SSLConfig 结构

sslConfig 用于配置 SSL 加密传输。当前附录确认 MySQL、SQLServer、PostgreSQL 支持该对象；不同数据源类型支持的字段不同。证书和私钥字段应传入文件内容及对应文件名，示例中的证书内容均为占位符。

参数	类型	是否必选	适用数据源	说明
securityConfig	String	否	MySQL、PostgreSQL	SSL 安全模式。MySQL 取值：REQUIRED、PREFERRED；PostgreSQL 取值：Prefer、Require、Verify-CA、Verify-Full。
sslCipher	String	否	MySQL	加密套件。
sslCA	String	否	MySQL、SQLServer、PostgreSQL	CA 证书内容。
sslCAFileName	String	否	MySQL、SQLServer、PostgreSQL	CA 证书文件名。
sslClientCert	String	否	MySQL、PostgreSQL	客户端证书内容。
sslClientCertFileName	String	否	MySQL、PostgreSQL	客户端证书文件名。
sslClientKey	String	否	MySQL、PostgreSQL	客户端私钥内容。
sslClientKeyFileName	String	否	MySQL、PostgreSQL	客户端私钥文件名。
sslIndentify	Boolean	否	MySQL	是否校验服务器身份。字段名必须使用接口定义的 sslIndentify。
hostNameInCertificate	String	否	SQLServer	服务器证书中的主机名。
trustServerCertificate	Boolean	否	SQLServer	是否信任服务器证书。

MySQL SSL 配置示例：

{
  "sslConfig": {
    "securityConfig": "REQUIRED",
    "sslIndentify": true,
    "sslCA": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----",
    "sslCAFileName": "ca.pem",
    "sslClientCert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----",
    "sslClientCertFileName": "client-cert.pem",
    "sslClientKey": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----",
    "sslClientKeyFileName": "client-key.pem"
  }
}

SQLServer SSL 配置示例：

{
  "sslConfig": {
    "hostNameInCertificate": "db.example.com",
    "trustServerCertificate": false,
    "sslCA": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----",
    "sslCAFileName": "ca.pem"
  }
}

PostgreSQL SSL 配置示例：

{
  "sslConfig": {
    "securityConfig": "Verify-Full",
    "sslCA": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----",
    "sslCAFileName": "root.crt",
    "sslClientCert": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----",
    "sslClientCertFileName": "client.crt",
    "sslClientKey": "-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----",
    "sslClientKeyFileName": "client.key"
  }
}

SSHConfig 结构

当 networkType=ssh 时，在顶层 sshConfig 中传入 SSH 隧道配置。sshAuthType 取 password 时，sshPassword 必填；取 privateKey 时，sshPrivateKey 必填。

参数	类型	是否必选	说明
sshHost	String	是	SSH 主机。
sshPort	Integer	否	SSH 端口，默认 22。
sshUsername	String	是	SSH 用户名。
sshAuthType	String	否	SSH 认证方式。取值：password、privateKey。
sshPassword	String	条件必填	sshAuthType=password 时必填，表示 SSH 密码。
sshPrivateKey	String	条件必填	sshAuthType=privateKey 时必填，表示 SSH 私钥内容。
sshPrivateKeyFileName	String	否	SSH 私钥文件名。
sshPassphrase	String	否	SSH 私钥口令。未设置口令时留空。
jumpServerList	Array	否	跳板机列表，元素结构与本对象相同。

SSH 私钥认证示例：

{
  "networkType": "ssh",
  "sshConfig": {
    "sshHost": "<SSH_HOST>",
    "sshPort": 22,
    "sshUsername": "<SSH_USERNAME>",
    "sshAuthType": "privateKey",
    "sshPrivateKey": "<SSH_PRIVATE_KEY>",
    "sshPrivateKeyFileName": "id_rsa",
    "sshPassphrase": "<SSH_PASSPHRASE>"
  }
}

账号和密码必填条件

username 和 password 是数据库或数据源认证账号密码；SSH 账号密码应放在 sshConfig 中。创建请求需要根据数据源类型和认证方式传入：

场景	username/password 必填条件
MySQL、MariaDB、TiDB、OceanBase MySQL、TDSQL MySQL、PolarDB-X、PolarDB-X Centralized、DRDS、SingleStore、GBase 8a、GreatSQL、GoldenDB、Lindorm MySQL、PostgreSQL、Greenplum、Amazon Redshift、SQL Server、Oracle、OceanBase Oracle、Dameng、YashanDB、DB2、HANA、GaussDB、DWS、GBase、Sybase、Doris、SelectDB、StarRocks、Kingbase、Kingbase Oracle	创建时必填。
MongoDB	创建时必填；认证库通过 extraConfig.authDB 指定。
Redis、ElastiCache、Memorystore、PegaDB	使用账号认证时必填；无认证时可不传。
Kafka	kafkaAuthorization 为 SASL/PLAIN、SASL/SCRAM-SHA-256 或 SASL/SCRAM-SHA-512 时必填；为 PLAINTEXT 时可不传。
Hive	当 hadoopAuthConfig.authMethod=KERBEROS 时，顶层 username、password 可不传；其他认证方式按目标认证配置填写。
Elasticsearch、ClickHouse、Trino、ShardingJDBC 等	按目标数据源认证方式填写；不启用认证时可不传。

不满足当前数据源类型认证条件时，接口可能返回参数校验错误。不要使用空字符串代替未使用的账号密码，也不要将 SSH 密码放入顶层 password。

MongoDB 单机版 extraConfig 参数

创建 MongoDB 单机数据源时，在 extraConfig 中传入以下字段。

参数	类型	是否必选	说明	示例
mongoDBDeploymentType	String	否	MongoDB 部署类型，单机模式传入 standalone。	standalone
authDB	String	是	认证数据库。	admin

请求示例

以下示例按通过网关访问非公网数据库编写。若目标数据库可从 NineData 公网直接访问，将 networkType 改为 public 并移除 gatewayId；网络类型必须与实际地址和网络配置匹配。

MongoDB 单机版：

{
  "name": "示例 MongoDB",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 27017,
  "datasourceType": "mongodb",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>",
  "extraConfig": {
    "mongoDBDeploymentType": "standalone",
    "authDB": "admin"
  }
}

MySQL：

{
  "name": "示例 MySQL",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 3306,
  "datasourceType": "mysql",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>"
}

PostgreSQL：

{
  "name": "示例 PostgreSQL",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 5432,
  "datasourceType": "postgresql",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>",
  "extraConfig": {
    "authDB": "<DATABASE_NAME>",
    "clientTimezone": "+08:00"
  }
}

Oracle（SERVICE_NAME）：

{
  "name": "示例 Oracle",
  "username": "<username>",
  "password": "<password>",
  "host": "<DB_HOST>",
  "port": 1521,
  "datasourceType": "oracle",
  "regionId": "<regionId>",
  "envId": "<envId>",
  "networkType": "gateway",
  "gatewayId": "<gatewayId>",
  "extraConfig": {
    "serviceName": "<SERVICE_NAME>"
  }
}

返回参数

参数	类型	说明	示例
success	Bool	接口调用是否成功。返回值：true、false。	true
requestId	String	请求 ID。	<requestId>
data	Object	创建的数据源详情，包含数据源 ID（datasourceId）信息。	{"datasourceId":"<datasourceId>"}

调用成功示例

{
  "success": true,
  "requestId": "<requestId>",
  "data": {
    "datasourceId": "<datasourceId>"
  }
}