首选页眉#

PostgREST支持在 RFC 7240 。它允许客户端为其请求指定必需和可选的行为。

支持以下首选项。

Prefer: handling 。看见从严从宽处理。
Prefer: timezone 。看见时区。
Prefer: return 。看见返回表示法。
Prefer: count 。看见数数。
Prefer: resolution 。看见向上插入。
Prefer: missing 。看见使用缺省值的大容量插入。
Prefer: max-affected ，请参阅受影响的最大值。
Prefer: tx 。看见交易结束首选项。
Prefer: params 。看见作为函数参数的单个JSON对象。

从严从宽处理#

默认情况下，服务器会忽略无法识别或无法实现的首选项。您可以使用 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 timezone 。它接受中的所有时区 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 或作为 authenticator )。

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 ，则无效的时区首选项将引发 error 。

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

HTTP/1.1 400 Bad Request

返回表示法#

这个 return 首选项可用于获取有关受影响资源的信息 inserted ， updated 或 deleted 。这有助于避免后续的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 可以设置首选项以指定是否 transaction 将以提交或回滚结束。默认情况下不启用此首选项，但可以使用激活 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对象#

警告

使用此首选项是 deprecated 赞成具有单个未命名JSON参数的函数。

Prefer: params=single-object 允许将JSON请求正文作为 function 。

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