创建数据源

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

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

请求方法：POST

请求参数

参数	类型	是否必选	说明	示例
datasourceType	String	是	数据源类型。必须传入下表中的枚举值；具体值是否可用取决于目标 NineData 环境当前启用的类型。	mysql
name	String	是	指定数据源名称。	示例 MongoDB
username	String	条件必填	数据库账号；具体必填条件取决于数据源类型和认证方式，详见账号和密码必填条件。	<username>
password	String	条件必填	数据库密码；必填条件与 username 相同，详见账号和密码必填条件。	<password>
host	String	是	单机模式传 IP 或域名；副本集或分片集群传 host1:port1,host2:port2。	<DB_HOST>
port	Integer	否	单机模式必填；副本集或分片集群模式不传，端口信息写入 host。	27017
envId	String	否	所属环境。可通过查询环境信息获取。	<envId>
regionId	String	否	为该数据源指定所属地域。您需要调用查询地区信息接口获取 regionId。	<regionId>
networkType	String	否	连接方式。不传时默认为 public；可选值：public、gateway、private、ssh。	public
masterName	String	否	主节点名称，适用于包含主节点的数据源。	master-1
hostAndPorts	String	否	逗号分隔的多节点 host:port 组合，例如 Redis Sentinel 或 Cluster。	host1:port1,host2:port2
instanceId	String	否	cloudInstanceType=instance 时必填。	<instanceId>
instanceType	String	否	云实例类型。可选值：ECS、EC2、RDS、Express、Polardb、PolardbX、DRDS、TDSQL、GaussDB、DDS、Aurora、Redis、Kafka、Elasticsearch、ADB、Doris、SCS、MongoDB、DocumentDB、Redshift、clickhouse、GaiaDB、GaiaDBX、OceanBase、VectorDB、VastBase、GoldenDB、CloudSQL、AlloyDB、GoogleCloud。	RDS
cloudInstanceType	String	否	云实例接入方式。可选值：instance、url。	instance
vendorRegionId	String	否	云厂商地域 ID。	cn-hangzhou
serverVersion	String	否	数据源服务版本。	8.0
gatewayId	String	否	networkType=gateway 时传入。	<gatewayId>
tunnelId	String	否	networkType=private 时通常传入；当前接口未强制校验。	<tunnelId>
accessId	String	否	云厂商访问凭证 ID；云环境 API 调用时使用。	<accessId>
env	String	否	环境标识，由请求参数决定。	<environment>
sshConfig	Object	否	networkType=ssh 时必填，用于指定 SSH 连接配置。字段结构见 SSHConfig 结构。	{}
extraConfig	Object	否	数据源专属配置。不同类型数据源的专有参数放在该对象中，详见下文。	{"authDB":"admin"}

参数必填规则

是否必选列说明接口的通用请求要求；数据源类型和连接方式会进一步决定条件字段。请仅传入当前场景需要的字段：

场景	必填字段或传参规则
所有创建请求	datasourceType、name。datasourceType 还必须是目标 NineData 环境当前启用的枚举值。
使用单机模式连接	host、port 必填。
使用副本集或分片集群模式连接	host 必填，并在其中按 host1:port1,host2:port2 传入节点和端口；不传 port。
networkType 未传	按 public 处理。
networkType=gateway	传入 gatewayId。
networkType=private	通常传入 tunnelId；当前接口未强制校验，缺省时可能按直连处理。
networkType=ssh	sshConfig 必填。
cloudInstanceType=instance	instanceId 必填。
使用云环境 API	按目标云环境传入 accessId；DataHub 类型会使用该凭证的 AccessKey 和 AccessKeySecret 作为账号密码。
需要指定环境或地域	传入 envId 或 regionId；不传 envId 时默认使用 env-dev，该环境不存在时校验失败。

未触发条件的字段不要使用空字符串代替。账号密码、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	否	节点账号。

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