首选项标头

PostgREST 遵循在 RFC 7240 上指定的 Prefer HTTP 标头。它允许客户端为其请求指定所需和可选的行为。

支持以下首选项。

严格或宽松处理

默认情况下，服务器会忽略无法识别或无法满足的偏好设置。您可以使用 handling 偏好设置来控制此行为。它可以取两个值：lenient（默认值）或 strict。

handling=strict 会在您指定无效偏好设置时抛出错误。例如

curl -i "http://localhost:3000/projects" \
  -H "Prefer: handling=strict, foo, bar"

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "code": "PGRST122",
    "message": "Invalid preferences given with handling=strict",
    "details": "Invalid preferences: foo, bar",
    "hint": null
}

handling=lenient 会忽略无效的偏好设置。

curl -i "http://localhost:3000/projects" \
  -H "Prefer: handling=lenient, foo, bar"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

时区

timezone 偏好设置允许您更改 PostgreSQL 时区。它接受 pg_timezone_names 中的所有时区。

curl -i "http://localhost:3000/timestamps" \
  -H "Prefer: timezone=America/Los_Angeles"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Preference-Applied: timezone=America/Los_Angeles

[
  {"t":"2023-10-18T05:37:59.611-07:00"},
  {"t":"2023-10-18T07:37:59.611-07:00"},
  {"t":"2023-10-18T09:37:59.611-07:00"}
]

对于无效的时区，PostgREST 会使用默认时区（在 postgresql.conf 中配置或作为 身份验证器 上的设置）返回值。

curl -i "http://localhost:3000/timestamps" \
  -H "Prefer: timezone=Jupiter/Red_Spot"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {"t":"2023-10-18T12:37:59.611+00:00"},
  {"t":"2023-10-18T14:37:59.611+00:00"},
  {"t":"2023-10-18T16:37:59.611+00:00"}
]

请注意，响应中没有 Preference-Applied。

但是，使用 handling=strict，无效的时区偏好设置将抛出 错误.

curl -i "http://localhost:3000/timestamps" \
  -H "Prefer: handling=strict, timezone=Jupiter/Red_Spot"

HTTP/1.1 400 Bad Request

返回表示

可以使用 return 偏好设置来获取有关受影响资源的信息，当它被 插入、更新 或 删除 时。这有助于避免后续的 GET 请求。

最小

使用 Prefer: return=minimal，不会返回任何响应主体。这是所有写入请求的默认模式。

仅限标头

如果表具有主键，则响应可以包含一个 Location 标头，描述在请求中包含标头 Prefer: return=headers-only 的情况下，在哪里可以找到新对象。确保该表不是只写表，否则构造 Location 标头会导致权限错误。

curl -i "http://localhost:3000/projects" -X POST \
  -H "Content-Type: application/json" \
  -H "Prefer: return=headers-only" \
  -d '{"id":33, "name": "x"}'

HTTP/1.1 201 Created
Location: /projects?id=eq.34
Preference-Applied: return=headers-only

完整

在另一方面，您可以通过在请求中包含标头 Prefer: return=representation，在响应中获取完整的创建对象。这样，您就不必进行另一个 HTTP 调用来发现可能在服务器端填充的属性。您还可以将标准 垂直过滤 应用于这些结果。

curl -i "http://localhost:3000/projects" -X POST \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{"id":33, "name": "x"}'

HTTP/1.1 201 Created
Preference-Applied: return=representation

[
    {
        "id": 33,
        "name": "x"
    }
]

事务结束偏好

可以设置 tx 偏好设置来指定 事务 将以 COMMIT 还是 ROLLBACK 结束。此偏好设置默认情况下未启用，但可以通过 db-tx-end 激活。

curl -i "http://localhost:3000/projects" -X POST \
  -H "Content-Type: application/json" \
  -H "Prefer: tx=rollback, return=representation" \
  -d '{"name": "Project X"}'

HTTP/1.1 200 OK
Preference-Applied: tx=rollback, return=representation

{"id": 35, "name": "Project X"}

最大影响范围

您可以通过发送 max-affected 偏好设置来限制请求中受影响的资源数量。此功能与 handling=strict 偏好设置结合使用。在宽松处理的情况下，max-affected 将被忽略。“受影响的资源”是指 DELETE 和 PATCH 请求返回的行数。这也通过 RPC 调用得到支持。

为了说明此偏好设置的使用，请考虑以下场景，其中 items 表包含 14 行。

curl -i "http://localhost:3000/items?id=lt.15 -X DELETE \
  -H "Content-Type: application/json" \
  -H "Prefer: handling=strict, max-affected=10"

HTTP/1.1 400 Bad Request

{
    "code": "PGRST124",
    "message": "Query result exceeds max-affected preference constraint",
    "details": "The query affects 14 rows",
    "hint": null
}

单个 JSON 对象作为函数参数

警告

使用此偏好设置已弃用，建议使用 具有单个未命名 JSON 参数的函数。

Prefer: params=single-object 允许将 JSON 请求正文作为 函数 的单个参数发送。

CREATE FUNCTION mult_them(param json) RETURNS int AS $$
  SELECT (param->>'x')::int * (param->>'y')::int
$$ LANGUAGE SQL;

curl "http://localhost:3000/rpc/mult_them" \
  -X POST -H "Content-Type: application/json" \
  -H "Prefer: params=single-object" \
  -d '{ "x": 4, "y": 2 }'

8