首选页眉

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

支持以下首选项。

从严从宽处理

默认情况下，服务器会忽略无法识别或无法实现的首选项。您可以使用 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"}

失踪

做时 POST 和 PATCH 请求时，有效负载中任何缺失的列都将被插入为 null 默认值。使用 DEFAULT 改为列值，请使用 Prefer: missing=default 标头

拥有：

create table foo (
  id bigint generated by default as identity primary key
, bar text
, baz int default 100
);

一项请求：

curl "http://localhost:3000/foo?columns=id,bar,baz" \
  -H "Content-Type: application/json" \
  -H "Prefer: missing=default, return=representation" \
  -d @- << EOF
    [
      { "bar": "val1" },
      { "bar": "val2", "baz": 15 }
    ]
EOF

将导致：

[
  { "id":  1, "bar": "val1", "baz": 100 },
  { "id":  2, "bar": "val2", "baz": 15 }
]

受影响的最大值

您可以通过发送以下命令来设置请求中受影响的资源量限制： max-affected 偏好此功能可与 handling=strict 偏好 max-affected 会被宽大处理而忽视。“受影响的资源”是由返回的行数 DELETE 和 PATCH 请求。

为了说明此首选项的用法，请考虑以下方案，其中 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
}

与 RPC ，则根据函数结果集中返回的行数完全执行首选项。这对于使用 data-modifying statements .一个简单的例子：

CREATE FUNCTION test.delete_items()
RETURNS SETOF items AS $$
  DELETE FROM items WHERE id < 15 RETURNING *;
$$ LANGUAGE SQL;

curl -i "http://localhost:3000/rpc/delete_items" \
  -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
}