Cloud Databases API

2ª geração

A API do Cloud Databases geralmente utiliza a API do Controlador de Recursos para fins operacionais. Utilize esta documentação da API para trabalhar com seus serviços de dados.

Autenticação

O acesso à API utiliza autenticação por token, por meio do cabeçalho Authorization: Bearer <token>. O token deve ter sido emitido pelo IAM. Você pode enviar uma chave de API do IAM diretamente como token ou usar a chave de API para gerar um token de portador do IAM.

Para chamar cada método, você precisará ter uma função atribuída que inclua as ações do IAM necessárias. Cada método lista a ação associada. Para obter mais informações sobre as ações do IAM e como elas são mapeadas para funções, consulte Gerenciando o acesso para o IBM Cloud®.

Manipulação de erros

A API utiliza códigos de resposta padrão da HTTP para indicar se um método foi concluído com sucesso. Uma resposta do tipo “ 200 ” sempre indica sucesso. Uma resposta do tipo “ 4xx ” indica algum tipo de falha, enquanto uma resposta do tipo “ 500 ” geralmente indica um erro interno do sistema. Qualquer uma dessas respostas pode vir acompanhada de um corpo no formato JSON que contenha informações mais detalhadas sobre o erro.

Rastreamento de eventos

Você pode monitorar a atividade da API na sua conta usando o IBM Cloud® Activity Tracker serviço. Sempre que um método da API é chamado, é gerado um evento que você pode acompanhar e auditar no site Activity Tracker. O tipo específico de evento é indicado para cada método individualmente.

IDs de implantação e CRNs

Os IDs de implantação são CRNs na plataforma Cloud Data Services. Ao usar o CRN, lembre-se de codificar o valor do CRN URL, pois ele pode incluir o caractere barra (/) %2F.

Exemplo: O CRN a seguir

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

fica assim quando codificado com o formato “ URL ”.

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

Paginação

Atualmente, nenhum endpoint retorna dados paginados.

Limitação de taxa

Atualmente, nenhum endpoint implementa limitação de taxa.

Métodos

Listar todos os produtos implantados

Retorna uma lista de todos os serviços em nuvem implantados.

GET /v2/resource_instances

Solicitação de exemplo:

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

Resposta de exemplo:

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

Objetos de recursos adicionais são retornados na matriz resources . Use o token next_url para recuperar a próxima página de resultados.

Obter informações sobre a implantação

Obtém todos os dados associados a uma implantação. Esses dados incluem o ID, o nome, o tipo de banco de dados e a versão.

GET /v2/resource_instances/{id}

Solicitação de exemplo:

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

Resposta de exemplo:

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

É possível obter as seguintes informações a partir da resposta da API:

  • last_operation objeto - Mostra a última tarefa que você realizou.
  • connection objeto - Exibe informações sobre a conexão do produto.
  • As informações específicas do produto são exibidas na página do produto (por exemplo, postgresql).

Como provisionar seu banco de dados

POST /v2/resource_instances

Solicitação de exemplo:

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

Parâmetros de Entrada

  • name (String)- O nome da instância.
  • target (String)- A região na qual a implantação será realizada (por exemplo, us-south, eu-de).
  • resource_group (String)- O ID do grupo de recursos.
  • resource_plan_id (String)- O ID do plano (por exemplo, databases-for-postgresql-gen2-standard).
  • parameters (Objeto)
    • dataservices (Objeto)
      • <service> (Objeto)- A chave do nome do serviço (por exemplo, postgresql, mysql).
        • storage_gb (Número inteiro)- Tamanho do armazenamento em GB.
        • members (Número inteiro)- Número de membros.
        • host_flavor (String)- O ID do tipo de host (por exemplo, b3c.8x32.encrypted).
        • version (String)- A versão do banco de dados (por exemplo, "18").
      • encryption (Objeto, opcional)- Configurações de criptografia de disco.
        • disk (String)- CRN da chave “ Key Protect ” para criptografia de disco.
      • $schema (Objeto)- Metadados do esquema.
        • version (String)- Versão do esquema; deve ser "1.0.0".

Como dimensionar seu banco de dados

PATCH /v2/resource_instances/{id}

Solicitação de exemplo:

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

Parâmetros de Entrada

  • parameters (Objeto)
    • dataservices (Objeto)
      • <service> (Objeto)- A chave do nome do serviço (por exemplo, postgresql, mysql).
        • storage_gb (Número inteiro)- Tamanho do armazenamento em GB.
        • members (Número inteiro)- Número de membros.
        • host_flavor (String)- O ID do tipo de host (por exemplo, bxf.4x16).