跳到主要内容
Version: 1.0.0

PostgreSQL HTTP API

功能介绍​

CloudBase PostgreSQL 数据库的 Data API 基于开源 PostgREST 实现，更多文档您可以参考 PostgREST 官方文档。

仅支持 public schema

目前 REST API 只支持 public schema，即只能访问 public schema 下的表、视图和函数，不支持访问或切换到其他 schema（如 auth、storage）。

如需读写非 public schema 的数据，请改用 执行 SQL 语句 或控制台的 SQL 编辑器。

请求域名​

请求域名格式为：https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{table}

  • envId 是环境id
  • table 是表名，必须是 public schema 下的表

接入指引​

调用以下接口需要传递 AccessToken，格式如Authorization: Bearer <token>。Access token 获取方式参考文档

请求编码​

当发起请求前请进行 url 编码，如：

原始请求

curl -i -X GET 'https://{{host}}/v1/rdb/rest/course?select=name,position&name=like.%张三%&title=eq.文章标题'

编码后请求

curl -i -X GET 'https://{{host}}/v1/rdb/rest/course?select=name,position&name=like.%%E5%BC%A0%E4%B8%89%&title=eq.%E6%96%87%E7%AB%A0%E6%A0%87%E9%A2%98'

请求头和返回头​

请求头参数说明示例
Accept支持 application/json、application/vnd.pgrst.object+json控制数据返回格式Accept: application/json
Content-Type支持 application/json、application/vnd.pgrst.object+json返回Content-Type: application/json
Prefer操作依赖的特征值
  • return=representation 写操作，返回数据体和数据头
  • return=minimal 写操作，不返回数据体只返回头，写操作默认类型
  • count=exact 读操作，指定 count 计数
  • resolution=merge-duplicates upsert操作，合并冲突项
  • resolution=ignore-duplicates upsert操作，忽略冲突项
Prefer: return=representation
Preference-Applied使用请求时Prefer的类型返回信息使用请求时的Prefer，会将对应的特征信息以此返回，某些情况下会有默认值Preference-Applied: return=representation
Content-Range分页信息
  • 当查询时指定 Prefer: count=exact 时会返回分页信息入 0-1/2，其中0表示起始位，1表示偏移量，2表示总数 （注意，此处的起始位、偏移量并非 PostgreSQL 中的 offset、limit关键字含义，而是指查询后的数据位置，通常配合 limit 使用）
  • 当写操作时指定 return=representation 或 return=minimal (默认) 时，会返回分页信息，如 -/2，其中2表示受影响行数
Content-Range: 0-1/2

错误码与 HTTP 状态码​

错误码HTTP状态码说明
INVALID_PARAM400请求参数无效
INVALID_REQUEST400请求内容无效：缺少权限字段、执行SQL异常等
INVALID_REQUEST406不符合单条记录返回约束
PERMISSION_DENIED401、403鉴权失败：如果身份认证失败返回 401，如果鉴权失败返回403
RESOURCE_NOT_FOUND404未找到数据库实例或表信息
SYS_ERR500系统内部错误
OPERATION_FAILED503建立数据库连接失败
RESOURCE_UNAVAILABLE503数据库由于某些原因导致不可用

数据返回​

  1. 所有 POST、PATCH、DELETE 一样，请求头带 Prefer: return=representation 表示有返回体，不带表示无回包只有返回头
  2. POST、PATCH、DELETE 的返回体通常是json array类型 [] ，如果请求头指定了 Accept: application/vnd.pgrst.object+json，那么会返回json object类型 {}
  3. 如果指定 Accept: application/vnd.pgrst.object+json，但是数据是大于 1 的量，则会报错