调用 RPC

通过 HTTP RESTful API 调用 PostgreSQL 数据库中的自定义函数（Stored Procedures / Functions）。

💡 提示：PostgreSQL 数据库的 HTTP API 基于 PostgREST 协议，RPC 调用语法与 PostgREST 完全兼容。

基础语法

POST https://your-envId.api.tcloudbasegateway.com/v1/rdb/rest/rpc/:function_name
Authorization: Bearer <access_token>
Content-Type: application/json

💡 提示：access_token 请参考 获取 AccessToken

创建函数

在调用 RPC 之前，需要先在 PostgreSQL 数据库中创建函数。可以通过 DMC 数据库管理工具执行 SQL 创建函数。

-- 创建一个简单的加法函数
CREATE OR REPLACE FUNCTION add_numbers(a integer, b integer)
RETURNS integer AS $$
  SELECT a + b;
$$ LANGUAGE sql;

-- 创建一个查询电影的函数
CREATE OR REPLACE FUNCTION search_films(keyword text)
RETURNS SETOF film AS $$
  SELECT * FROM film WHERE title ILIKE '%' || keyword || '%';
$$ LANGUAGE sql;

-- 创建一个统计函数
CREATE OR REPLACE FUNCTION get_film_stats()
RETURNS json AS $$
  SELECT json_build_object(
    'total', COUNT(*),
    'avg_duration', ROUND(AVG(duration)),
    'max_duration', MAX(duration),
    'min_duration', MIN(duration)
  ) FROM film;
$$ LANGUAGE sql;

基础调用

带参数调用

# 调用加法函数
curl -X POST 'https://{{host}}/v1/rdb/rest/rpc/add_numbers' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{ "a": 1, "b": 2 }'

请求返回示例

HTTP/1.1 200 OK
Header:
    content-type: application/json; charset=utf-8
Body:
3

无参数调用

# 调用统计函数
curl -X POST 'https://{{host}}/v1/rdb/rest/rpc/get_film_stats' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

请求返回示例

HTTP/1.1 200 OK
Header:
    content-type: application/json; charset=utf-8
Body:
{
    "total": 15,
    "avg_duration": 148,
    "max_duration": 194,
    "min_duration": 96
}

返回表数据的函数

当函数返回 SETOF <table> 时，返回值为数组格式，并且支持与普通查询一样的过滤、排序、分页等操作。

# 搜索包含关键字的电影
curl -X POST 'https://{{host}}/v1/rdb/rest/rpc/search_films' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{ "keyword": "Godfather" }'

请求返回示例

HTTP/1.1 200 OK
Header:
    content-type: application/json; charset=utf-8
Body:
[
    {
        "id": 3,
        "title": "The Godfather",
        "release_year": 1972,
        "director": "Francis Ford Coppola",
        "duration": 175,
        "_openid": "1977683311217119233"
    },
    {
        "id": 4,
        "title": "The Godfather: Part II",
        "release_year": 1974,
        "director": "Francis Ford Coppola",
        "duration": 202,
        "_openid": "1977683311217119233"
    }
]

对返回结果进行过滤和排序

当函数返回表数据时，可以像普通查询一样使用过滤、排序、分页等参数。

# 搜索电影，只返回指定字段，并按年份降序排列，限制返回 2 条
curl -X POST 'https://{{host}}/v1/rdb/rest/rpc/search_films?select=title,release_year&order=release_year.desc&limit=2' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{ "keyword": "Godfather" }'

请求返回示例

HTTP/1.1 200 OK
Header:
    content-type: application/json; charset=utf-8
Body:
[
    {
        "title": "The Godfather: Part II",
        "release_year": 1974
    },
    {
        "title": "The Godfather",
        "release_year": 1972
    }
]

使用 GET 请求调用

除了 POST 请求外，也可以使用 GET 请求调用 RPC 函数，参数通过 query string 传递。

⚠️ 注意：GET 方式仅适用于标记为 IMMUTABLE 或 STABLE 的只读函数。

# 使用 GET 请求调用加法函数
curl -X GET 'https://{{host}}/v1/rdb/rest/rpc/add_numbers?a=1&b=2' \
-H 'Authorization: Bearer <access_token>'

请求返回示例

HTTP/1.1 200 OK
Header:
    content-type: application/json; charset=utf-8
Body:
3

强制返回单个对象

默认情况下，函数返回的标量值会直接返回。如果需要强制返回对象格式，可以指定 Header Accept: application/vnd.pgrst.object+json。

curl -X POST 'https://{{host}}/v1/rdb/rest/rpc/search_films?limit=1' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.pgrst.object+json' \
-d '{ "keyword": "Godfather" }'

⚠️ 注意：使用 application/vnd.pgrst.object+json 时，返回结果必须恰好为一条记录，否则会报错。可以配合 limit=1 使用。

请求返回示例

HTTP/1.1 200 OK
Header:
    content-type: application/vnd.pgrst.object+json; charset=utf-8
Body:
{
    "id": 3,
    "title": "The Godfather",
    "release_year": 1972,
    "director": "Francis Ford Coppola",
    "duration": 175,
    "_openid": "1977683311217119233"
}

函数参数类型

PostgREST 支持多种 PostgreSQL 函数参数类型：

参数类型	说明	JSON 传参示例
integer	整数	{ "id": 1 }
text / varchar	文本	{ "name": "test" }
boolean	布尔值	{ "active": true }
json / jsonb	JSON 对象	{ "data": { "key": "value" } }
integer[]	整数数组	{ "ids": [1, 2, 3] }
text[]	文本数组	{ "names": ["a", "b"] }