Cloud Databases API

第2代

Cloud Databases API 通常使用资源控制器 API 进行操作。请使用此 API 文档来操作您的数据服务。

认证

访问该 API 采用令牌认证，需在请求头中使用 Authorization: Bearer <token>。该令牌必须由 IAM 签发。您可以直接将 IAM API 密钥作为令牌提交，或者使用该 API 密钥生成一个 IAM 承载令牌。

要调用每个方法，您必须是被分配了一个角色，且该角色包含所需的IAM操作。每个方法都列出了相关的操作。有关 IAM 操作及其与角色的映射关系的更多信息，请参阅《管理 IBM Cloud® 的访问权限》。

错误处理

该 API 使用标准的 HTTP 响应代码来指示方法是否执行成功。 200 响应始终表示成功。 4xx 类型的响应表示某种错误，而 500 类型的响应通常表示系统内部错误。这些响应中的任何一个都可能附带一个 JSON 格式的正文，其中包含更详细的错误信息。

事件跟踪

您可以使用 IBM Cloud® Activity Tracker 服务。每当调用一个 API 方法时，系统都会生成一个事件，您可以在 Activity Tracker 中对其进行跟踪和审计。每个方法都列出了具体的事件类型。

部署 ID 和 CRN

在 Cloud Data Services 平台上，部署 ID 即为 CRN。使用 CRN 时，请记住对 CRN 值进行 URL 编码，因为其中可能包含正斜杠 (/) %2F 字符。

示例：以下 CRN

crn:v1:bluemix:public:databases-for-redis:us-south:a/274074dce64e9c423ffc238516c755e1:29caf0e7-120f-4da8-9551-3abf57ebcfc7::

在采用 URL 编码后，结果如下：

crn:v1:bluemix:public:databases-for-redis:us-south:a%2F274074dce64e9c423ffc238516c755e1:29caf0e7-120f-4da8-9551-3abf57ebcfc7::

分页

目前没有哪个端点返回分页数据。

速率限制

目前尚无任何端点实现速率限制。

方法

列出所有已部署的产品

返回所有已部署的云服务的列表。

GET /v2/resource_instances

示例请求：

curl -X GET https://resource-controller.cloud.ibm.com/v2/resource_instances -H "Authorization: Bearer <IAM token>"

示例响应：

{
  "rows_count": 100,
  "next_url": "/v2/resource_instances?start=<token>",
  "resources": [
    {
      "id": "crn:v1:bluemix:public:databases-for-redis:eu-de:a/40ddc34a953a8c02f10987b59085b60e:07d523b1-6eea-4263-bd03-c17edf355e0b::",
      "guid": "07d523b1-6eea-4263-bd03-c17edf355e0b",
      "url": "/v2/resource_instances/07d523b1-6eea-4263-bd03-c17edf355e0b",
      "created_at": "2026-07-17T06:41:51.267012883Z",
      "updated_at": "2026-07-17T06:42:11.22949657Z",
      "deleted_at": null,
      "created_by": "Id-270000000X",
      "updated_by": "",
      "deleted_by": "",
      "scheduled_reclaim_at": null,
      "restored_at": null,
      "scheduled_reclaim_by": "",
      "restored_by": "",
      "name": "test-redis-gen2",
      "region_id": "eu-de",
      "account_id": "40ddc34a953a8c02f10987b59085b60e",
      "reseller_channel_id": "",
      "resource_plan_id": "databases-for-redis-gen2-standard",
      "resource_group_id": "eb922ba0717f47589ca26d202c5cc915",
      "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/40ddc34a953a8c02f10987b59085b60e::resource-group:eb922ba0717f47589ca26d202c5cc915",
      "target_crn": "crn:v1:bluemix:public:globalcatalog::::deployment:databases-for-redis-standard-gen2%3Aeu-de",
      "parameters": {
        "dataservices": {
          "redis": {
            "host_flavor": "bxf.4x16",
            "members": 2,
            "storage_gb": 15,
            "version": "8.2"
          }
        }
      },
      "allow_cleanup": false,
      "crn": "crn:v1:bluemix:public:databases-for-redis:eu-de:a/40ddc34a953a8c02f10987b59085b60e:07d523b1-6eea-4263-bd03-c17edf355e0b::",
      "state": "provisioning",
      "type": "service_instance",
      "sub_type": "Public",
      "resource_id": "databases-for-redis",
      "dashboard_url": null,
      "last_operation": {
        "type": "create",
        "state": "in progress",
        "async": true,
        "description": "Provision in progress",
        "cancelable": true,
        "poll": true
      },
      "resource_keys_url": "/v2/resource_instances/07d523b1-6eea-4263-bd03-c17edf355e0b/resource_keys",
      "plan_history": [
        {
          "resource_plan_id": "databases-for-redis-gen2-standard",
          "start_date": "2026-07-17T06:41:51.267012883Z",
          "requestor_id": "Id-270000000X"
        }
      ],
      "migrated": false,
      "controlled_by": "",
      "locked": false,
      "onetime_credentials": false
    }
  ]
}

resources 数组中返回了其他资源对象。使用 next_url 令牌来获取下一页结果。

获取部署信息

获取与某个部署相关的完整数据。这些数据包括 ID、名称、数据库类型和版本。

GET /v2/resource_instances/{id}

示例请求：

curl -X GET https://resource-controller.cloud.ibm.com/v2/resource_instances/95004d03-9fec-443b-9f6e-083f2b25e73a -H "Authorization: Bearer <IAM token>" \

示例响应：

{
	"id": "crn:v1:bluemix:public:databases-for-postgresql:us-east:a/23b09aee04da4545b6e32805fa93249d:95004d03-9fec-443b-9f6e-083f2b25e73a::",
	"guid": "95004d03-9fec-443b-9f6e-083f2b25e73a",
	"url": "/v2/resource_instances/95004d03-9fec-443b-9f6e-083f2b25e73a",
	"created_at": "2026-07-02T14:04:29.613949688Z",
	"updated_at": "2026-07-02T14:15:54.226535327Z",
	"deleted_at": null,
	"created_by": "Id-4700030B2K",
	"updated_by": "",
	"deleted_by": "",
	"scheduled_reclaim_at": null,
	"restored_at": null,
	"scheduled_reclaim_by": "",
	"restored_by": "",
	"name": "Databases for PostgreSQL-3b",
	"region_id": "us-east",
	"account_id": "23b09aee04da4545b6e32805fa93249d",
	"reseller_channel_id": "",
	"resource_plan_id": "databases-for-postgresql-gen2-standard",
	"resource_group_id": "c21a4e8564c14d1aab2a9a8b441904eb",
	"resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/23b09aee04da4545b6e32805fa93249d::resource-group:c21a4e8564c14d1aab2a9a8b441904eb",
	"target_crn": "crn:v1:bluemix:public:globalcatalog::::deployment:databases-for-postgresql-standard-gen2%3Aus-east",
	"parameters": {
		"dataservices": {
			"postgresql": {
				"host_flavor": "bx3d.4x20",
				"members": 2,
				"storage_gb": 10,
				"version": "18"
			}
		}
	},
	"allow_cleanup": false,
	"crn": "crn:v1:bluemix:public:databases-for-postgresql:us-east:a/23b09aee04da4545b6e32805fa93249d:95004d03-9fec-443b-9f6e-083f2b25e73a::",
	"state": "active",
	"type": "service_instance",
	"sub_type": "Public",
	"resource_id": "databases-for-postgresql",
	"dashboard_url": null,
	"last_operation": {
		"type": "create",
		"state": "succeeded",
		"async": true,
		"description": "Provision completed successfully",
		"cancelable": true,
		"poll": true
	},
	"resource_keys_url": "/v2/resource_instances/95004d03-9fec-443b-9f6e-083f2b25e73a/resource_keys",
	"plan_history": [
		{
			"resource_plan_id": "databases-for-postgresql-gen2-standard",
			"start_date": "2026-07-02T14:04:29.613949688Z",
			"requestor_id": "Id-4700030B2K"
		}
	],
	"migrated": false,
	"extensions": {
		"dataservices": {
			"$schema": {
				"version": "1.0.0"
			},
			"connection": {
				"cli": {
					"arguments": [
						"host=95004d03-9fec-443b-9f6e-083f2b25e73a.private.uhp.postgresql.us-east.dataservices.appdomain.cloud port=5432 dbname=postgres user=$PGUSER password=$PGPASSWORD sslmode=verify-full"
					],
					"bin": "psql",
					"composed": [
						"PGUSER=$PGUSER PGPASSWORD=$PGPASSWORD PGSSLMODE=verify-full PGSSLROOTCERT=system psql 'host=95004d03-9fec-443b-9f6e-083f2b25e73a.private.uhp.postgresql.us-east.dataservices.appdomain.cloud port=5432 dbname=postgres'"
					],
					"environment": {
						"PGPASSWORD": "$PGPASSWORD",
						"PGSSLMODE": "verify-full",
						"PGSSLROOTCERT": "system",
						"PGUSER": "$PGUSER"
					},
					"type": "cli"
				},
				"postgres": {
					"authentication": {
						"method": "direct",
						"password": "$PGPASSWORD",
						"username": "$PGUSER"
					},
					"composed": [
						"postgres://$PGUSER:$PGPASSWORD@95004d03-9fec-443b-9f6e-083f2b25e73a.private.uhp.postgresql.us-east.dataservices.appdomain.cloud:5432/postgres?sslmode=verify-full"
					],
					"database": "postgres",
					"hosts": [
						{
							"hostname": "95004d03-9fec-443b-9f6e-083f2b25e73a.private.uhp.postgresql.us-east.dataservices.appdomain.cloud",
							"port": 5432
						}
					],
					"path": "/postgres",
					"port": 5432,
					"query_options": {
						"sslmode": "verify-full"
					},
					"scheme": "postgres",
					"type": "uri"
				}
			},
			"postgresql": {
				"configuration": {
					"max_connections": 115
				},
				"cpu_count": 4,
				"host_flavor": "bx3d.4x20",
				"members": 2,
				"memory_gb": 20,
				"storage_gb": 10,
				"version": "18"
			}
		},
		"virtual_private_endpoints": {
			"dns_domain": "95004d03-9fec-443b-9f6e-083f2b25e73a.private.uhp.postgresql.us-east.dataservices.appdomain.cloud",
			"dns_hosts": [
				"",
				"*"
			],
			"endpoints": [
				{
					"ip_address": "10.51.217.34",
					"zone": "us-east-1"
				},
				{
					"ip_address": "10.51.219.57",
					"zone": "us-east-2"
				},
				{
					"ip_address": "10.51.221.12",
					"zone": "us-east-3"
				}
			],
			"origin_type": "vpc",
			"ports": [
				{
					"port_max": 5432,
					"port_min": 5432
				}
			]
		}
	},
	"controlled_by": "",
	"locked": false,
	"onetime_credentials": false
}

您可以从 API 响应中获取以下信息：

last_operation 对象 - 显示您最近执行的任务。
connection object - 显示产品连接信息。
具体产品的信息显示在产品对象下方（例如，postgresql ）。

如何配置数据库

POST /v2/resource_instances

示例请求：

curl -X POST https://resource-controller.cloud.ibm.com/v2/resource_instances \
  -H "Authorization: Bearer <IAM token>" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-instance",
    "target": "ca-mon",
    "resource_group": "5c49eabc-f5e8-5881-a37e-2d100a33b3df",
    "resource_plan_id": "databases-for-postgresql-gen2-standard",
    "parameters": {
      "dataservices": {
        "postgresql": {
          "storage_gb": 10,
          "members": 2,
          "host_flavor": "b3c.8x32.encrypted",
          "version": "18"
        },
        "encryption": {
          "disk": "crn:v1..."
        },
        "$schema": {
          "version": "1.0.0"
        }
      }
    }
  }'

输入参数

name (字符串)- 实例的名称。
target (字符串)- 部署目标区域（例如，us-south、eu-de ）。
resource_group (字符串)- 资源组的 ID。
resource_plan_id (字符串)- 计划 ID（例如，databases-for-postgresql-gen2-standard ）。
parameters (对象)
- dataservices (对象)
  - <service> (对象)- 服务名称键（例如，postgresql、mysql ）。
    - storage_gb (整数)- 存储大小（单位：GB）。
    - members (整数)- 成员数量。
    - host_flavor (字符串)- 主机类型 ID（例如，b3c.8x32.encrypted ）。
    - version (字符串)- 数据库版本（例如，"18" ）。
  - encryption (对象，可选)- 磁盘加密设置。
    - disk (字符串)- 用于磁盘加密的“Key Protect”密钥的CRN。
  - $schema (对象)- 模式元数据。
    - version (字符串)- 模式版本，必须为 "1.0.0"。

如何扩展数据库

PATCH /v2/resource_instances/{id}

示例请求：

curl -X PATCH https://resource-controller.cloud.ibm.com/v2/resource_instances/ed9d2c9b-444b-421d-bbc0-503ca8dd3036 \
  -H "Authorization: Bearer <IAM token>" \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": {
      "dataservices": {
        "postgresql": {
          "storage_gb": 12,
          "members": 2,
          "host_flavor": "bxf.4x16"
        }
      }
    }
  }'

输入参数

parameters (对象)
- dataservices (对象)
  - <service> (对象)- 服务名称键（例如，postgresql、mysql ）。
    - storage_gb (整数)- 存储大小（单位：GB）。
    - members (整数)- 成员数量。
    - host_flavor (字符串)- 主机类型 ID（例如，bxf.4x16 ）。