HTTP QUERY 方法

本文档使用以下位置定义的术语：第 3 节，见 [HTTP]。

此外，本文档使用术语URI 查询参数表示 URI 查询 组件中的参数 (第 4.2.2 节， 见 [HTTP])，并使用术语查询 内容表示请求内容 (第 6.4 节，见 [HTTP])，即 QUERY 请求的内容。

本文档中的关键词“MUST（必须）”、“MUST NOT（不得）”、“REQUIRED（必需）”、“SHALL（必须）”、“SHALL NOT（不得）”、“SHOULD（应当）”、“SHOULD NOT（不应当）”、“RECOMMENDED（建议）”、“NOT RECOMMENDED（不建议）”、“MAY（可以）”和“OPTIONAL（可选）”应按照以下文档中的说明解释： BCP 14 [RFC2119] [RFC8174] 当且仅当对应英文关键词像此处所示那样以全大写形式出现时。

QUERY 请求的语义同时取决于请求内容和相关的 元数据，例如媒体类型 ([HTTP]，第 8.3.1 节)。 一般而言，对于内容与元数据不一致的请求所存在的任何问题，都必须使用 4xx（客户端错误）响应予以拒绝 ([HTTP]，第 15.5 节)。

• 如果请求缺少媒体类型信息，则按定义它就是不正确的，需要 使用 4xx 状态码使其失败，例如 400（客户端错误）。
• 如果指定了媒体类型，但资源不支持该类型，则适合使用 415 （不支持的媒体类型）。这明确包括以下情况： 原则上已知该媒体类型，但它缺少针对 目标资源的 QUERY 的特定语义。在这两种情况下，Accept-Query 响应字段 (第 3 节) 可用于告知客户端所支持的媒体类型。
• 如果指定了媒体类型，但它与实际请求内容不一致，则 可以返回 400（错误请求）。也就是说，不允许服务器根据请求内容推断媒体 类型，然后覆盖缺失或“错误”的值 （即“内容嗅探”）。
• 如果指定的媒体类型已被理解，且内容确实与 该类型一致，但由于查询的实际内容而无法处理 查询，则可以使用状态码 422（无法处理的内容）。例如， 语法正确的 SQL 查询标识了一个不存在的表。
• 如果客户端使用 Accept 字段 ([HTTP]，第 12.5.1 节) 请求了资源不支持的特定响应媒体类型，则适合使用 406（不可 接受）状态码。

对于任意给定的 QUERY 请求，其等价资源是一个响应 GET 请求、代表该 QUERY 请求及其目标，并同时考虑消息 内容和元数据的资源 (第 6 节，见 [HTTP])。具体而言，这 包括表示元数据 (第 8 节，见 [HTTP])，例如 内容的媒体类型。

换言之，等价资源是通过纳入请求内容， 从实现 QUERY 的资源派生而来的。

术语等价资源用于定义其他 HTTP 方面的行为，例如选定表示。服务器可以但不必为 这些资源分配 URI（参见 第 1.1 节，位于 [URI]）。如果 分配了 URI，这些资源就可以通过 GET 请求访问。

成功响应（2xx，第 15.3 节，见 [HTTP]）可以包含一个 Content-Location 首部字段，其中包含与 操作结果对应的资源标识符；详情参见 第 8.7 节，位于 [HTTP]。这 表示服务器声明：客户端可以向 指定 URI 发送 GET 请求，以检索刚刚执行的查询操作的结果。所 指示的资源可能是临时的。

参见附录 A.4.1 中的示例。

服务器可以为 QUERY 请求的等价资源 (第 2.2 节) 分配 URI。如果服务器这样 做，则可以将该资源的 URI 包含在 2xx 响应的 Location 首部字段中（参见 第 10.2.2 节， 位于 [HTTP]）。这表示 服务器声明：客户端可以向指定 URI 发送 GET 请求，以重复刚刚执行的查询 操作，而无需重新发送查询内容。此资源的 URI 可能 是临时的；如果后续请求失败，客户端可以使用原始 QUERY 请求目标和之前提交的内容重试。

参见附录 A.4.2 中的示例。

在某些情况下，服务器可能选择通过 将用户代理重定向到其他 URI 来间接响应 QUERY 请求（参见 第 15.4 节，位于 [HTTP]）。

状态码为 301（永久移动，[HTTP]，第 15.4.2 节）或 308（永久重定向，[HTTP]，第 15.4.9 节）的响应，表示目标资源已永久移动到 Location 响应字段所引用的其他 URI ([HTTP]，第 10.2.2 节)。同样，状态码为 302（找到，[HTTP]，第 15.4.3 节）或 307（临时重定向，[HTTP]，第 15.4.8 节）的响应，表示目标资源已临时移动。在这四种 情况下，服务器都在建议用户代理可以通过 向 Location 所引用的新目标 URI 发送类似的 QUERY 请求， 来完成其原始 QUERY 请求。

请注意，在收到 301 或 302 响应后将 POST 重定向为 GET 请求的例外情况，不适用于 QUERY 请求。

状态码为 303（参见其他，第 15.4.4 节， 见 [HTTP]）的 QUERY 响应表示， 原始查询可以通过对 Location 响应字段所引用的 URI 发出普通检索请求来完成 ([HTTP]，第 10.2.2 节)。对于 HTTP，这意味着向新目标 URI 发送 GET 请求，如 以下示例所示：附录 A.4.3。

QUERY 请求的选定表示 (第 3.2 节，见 [HTTP]) 与对该 QUERY 请求的等价资源 (第 2.2 节) 发出 GET 请求时 的选定表示相同。

条件 QUERY 要求仅在条件首部字段所描述的 情况下，才在响应中返回选定表示（即经过任何内容协商后的查询结果）， 这些情况定义于 第 13 节，位于 [HTTP]。

参见附录 A.5 中的 示例。

QUERY 方法的响应是可缓存的；缓存可以使用它来 满足后续的 QUERY 请求，依据 第 4 节，位于 [HTTP-CACHING]。

QUERY 请求的缓存键 (第 2 节，见 [HTTP-CACHING]) 必须纳入请求内容 (第 6 节，见 [HTTP-CACHING]) 及相关 元数据 (第 8 节， 见 [HTTP])。

• 移除内容编码 (第 8.4 节， 见 [HTTP])。
• 根据请求的 Content-Type 字段中任何媒体 子类型后缀所指示的格式约定知识进行规范化（例如，"+json"；参见 第 4.2.8 节，位于 [RFC6838]）。
• 根据请求的 Content-Type 字段所指示的 内容本身的语义知识进行规范化。

请注意，任何此类转换都仅用于生成 缓存键；它不会更改请求本身。

客户端可以使用 "no-transform" 缓存指令 (第 5.2.1.6 节，见 [HTTP-CACHING])，表明它们希望 不发生此类转换（但请注意，此指令仅具有建议性质）。

请注意，缓存 QUERY 方法响应本质上比缓存 GET 响应更复杂，因为必须完整读取请求内容才能 确定缓存键。如果 QUERY 响应提供了 Location 响应字段 (第 2.4 节) 来指示等价资源的 URI (第 2.2 节)，客户端可以在 后续请求中改用 GET，从而简化处理。

QUERY 的范围请求语义与 GET 的范围请求语义相同，定义见 第 14 节，位于 [HTTP]。不过，字节范围请求 （本文撰写时唯一定义的范围单位）对于 QUERY 请求的结果几乎没有价值。

查询格式通常会定义自身限制结果集或对结果集分页的方式，例如 SQL 中的 "FETCH FIRST ... ROWS ONLY"。预计将使用这些内置功能 来替代 HTTP 范围请求。

IANA 已将 QUERY 方法添加到“超文本传输协议 (HTTP) 方法 注册表”，地址为 <http://www.iana.org/assignments/http-methods> （参见 第 16.3.1 节，位于 [HTTP]）。

IANA 已将 Accept-Query 字段添加到“超文本传输协议 (HTTP) 字段 名注册表”，地址为 <https://www.iana.org/assignments/http-fields> （参见 第 16.1.1 节，位于 [HTTP]）。

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

OPTIONS /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Allow: GET, QUERY, OPTIONS, HEAD

Allow 响应字段 (第 10.2.1 节， 见 [HTTP]) 表示 指定资源所支持的方法集合。

除了使用 OPTIONS，还有其他方式。例如，可以在事先不知道服务器是否支持的情况下， 尝试发送 QUERY 请求。服务器随后要么处理该 请求，要么以 4xx 状态响应，例如 405（不允许的方法，第 15.5.6 节， 见 [HTTP]），其中包含 Allow 响应字段。

HEAD /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Content-Type: application/xhtml
Accept-Query: application/x-www-form-urlencoded, application/sql

哪些请求方法的响应会包含 Accept-Query，取决于 所访问的资源。

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/xhtml
Accept: application/x-www-form-urlencoded, application/sql

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17
Location: /contacts/stored-queries/42
Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 Nov 2024, 16:10:24 GMT

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Date: Sun, 7 Sep 2025, 00:00:00 GMT
Content-Type: application/xslt+xml
Accept: text/csv

...使用 XSLT 的查询内容...

HTTP/1.1 200 OK
Date: Sun, 7 Sep 2025, 00:00:00 GMT
Location: /stored-queries/4815162342
Content-Type: text/csv
Accept-Query: "application/sql", "application/xslt+xml"
Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Encoding, Content-Type

decade, total, with errata, % with errata, average page count
1960, 26, 5, 19.2, 5.3
1970, 666, 18, 2.7, 6.1
1980, 376, 44, 11.7, 23.4
1990, 1593, 269, 16.9, 25.5
2000, 2888, 1048, 36.3, 27.3
2010, 2954, 895, 30.3, 26.1
2020, 1133, 230, 20.3, 26.2

这里，服务器已将路径 "/stored-queries/4815162342" 分配给等价 资源 (第 2.4 节)， 以供后续通过 GET 使用。

QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Date: Mon, 8, Sep 2025, 11:00:00 GMT
Content-Type: application/sql
Accept: text/csv
If-Modified-Since: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Type

...相同的查询，但使用 SQL...

HTTP/1.1 304 Not Modified
Date: Mon, 8 Sep 2025, 11:00:00 GMT
Content-Type: text/csv
Location: /stored-queries/4815162342
Accept-Query: "application/sql", "application/xslt+xml"
Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Type

GET /stored-queries/4815162342 HTTP/1.1
Host: example.org
Date: Sun, 21, Sep 2025, 12:08:00 GMT
Accept: text/csv
If-Modified-Since: Sun, 31 Aug 2025, 00:00:00 GMT

HTTP/1.1 200 OK
Date: Sun, 21, Sep 2025, 12:08:00 GMT
Content-Type: text/csv
Last-Modified: Thu, 18 Sep 2025, 19:56:00 GMT
Vary: Accept-Query, Content-Encoding, Content-Type

decade, total, with errata, % with errata, average page count
1960, 26, 5, 19.2, 5.3
1970, 666, 18, 2.7, 6.1
1980, 376, 44, 11.7, 23.4
1990, 1593, 269, 16.9, 25.5
2000, 2888, 1048, 36.3, 27.3
2010, 2954, 895, 30.3, 26.1
2020, 1133, 230, 20.3, 26.2

（请注意本十年对应行中的变化。）

下图说明了条件请求的用法，以及在 为等价资源分配 URI 时（且客户端利用 该 URI 时）可能产生的差异。虚构的字段名 "Validator" 仅用于演示 目的。

以下示例展示了对 JSON 形式的 [RFC8259] RFC 勘误数据库的请求。

以下请求使用可扩展样式表语言转换 (XSLT) 来提取 按年份和已定义的勘误类型汇总的勘误信息。

QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/xslt+xml
Accept: application/xml, text/csv

<transform xmlns="http://www.w3.org/1999/XSL/Transform"
  xmlns:j="http://www.w3.org/2005/xpath-functions"
  version="3.0">

  <output method="text"/>

  <param name="input"/>

  <variable name="json"
    select="json-to-xml(unparsed-text($input))"/>

  <variable name="sc">errata_status_code</variable>
  <variable name="sd">submit_date</variable>

  <template match="/">
    <text>year, total, rejected, verified, hdu, reported</text>
    <text>&#10;</text>
    <variable name="en" select="$json//j:map"/>
    <for-each-group select="$en"
      group-by="substring-before(j:string[@key=$sd],'-')">
      <sort select="current-grouping-key()"/>
      <variable name="year" select="current-grouping-key()"/>
      <variable name="errata" select=
        "$en[$year=substring-before(j:string[@key=$sd],'-')]"/>
      <value-of select="concat(
        $year,
        ', ',
        count($errata),
        ', ',
        count($errata['Rejected'=j:string[@key=$sc]]),
        ', ',
        count($errata['Verified'=j:string[@key=$sc]]),
        ', ',
        count(
          $errata['Held for Document Update'=j:string[@key=$sc]]),
        ', ',
        count($errata['Reported'=j:string[@key=$sc]]),
        '&#10;')"/>
    </for-each-group>
  </template>

</transform>

HTTP/1.1 200 OK
Content-Type: text/csv
Accept-Query: "application/jsonpath", "application/xslt+xml"
Date: Wed, 19 Feb 2025, 17:10:01 GMT

year, total, rejected, verified, hdu, reported
2000, 14, 0, 14, 0, 0
2001, 72, 1, 70, 1, 0
2002, 124, 8, 104, 12, 0
2003, 63, 0, 61, 2, 0
2004, 89, 1, 83, 5, 0
2005, 156, 10, 96, 50, 0
2006, 444, 54, 176, 214, 0
2007, 429, 48, 188, 193, 0
2008, 423, 52, 165, 206, 0
2009, 331, 39, 148, 144, 0
2010, 538, 80, 232, 222, 4
2011, 367, 47, 170, 150, 0
2012, 348, 54, 149, 145, 0
2013, 341, 61, 169, 106, 5
2014, 342, 73, 180, 72, 17
2015, 343, 79, 145, 89, 30
2016, 295, 46, 122, 82, 45
2017, 303, 46, 120, 84, 53
2018, 350, 61, 118, 98, 73
2019, 335, 47, 131, 94, 63
2020, 387, 68, 117, 123, 79
2021, 321, 44, 148, 63, 66
2022, 358, 37, 198, 40, 83
2023, 262, 38, 121, 33, 70
2024, 322, 33, 125, 23, 141
9999, 1, 0, 0, 1, 0

QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json

$..[
     ?@.errata_status_code=="Rejected"
     && @.submit_date>"2024"
   ]
   ["doc-id"]

HTTP/1.1 200 OK
Content-Type: application/json
Accept-Query: "application/jsonpath", "application/xslt+xml"
Date: Thu, 20 Feb 2025, 09:55:42 GMT
Last-Modified: Thu, 20 Feb 2025 06:10:01 GMT

[
  "RFC1185","RFC8407","RFC6350","RFC8467","RFC1157","RFC9543",
  "RFC9076","RFC7656","RFC2822","RFC9460","RFC2104","RFC6797",
  "RFC9499","RFC9557","RFC2131","RFC2328","RFC9001","RFC3325",
  "RFC9438","RFC2526","RFC2985","RFC7643","RFC9132","RFC6376",
  "RFC9110","RFC9460","RFC7748","RFC9497","RFC8463","RFC4035",
  "RFC7239","RFC9083","RFC9537","RFC9537","RFC9420","RFC9000",
  "RFC9656","RFC9110","RFC2324","RFC2549","RFC6797","RFC2549",
  "RFC8894"
]