Internet Engineering Task Force (IETF)                   P. van der Stok
Request for Comments: 8132                                    Consultant
Category: Standards Track                                     C. Bormann
ISSN: 2070-1721                                  Universitaet Bremen TZI
                                                               A. Sehgal
                                                            NAVOMI, Inc.
                                                              April 2017
        
Internet Engineering Task Force (IETF)                   P. van der Stok
Request for Comments: 8132                                    Consultant
Category: Standards Track                                     C. Bormann
ISSN: 2070-1721                                  Universitaet Bremen TZI
                                                               A. Sehgal
                                                            NAVOMI, Inc.
                                                              April 2017
        

PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)

受约束应用程序协议(CoAP)的修补程序和获取方法

Abstract

摘要

The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources.

RFC 7252中为受限应用程序协议(CoAP)定义的方法只允许访问完整的资源,而不允许访问部分资源。如果资源具有较大或复杂的数据,或者在需要资源连续性的情况下,不希望替换或请求整个资源。一些使用CoAP的应用程序需要访问部分资源。

This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource.

本规范定义了用于访问和更新部分资源的新CoAP方法FETCH、PATCH和iPATCH。

Status of This Memo

关于下段备忘

This is an Internet Standards Track document.

这是一份互联网标准跟踪文件。

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.

本文件是互联网工程任务组(IETF)的产品。它代表了IETF社区的共识。它已经接受了公众审查,并已被互联网工程指导小组(IESG)批准出版。有关互联网标准的更多信息,请参见RFC 7841第2节。

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc8132.

有关本文件当前状态、任何勘误表以及如何提供反馈的信息,请访问http://www.rfc-editor.org/info/rfc8132.

Copyright Notice

版权公告

Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.

版权所有(c)2017 IETF信托基金和确定为文件作者的人员。版权所有。

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件,因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本,并提供简化BSD许可证中所述的无担保。

Table of Contents

目录

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  FETCH . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  PATCH and iPATCH  . . . . . . . . . . . . . . . . . . . .   4
     1.3.  Requirements Language . . . . . . . . . . . . . . . . . .   5
     1.4.  Terminology and Acronyms  . . . . . . . . . . . . . . . .   5
   2.  FETCH Method  . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Response Codes  . . . . . . . . . . . . . . . . . . . . .   6
     2.2.  Error Handling  . . . . . . . . . . . . . . . . . . . . .   6
     2.3.  Option Numbers  . . . . . . . . . . . . . . . . . . . . .   7
       2.3.1.  The Content-Format Option . . . . . . . . . . . . . .   7
       2.3.2.  The ETag Option . . . . . . . . . . . . . . . . . . .   8
     2.4.  Working with Observe  . . . . . . . . . . . . . . . . . .   8
     2.5.  Working with Block  . . . . . . . . . . . . . . . . . . .   8
     2.6.  Building FETCH Requests . . . . . . . . . . . . . . . . .   8
     2.7.  A Simple Example for FETCH  . . . . . . . . . . . . . . .   8
   3.  PATCH and iPATCH Methods  . . . . . . . . . . . . . . . . . .   9
     3.1.  Simple Examples for PATCH and iPATCH  . . . . . . . . . .  12
     3.2.  Response Codes  . . . . . . . . . . . . . . . . . . . . .  14
     3.3.  Option Numbers  . . . . . . . . . . . . . . . . . . . . .  14
     3.4.  Error Handling  . . . . . . . . . . . . . . . . . . . . .  15
   4.  The New Set of CoAP Methods . . . . . . . . . . . . . . . . .  16
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  17
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  18
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  19
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  19
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  19
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  20
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21
        
   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  FETCH . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  PATCH and iPATCH  . . . . . . . . . . . . . . . . . . . .   4
     1.3.  Requirements Language . . . . . . . . . . . . . . . . . .   5
     1.4.  Terminology and Acronyms  . . . . . . . . . . . . . . . .   5
   2.  FETCH Method  . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Response Codes  . . . . . . . . . . . . . . . . . . . . .   6
     2.2.  Error Handling  . . . . . . . . . . . . . . . . . . . . .   6
     2.3.  Option Numbers  . . . . . . . . . . . . . . . . . . . . .   7
       2.3.1.  The Content-Format Option . . . . . . . . . . . . . .   7
       2.3.2.  The ETag Option . . . . . . . . . . . . . . . . . . .   8
     2.4.  Working with Observe  . . . . . . . . . . . . . . . . . .   8
     2.5.  Working with Block  . . . . . . . . . . . . . . . . . . .   8
     2.6.  Building FETCH Requests . . . . . . . . . . . . . . . . .   8
     2.7.  A Simple Example for FETCH  . . . . . . . . . . . . . . .   8
   3.  PATCH and iPATCH Methods  . . . . . . . . . . . . . . . . . .   9
     3.1.  Simple Examples for PATCH and iPATCH  . . . . . . . . . .  12
     3.2.  Response Codes  . . . . . . . . . . . . . . . . . . . . .  14
     3.3.  Option Numbers  . . . . . . . . . . . . . . . . . . . . .  14
     3.4.  Error Handling  . . . . . . . . . . . . . . . . . . . . .  15
   4.  The New Set of CoAP Methods . . . . . . . . . . . . . . . . .  16
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  17
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  18
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  19
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  19
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  19
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  20
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21
        
1. Introduction
1. 介绍

Similar to HTTP, the GET method defined in [RFC7252] for the Constrained Application Protocol (CoAP) only allows the specification of a URI and request parameters in CoAP options, not the transfer of a request payload detailing the request. This leads some applications to use POST where a cacheable, idempotent, safe request is actually desired.

与HTTP类似,[RFC7252]中为受限应用程序协议(CoAP)定义的GET方法只允许在CoAP选项中指定URI和请求参数,而不允许传输详细说明请求的请求负载。这导致一些应用程序在实际需要可缓存、幂等、安全的请求时使用POST。

Again, similar to the original specification of HTTP, the PUT method defined in [RFC7252] only allows a complete resource to be replaced. This also leads applications to use POST where a cacheable, possibly idempotent request is actually desired.

同样,与HTTP的原始规范类似,[RFC7252]中定义的PUT方法只允许替换完整的资源。这也导致应用程序在实际需要可缓存、可能是幂等请求的地方使用POST。

The present specification adds new CoAP methods: FETCH, to perform the equivalent of a GET with a request body; and the twin methods, PATCH and iPATCH, to modify parts of a CoAP resource.

目前的规范增加了新的CoAP方法:FETCH,以执行与请求主体的GET等价的操作;还有两种方法,PATCH和iPATCH,用于修改部分CoAP资源。

1.1. FETCH
1.1. 取来

The CoAP GET method [RFC7252] is used to obtain the representation of a resource, where the resource is specified by a URI and additional request parameters can also shape the representation. This has been modeled after the HTTP GET operation and the REST model in general.

CoAP GET方法[RFC7252]用于获取资源的表示,其中资源由URI指定,其他请求参数也可以塑造表示。这通常是在HTTPGET操作和REST模型之后建模的。

In HTTP, a resource is often used to search for information, and existing systems varyingly use the HTTP GET and POST methods to perform a search. Often, a POST method is used solely so that a larger set of parameters to the search can be supplied in the request body than can comfortably be transferred in the URI with a GET request. [HTTP-SEARCH] proposes a SEARCH method that is similar to GET in most properties but enables sending a request body, as is done with POST. The FETCH method defined in the present specification is inspired by [HTTP-SEARCH], which updates the definition and semantics of the HTTP SEARCH request method previously defined by [RFC5323]. However, there is no intention to limit FETCH to search-type operations, and the resulting properties may not be the same as those of HTTP SEARCH.

在HTTP中,经常使用资源来搜索信息,而现有的系统使用HTTP GET和POST方法来执行搜索。通常,只使用POST方法,以便在请求体中提供比在URI中使用GET请求传输更大的搜索参数集。[HTTP-SEARCH]提出了一种搜索方法,该方法类似于大多数属性中的GET,但允许发送请求正文,就像POST一样。本规范中定义的获取方法受[HTTP-SEARCH]的启发,它更新了[RFC5323]先前定义的HTTP搜索请求方法的定义和语义。但是,无意将FETCH限制为search类型的操作,结果属性可能与HTTP search的属性不同。

A major problem with GET is that the information that controls the request needs to be bundled up in some unspecified way into the URI. Using the request body for this information has a number of advantages:

GET的一个主要问题是,控制请求的信息需要以某种未指定的方式绑定到URI中。使用请求机构获取此信息有许多优点:

o The client can specify a media type (and a content coding) that enables the server to unambiguously interpret the request parameters in the context of that media type. Also, the request body is not limited by the character set limitations of URIs, which enables a more natural (and more efficient) representation of certain domain-specific parameters.

o 客户机可以指定媒体类型(和内容编码),使服务器能够在该媒体类型的上下文中明确地解释请求参数。此外,请求主体不受URI的字符集限制的限制,这使得某些特定于域的参数的表示更自然(更高效)。

o The request parameters are not limited by the maximum size of the URI. In HTTP, that is a problem, as the practical limit for this size varies. In CoAP, another problem is that the block-wise transfer is not available for transferring large URI options in multiple rounds.

o 请求参数不受URI的最大大小限制。在HTTP中,这是一个问题,因为此大小的实际限制不同。在CoAP中,另一个问题是分块传输不可用于在多轮中传输大URI选项。

As an alternative to using GET, many implementations make use of the POST method to perform extended requests (even if they are semantically idempotent, safe, and even cacheable) to be able to pass along the input parameters within the request payload as opposed to using the request URI.

作为使用GET的替代方法,许多实现使用POST方法来执行扩展请求(即使它们在语义上是幂等的、安全的,甚至是可缓存的),以便能够在请求负载内传递输入参数,而不是使用请求URI。

The FETCH method provides a solution that spans the gap between the use of GET and POST. As with POST, the input to the FETCH operation is passed along within the payload of the request rather than as part of the request URI. Unlike POST, however, the semantics of the FETCH method are more specifically defined.

FETCH方法提供了一个解决方案,跨越了GET和POST使用之间的鸿沟。与POST一样,FETCH操作的输入在请求的有效负载内传递,而不是作为请求URI的一部分传递。然而,与POST不同的是,FETCH方法的语义定义更为明确。

1.2. PATCH and iPATCH
1.2. 配线架和iPATCH

PATCH is also specified for HTTP in [RFC5789]. Most of the motivation for PATCH described in [RFC5789] also applies here. iPATCH is the idempotent version of PATCH.

[RFC5789]中还为HTTP指定了修补程序。[RFC5789]中描述的补丁的大部分动机也适用于此。iPATCH是PATCH的幂等版本。

The PUT method exists to overwrite a resource with completely new contents and cannot be used to perform partial changes. When using PUT for partial changes, proxies and caches, and even clients and servers, may get confused as to the result of the operation. PATCH was not adopted in an early design stage of CoAP; however, it has become necessary with the arrival of applications that require partial updates to resources (e.g., [COAP-MGMNT]). Using PATCH avoids transferring all data associated with a resource in case of modifications, thereby not burdening the constrained communication medium.

PUT方法用于用全新内容覆盖资源,不能用于执行部分更改。使用PUT进行部分更改时,代理和缓存,甚至客户端和服务器,可能会对操作结果感到困惑。在CoAP的早期设计阶段未采用补丁;然而,随着需要部分更新资源(例如[COAP-MGMNT])的应用程序的到来,这一点变得非常必要。使用补丁可以避免在修改时传输与资源相关联的所有数据,从而不会加重受约束的通信介质的负担。

This document relies on knowledge of the PATCH specification for HTTP [RFC5789]. This document provides extracts from [RFC5789] to make independent reading possible.

本文档依赖于HTTP[RFC5789]的补丁规范知识。本文件提供了[RFC5789]的摘录,使独立阅读成为可能。

1.3. Requirements Language
1.3. 需求语言

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“建议”、“不建议”、“可”和“可选”应按照[RFC2119]中的说明进行解释。

1.4. Terminology and Acronyms
1.4. 术语和首字母缩略词

This document uses terminology defined in [RFC5789] and [RFC7252].

本文件使用[RFC5789]和[RFC7252]中定义的术语。

Specifically, it uses the terms "safe" and "idempotent" as defined in Section 5.1 of [RFC7252]. (Further discussion of safe and idempotent methods can now be found in Sections 4.2.1 and 4.2.2 of [RFC7231], respectively; the implications of idempotence of methods on server implementations are also discussed in Section 4.5 of [RFC7252].)

具体而言,它使用了[RFC7252]第5.1节中定义的术语“安全”和“幂等”。(关于安全方法和幂等方法的进一步讨论,请参见[RFC7231]的第4.2.1节和第4.2.2节;关于方法幂等性对服务器实现的影响,请参见[RFC7252]的第4.5节。)

2. FETCH Method
2. 获取方法

The CoAP FETCH method is used to obtain a representation of a resource, specified by a number of request parameters. Unlike the CoAP GET method, which requests that a server return a representation of the resource identified by the effective request URI (as defined by [RFC7252]), the FETCH method is used by a client to ask the server to produce a representation as described by the request parameters (including the request options and the payload) based on the resource specified by the effective request URI. The payload returned in response to a FETCH cannot be assumed to be a complete representation of the resource identified by the effective request URI, i.e., it cannot be used by a cache as a payload to be returned by a GET request.

CoAP FETCH方法用于获取由多个请求参数指定的资源表示。与CoAP GET方法不同,CoAP GET方法要求服务器返回由有效请求URI(由[RFC7252]定义)标识的资源表示形式,客户机使用FETCH方法要求服务器生成请求参数(包括请求选项和有效负载)描述的表示形式基于有效请求URI指定的资源。不能假设为响应提取而返回的有效负载是由有效请求URI标识的资源的完整表示,也就是说,缓存不能将其用作GET请求返回的有效负载。

Together with the request options, the body of the request (which may be constructed from multiple payloads using the block protocol [RFC7959]) defines the request parameters. With the FETCH method, implementations may submit a request body of any media type that is defined with the semantics of selecting information from a resource in such a FETCH request; it is outside the scope of this document how information about media types admissible for the specific resource is obtained by the client (although we can hint that form relations [CORE-APP] might be a preferred way). It is RECOMMENDED that any discovery method that allows a client to find out that the server supports FETCH also provides information regarding what FETCH payload media types are applicable.

与请求选项一起,请求主体(可以使用块协议[RFC7959]从多个有效负载构建)定义请求参数。使用该获取方法,实现可以提交任何媒体类型的请求体,该媒体类型是用从该获取请求中的资源选择信息的语义定义的;客户机如何获取特定资源可接受的媒体类型信息不在本文档的范围内(尽管我们可以暗示,表单关系[CORE-APP]可能是首选方式)。建议任何允许客户端发现服务器支持FETCH的发现方法也提供有关适用的FETCH有效负载媒体类型的信息。

FETCH requests are both safe and idempotent with regards to the resource identified by the request URI. That is, the performance of a FETCH is not intended to alter the state of the targeted resource. (However, while processing a FETCH request, a server can be expected to allocate computing and memory resources or even create additional server resources through which the response to the search can be retrieved.)

对于由请求URI标识的资源,获取请求既安全又幂等。也就是说,获取的性能并不是为了改变目标资源的状态。(但是,在处理获取请求时,服务器可能会分配计算和内存资源,甚至创建额外的服务器资源,通过这些资源可以检索对搜索的响应。)

A successful response to a FETCH request is expected to provide some indication as to the final disposition of the requested operation. If a successful response includes a body payload, the payload is expected to describe the results of the FETCH operation.

对提取请求的成功响应将提供有关请求操作的最终处置的一些指示。如果成功的响应包括主体有效载荷,则该有效载荷将描述提取操作的结果。

Depending on the response code as defined by [RFC7252], the response to a FETCH request is cacheable; the request body is part of the cache key. Specifically, 2.05 (Content) response codes (the responses for which are cacheable) are a typical way to respond to a FETCH request. (Note that this aspect differs markedly from [HTTP-SEARCH] and also that caches that cannot use the request payload as part of the cache key will not be able to cache responses to FETCH requests at all.) The Max-Age option in the response has equivalent semantics to its use in a GET.

根据[RFC7252]定义的响应代码,对提取请求的响应是可缓存的;请求主体是缓存密钥的一部分。具体而言,2.05(内容)响应代码(响应可缓存)是响应获取请求的典型方式。(请注意,此方面与[HTTP-SEARCH]明显不同,并且不能将请求有效负载用作缓存密钥的一部分的缓存将无法缓存响应以获取请求。)响应中的Max Age选项的语义与其在GET中的使用相同。

The semantics of the FETCH method change to a "conditional FETCH" if the request message includes an If-Match or If-None-Match option [RFC7252]. A conditional FETCH requests that the query be performed only under the circumstances described by the conditional option(s). It is important to note, however, that such conditions are evaluated against the state of the target resource itself as opposed to the results of the FETCH operation.

如果请求消息包含if-Match或if-None-Match选项[RFC7252],则提取方法的语义将更改为“条件提取”。条件提取请求仅在条件选项描述的情况下执行查询。但是,需要注意的是,这些条件是根据目标资源本身的状态而不是提取操作的结果来评估的。

2.1. Response Codes
2.1. 响应代码

FETCH for CoAP adopts the response codes as specified in Sections 5.9 and 12.1.2 of [RFC7252] as well as the additional response codes mentioned in Section 2.2.

CoAP的FETCH采用[RFC7252]第5.9节和第12.1.2节中规定的响应代码以及第2.2节中提到的其他响应代码。

2.2. Error Handling
2.2. 错误处理

A FETCH request may fail under certain known conditions. Beyond the conditions already defined in [RFC7252] for GET, noteworthy ones are:

在某些已知条件下,提取请求可能会失败。除了[RFC7252]中已经为GET定义的条件外,值得注意的是:

Malformed FETCH payload: If a server determines that the payload provided with a FETCH request is not properly formatted, it can return a 4.00 (Bad Request) CoAP error. The definition of a malformed payload depends upon the CoAP Content-Format specified with the request.

格式错误的获取有效负载:如果服务器确定与获取请求一起提供的有效负载格式不正确,则可能返回4.00(错误请求)CoAP错误。格式错误的有效负载的定义取决于请求中指定的CoAP内容格式。

Unsupported FETCH payload: In case a client sends a payload that is inappropriate for the resource identified by the Request-URI, the server can return a 4.15 (Unsupported Content-Format) CoAP error. The server can determine if the payload is supported by checking the CoAP Content-Format specified with the request.

不支持的获取负载:如果客户端发送的负载与请求URI标识的资源不匹配,服务器可能会返回4.15(不支持的内容格式)CoAP错误。服务器可以通过检查请求中指定的CoAP内容格式来确定是否支持有效负载。

Unprocessable request: This situation occurs when the payload of a FETCH request is determined to be valid (i.e., well-formed and supported) but the server is unable to or is incapable of processing the request. The server can return a 4.22 (Unprocessable Entity) CoAP error. In situations when the server has insufficient computing resources to complete the request successfully, it can return a 4.13 (Request Entity Too Large) CoAP error (see also below). If there are more specific errors that provide additional insight into the problem, then those should be used.

无法处理的请求:当获取请求的有效负载被确定为有效(即格式良好且受支持),但服务器无法或无法处理该请求时,就会发生这种情况。服务器可能返回4.22(不可处理实体)CoAP错误。在服务器没有足够的计算资源来成功完成请求的情况下,它可能会返回4.13(请求实体太大)CoAP错误(另请参见下文)。如果有更具体的错误提供了对问题的进一步了解,那么应该使用这些错误。

Request too large: If the payload of the FETCH request is larger than a CoAP server can process, then it can return the 4.13 (Request Entity Too Large) CoAP error.

请求太大:如果FETCH请求的负载大于CoAP服务器可以处理的负载,那么它可以返回4.13(请求实体太大)CoAP错误。

It is possible that other error situations not mentioned here are encountered by a CoAP server while processing the FETCH request. In these situations, other appropriate CoAP response codes can also be returned.

在处理提取请求时,CoAP服务器可能会遇到此处未提及的其他错误情况。在这些情况下,还可以返回其他适当的CoAP响应代码。

2.3. Option Numbers
2.3. 选项编号

FETCH for CoAP adopts the option numbers as specified in Sections 5.10 and 12.2 of [RFC7252].

CoAP的FETCH采用[RFC7252]第5.10节和第12.2节规定的选项编号。

Generally, options defined for GET act in an analogous way for FETCH. Two specific cases are called out in the rest of this section.

通常,为GET定义的选项对FETCH的作用类似。本节其余部分将列出两个具体案例。

2.3.1. The Content-Format Option
2.3.1. “内容格式”选项

A FETCH request MUST include a Content-Format option (see Section 5.10.3 of [RFC7252]) to specify the media type and content coding of the request body. (Typically, the media type will have been specifically designed to specify details for a selection or a search on a resource.)

提取请求必须包括内容格式选项(见[RFC7252]第5.10.3节),以指定请求正文的媒体类型和内容编码。(通常,媒体类型专门设计用于指定资源选择或搜索的详细信息。)

2.3.2. The ETag Option
2.3.2. ETag选项

The ETag option on a FETCH result has the same semantics as defined in Section 5.10.6 of [RFC7252]. In particular, its use as a response option describes the "tagged representation", which for FETCH is the same as the "selected representation". The FETCH payload is input to that selection process and therefore needs to be part of the cache key. Similarly, the use of ETag as a request option can elicit a 2.03 (Valid) response if the representation associated with the ETag would still be selected by the FETCH request (including its payload).

获取结果上的ETag选项具有与[RFC7252]第5.10.6节中定义的相同语义。特别是,它作为响应选项的使用描述了“标记的表示法”,对于获取,它与“选定的表示法”相同。提取有效负载是该选择过程的输入,因此需要是缓存密钥的一部分。类似地,如果FETCH请求(包括其有效负载)仍然选择与ETag相关联的表示,则将ETag用作请求选项可能会引发2.03(有效)响应。

2.4. Working with Observe
2.4. 与观察者合作

The Observe option [RFC7641] can be used with a FETCH request as it can be used with a GET request.

Observe选项[RFC7641]可以与FETCH请求一起使用,就像它可以与GET请求一起使用一样。

2.5. Working with Block
2.5. 使用积木

The Block1 option [RFC7959] can be used with a FETCH request as it would be used with a POST request; the Block2 option can then be used as it would with GET or POST.

Block1选项[RFC7959]可用于获取请求,就像用于POST请求一样;Block2选项可以像GET或POST一样使用。

2.6. Building FETCH Requests
2.6. 生成获取请求

One property of FETCH that may be non-obvious is that a FETCH request cannot be generated from a link alone; the client also needs a way to generate the request payload. Again, form relations [CORE-APP] may be able to fill parts of this gap.

FETCH的一个不明显的特性是,不能仅从链接生成FETCH请求;客户端还需要一种生成请求有效负载的方法。同样,表单关系[CORE-APP]可能能够填补部分空白。

2.7. A Simple Example for FETCH
2.7. FETCH的一个简单示例

The FETCH method needs a media type for its payload (as expressed by the Content-Format request option) that specifies the search query in similar detail as is shown for the PATCH payload in the PATCH example in Section 3.1. ([HTTP-SEARCH] invents a "text/query" format based on some hypothetical SQL dialect for its examples.)

FETCH方法需要一个媒体类型作为其有效负载(由Content Format request选项表示),该媒体类型指定搜索查询的详细信息,如第3.1节补丁示例中补丁有效负载所示。([HTTP-SEARCH]根据一些假设的SQL方言发明了一种“文本/查询”格式作为示例。)

The example below illustrates retrieval of a subset of a JSON [RFC7159] object (the same object as used in Section 3.1). Using a hypothetical media type "application/example-map-keys+json" (with a Content-Format ID of NNN, which is not defined as this is just an example), the client specifies the items in the object that it wants: it supplies a JSON array that gives the map keys for these items. A resource located at <coap://www.example.com/object> can be represented by a JSON document that we will consider as the target of the FETCH. The client wants to learn the contents of the single map key "foo" within this target:

下面的示例说明了如何检索JSON[RFC7159]对象的子集(与第3.1节中使用的对象相同)。使用假设的媒体类型“application/example map keys+json”(内容格式ID为NNN,未定义为这只是一个示例),客户机指定其所需对象中的项:它提供一个json数组,该数组为这些项提供映射键。位于以下位置的资源:<coap://www.example.com/object>可以用JSON文档来表示,我们将将其视为获取的目标。客户端希望了解此目标中单个映射键“foo”的内容:

   {
     "x-coord": 256,
     "y-coord": 45,
     "foo": ["bar","baz"]
   }
        
   {
     "x-coord": 256,
     "y-coord": 45,
     "foo": ["bar","baz"]
   }
        

FETCH Example: JSON Document Returned by GET

获取示例:GET返回的JSON文档

The example FETCH request specifies a single top-level member desired by giving its map key as the sole element of the "example-map-keys" payload:

示例获取请求通过将其映射键作为“示例映射键”负载的唯一元素来指定所需的单个顶级成员:

   FETCH CoAP://www.example.com/object
   Content-Format: NNN (application/example-map-keys+json)
   Accept: application/json
   [
     "foo"
   ]
        
   FETCH CoAP://www.example.com/object
   Content-Format: NNN (application/example-map-keys+json)
   Accept: application/json
   [
     "foo"
   ]
        

FETCH Example: Request

获取示例:请求

The server returns a subset document with just the selected member:

服务器返回仅包含选定成员的子集文档:

   2.05 Content
   Content-Format: 50 (application/json)
   {
     "foo": ["bar","baz"]
   }
        
   2.05 Content
   Content-Format: 50 (application/json)
   {
     "foo": ["bar","baz"]
   }
        

FETCH Example: Response with Subset JSON Document

获取示例:带有JSON文档子集的响应

By the logic of this example, the requester could have entered more than one map key into the request payload array and would have received a more complete subset of the top-level JSON object that is representing the resource.

根据本例的逻辑,请求者可以在请求有效负载数组中输入多个映射键,并接收表示资源的顶级JSON对象的更完整子集。

3. PATCH and iPATCH Methods
3. 补丁和iPATCH方法

The PATCH and iPATCH methods request that a set of changes described in the request payload be applied to the target resource of the request. The set of changes is represented in a format identified by a media type. If the Request-URI does not point to an existing resource, the server MAY create a new resource with that URI, depending on the PATCH document type (whether it can logically modify a null resource) and permissions, as well as other conditions such as the degree of control the server gives clients in creating new

PATCH和iPATCH方法请求将请求有效负载中描述的一组更改应用于请求的目标资源。更改集以媒体类型标识的格式表示。如果请求URI未指向现有资源,则服务器可能会使用该URI创建新资源,具体取决于修补程序文档类型(是否可以在逻辑上修改空资源)和权限,以及其他条件,如服务器在创建新资源时给予客户端的控制程度

entries in its URI space (see also Section 3.4). Creation of a new resource would result in a 2.01 (Created) response code dependent on the PATCH document type.

其URI空间中的条目(另请参见第3.4节)。根据修补程序文档类型,创建新资源将产生2.01(已创建)响应代码。

Restrictions to a PATCH or iPATCH request can be made by including the If-Match or If-None-Match options in the request (see Sections 5.10.8.1 and 5.10.8.2 of [RFC7252]). If the resource could not be created or modified, then an appropriate error response code SHOULD be sent.

可通过在请求中包含“如果匹配”或“如果不匹配”选项来限制补丁或iPATCH请求(参见[RFC7252]第5.10.8.1节和第5.10.8.2节)。如果无法创建或修改资源,则应发送适当的错误响应代码。

The difference between the PUT and PATCH requests is documented in [RFC5789]. When a request is intended to effect a partial update of a given resource, clients cannot use PUT while supplying just the update, but they might be able to use PATCH or iPATCH.

PUT和修补程序请求之间的差异记录在[RFC5789]中。当请求旨在对给定资源进行部分更新时,客户端在仅提供更新时不能使用PUT,但它们可能可以使用PATCH或iPATCH。

The PATCH method is "not safe" and "not idempotent", as is the HTTP PATCH method specified in [RFC5789].

与[RFC5789]中指定的HTTP修补方法一样,修补方法是“不安全”和“不幂等”的。

The iPATCH method is not safe but idempotent, as with the CoAP PUT method specified in Section 5.8.3 of [RFC7252].

iPATCH方法不安全,但与[RFC7252]第5.8.3节中规定的CoAP PUT方法一样是幂等的。

A client can mark a request as idempotent by using the iPATCH method instead of the PATCH method. This is the only difference between the two. The indication of idempotence may enable the server to keep less state about the interaction; some constrained servers may only implement the iPATCH variant for this reason.

客户端可以使用iPATCH方法而不是PATCH方法将请求标记为幂等。这是两者之间唯一的区别。幂等性的指示可以使服务器保持较少的交互状态;因此,某些受约束的服务器可能仅实施iPATCH变体。

PATCH and iPATCH are both atomic. The server MUST apply the entire set of changes atomically and never provide a partially modified representation to a concurrently executed GET request. Given the constrained nature of the servers, most servers will only execute CoAP requests consecutively, thus preventing a concurrent partial overlapping of request modifications. In other words, modifications MUST NOT be applied to the server state when an error occurs or when only a partial execution is possible on the resources present in the server.

PATCH和iPATCH都是原子的。服务器必须以原子方式应用整个更改集,并且决不能向并发执行的GET请求提供部分修改的表示。考虑到服务器的受限性质,大多数服务器将仅连续执行CoAP请求,从而防止请求修改的并发部分重叠。换句话说,当发生错误或在服务器中存在的资源上只能部分执行时,不能对服务器状态应用修改。

The atomicity applies to a single server. When a PATCH or iPATCH request is multicast to a set of servers, each server can either execute all required modifications or not. It is not required that all servers execute all modifications or none. An Atomic Commit protocol that provides multiple server atomicity is out of scope.

原子性适用于单个服务器。当一个补丁或iPATCH请求被多播到一组服务器时,每个服务器都可以执行或不执行所有必需的修改。不要求所有服务器执行所有修改或不执行任何修改。提供多服务器原子性的原子提交协议超出范围。

A PATCH or iPATCH response can invalidate a cache in a similar manner to the PUT response. For the successful (2.xx) response codes, PATCH or iPATCH have the following caching behavior:

补丁或iPATCH响应可以以与PUT响应类似的方式使缓存失效。对于成功的(2.xx)响应代码,PATCH或iPATCH具有以下缓存行为:

o A 2.01 (Created) response invalidates any cache entry for the resource indicated by the Location-* options; the payload is a representation of the action result.

o 2.01(已创建)响应使Location-*选项指示的资源的任何缓存项无效;有效载荷是动作结果的表示。

o A 2.04 (Changed) response invalidates any cache entry for the target resource; the payload is a representation of the action result.

o 2.04(更改)响应使目标资源的任何缓存项无效;有效载荷是动作结果的表示。

There is no guarantee that a resource can be modified with PATCH or iPATCH. Servers MUST ensure that a received PATCH body is appropriate for the type of resource identified by the target resource of the request.

无法保证可以使用PATCH或iPATCH修改资源。服务器必须确保收到的补丁正文适合于请求的目标资源标识的资源类型。

It is RECOMMENDED that any discovery method that allows a client to find out that the server supports one of PATCH and iPATCH also provide information regarding what PATCH payload media types are applicable and which of the two methods are implemented by the server for each of these media types.

建议任何允许客户端发现服务器支持PATCH和iPATCH中的一种的发现方法也提供有关适用的补丁有效负载介质类型以及服务器为每种介质类型实施的两种方法中的哪一种的信息。

Servers that do not rely on the idempotence of iPATCH can easily support both PATCH and iPATCH, and it is RECOMMENDED they do so. This is inexpensive to do, as, for iPATCH, there is no requirement on the server to check that the client's intention that the request be idempotent is fulfilled (although there is diagnostic value in that check, so a less-constrained implementation may want to perform it).

不依赖iPATCH幂等性的服务器可以轻松支持PATCH和iPATCH,建议这样做。这样做成本较低,因为对于iPATCH,服务器上不需要检查客户端是否满足了请求幂等的意图(尽管该检查具有诊断价值,因此约束较少的实现可能希望执行该检查)。

3.1. Simple Examples for PATCH and iPATCH
3.1. PATCH和iPATCH的简单示例

The example is taken over from [RFC6902], which specifies a JSON notation for PATCH operations. A resource located at <coap://www.example.com/object> contains a target JSON document.

该示例取自[RFC6902],它为补丁操作指定了JSON符号。位于以下位置的资源:<coap://www.example.com/object>包含一个目标JSON文档。

   JSON document original state:
       {
         "x-coord": 256,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   JSON document original state:
       {
         "x-coord": 256,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   REQ: iPATCH CoAP://www.example.com/object
   Content-Format: 51 (application/json-patch+json)
       [
         { "op":"replace", "path":"x-coord", "value":45}
       ]
        
   REQ: iPATCH CoAP://www.example.com/object
   Content-Format: 51 (application/json-patch+json)
       [
         { "op":"replace", "path":"x-coord", "value":45}
       ]
        

RET: CoAP 2.04 Changed

RET:CoAP 2.04已更改

   JSON document final state:
       {
         "x-coord": 45,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   JSON document final state:
       {
         "x-coord": 45,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        

This example illustrates use of an idempotent modification to the x-coord member of the existing resource "object". The 2.04 (Changed) response code conforms with the CoAP PUT method.

此示例演示了对现有资源“对象”的x-coord成员使用幂等修改。2.04(更改)响应代码符合CoAP PUT方法。

The same example using the Content-Format application/merge-patch+json from [RFC7396] looks like the following:

使用[RFC7396]中的内容格式应用程序/合并补丁+json的相同示例如下所示:

   JSON document original state:
       {
         "x-coord": 256,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   JSON document original state:
       {
         "x-coord": 256,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   REQ: iPATCH CoAP://www.example.com/object
   Content-Format: 52 (application/merge-patch+json)
        { "x-coord":45}
        
   REQ: iPATCH CoAP://www.example.com/object
   Content-Format: 52 (application/merge-patch+json)
        { "x-coord":45}
        

RET: CoAP 2.04 Changed

RET:CoAP 2.04已更改

   JSON document final state:
       {
         "x-coord": 45,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   JSON document final state:
       {
         "x-coord": 45,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        

The examples show the use of the iPATCH method, but the use of the PATCH method would have led to the same result. Below, a non-idempotent modification is shown. Because the action is non-idempotent, iPATCH returns an error, while PATCH executes the action.

示例显示了iPATCH方法的使用,但使用PATCH方法也会产生相同的结果。下面显示了一个非幂等修改。由于该操作是非幂等的,iPATCH将返回一个错误,而PATCH将执行该操作。

   JSON document original state:
       {
         "x-coord": 256,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   JSON document original state:
       {
         "x-coord": 256,
         "y-coord": 45,
         "foo": ["bar","baz"]
       }
        
   REQ: iPATCH CoAP://www.example.com/object
   Content-Format: 51 (application/json-patch+json)
       [
         { "op":"add","path":"foo/1","value":"bar"}
       ]
   RET: CoAP 4.00 Bad Request
   Diagnostic payload: Patch format not idempotent
        
   REQ: iPATCH CoAP://www.example.com/object
   Content-Format: 51 (application/json-patch+json)
       [
         { "op":"add","path":"foo/1","value":"bar"}
       ]
   RET: CoAP 4.00 Bad Request
   Diagnostic payload: Patch format not idempotent
        

JSON document final state is unchanged

JSON文档最终状态不变

   REQ: PATCH CoAP://www.example.com/object
   Content-Format: 51 (application/json-patch+json)
       [
         { "op":"add","path":"foo/1","value":"bar"}
       ]
   RET: CoAP 2.04 Changed
        
   REQ: PATCH CoAP://www.example.com/object
   Content-Format: 51 (application/json-patch+json)
       [
         { "op":"add","path":"foo/1","value":"bar"}
       ]
   RET: CoAP 2.04 Changed
        
   JSON document final state:
       {
         "x-coord": 45,
         "y-coord": 45,
         "foo": ["bar","bar","baz"]
       }
        
   JSON document final state:
       {
         "x-coord": 45,
         "y-coord": 45,
         "foo": ["bar","bar","baz"]
       }
        
3.2. Response Codes
3.2. 响应代码

PATCH and iPATCH for CoAP adopt the response codes as specified in Sections 5.9 and 12.1.2 of [RFC7252] and add 4.09 (Conflict) and 4.22 (Unprocessable Entity) with the semantics specified in Section 3.4 of the present specification.

CoAP的PATCH和iPATCH采用[RFC7252]第5.9节和第12.1.2节中规定的响应代码,并添加4.09(冲突)和4.22(不可处理实体),其语义在本规范第3.4节中规定。

3.3. Option Numbers
3.3. 选项编号

PATCH and iPATCH for CoAP adopt the option numbers as specified in Sections 5.10 and 12.2 of [RFC7252].

CoAP的配线架和iPATCH采用[RFC7252]第5.10节和第12.2节规定的选项编号。

3.4. Error Handling
3.4. 错误处理

A PATCH or iPATCH request may fail under certain known conditions. These situations should be dealt with as expressed below.

在某些已知条件下,补丁或iPATCH请求可能会失败。这些情况应按以下方式处理。

Malformed PATCH or iPATCH payload: If a server determines that the payload provided with a PATCH or iPATCH request is not properly formatted, it can return a 4.00 (Bad Request) CoAP error. The definition of a malformed payload depends upon the CoAP Content-Format specified with the request.

格式错误的修补程序或iPATCH负载:如果服务器确定修补程序或iPATCH请求提供的负载格式不正确,则可能返回4.00(错误请求)CoAP错误。格式错误的有效负载的定义取决于请求中指定的CoAP内容格式。

Unsupported PATCH or iPATCH payload: In case a client sends a payload that is inappropriate for the resource identified by the Request-URI, the server can return a 4.15 (Unsupported Content-Format) CoAP error. The server can determine if the payload is supported by checking the CoAP Content-Format specified with the request.

不支持的修补程序或iPATCH负载:如果客户端发送的负载与请求URI标识的资源不匹配,服务器可能会返回4.15(不支持的内容格式)CoAP错误。服务器可以通过检查请求中指定的CoAP内容格式来确定是否支持有效负载。

Unprocessable request: This situation occurs when the payload of a PATCH request is determined to be valid (i.e., well-formed and supported) but the server is unable to or is incapable of processing the request. The server can return a 4.22 (Unprocessable Entity) CoAP error. More specific scenarios might include situations such as:

无法处理的请求:当补丁请求的有效负载被确定为有效(即格式良好且受支持),但服务器无法或无法处理该请求时,就会发生这种情况。服务器可能返回4.22(不可处理实体)CoAP错误。更具体的场景可能包括以下情况:

* the server has insufficient computing resources to complete the request successfully -- 4.13 (Request Entity Too Large) CoAP response code (see below); or

* 服务器没有足够的计算资源来成功完成请求——4.13(请求实体太大)CoAP响应代码(见下文);或

* the resource specified in the request becomes invalid by applying the payload -- 4.09 (Conflict) CoAP response code (see "Conflicting state" below)).

* 通过应用有效负载--4.09(冲突)CoAP响应代码(请参阅下面的“冲突状态”),请求中指定的资源将无效。

In case there are more specific errors that provide additional insight into the problem, then those should be used.

如果有更具体的错误提供了对问题的进一步了解,那么应该使用这些错误。

Resource not found: The 4.04 (Not Found) error should be returned if the payload of a PATCH request cannot be applied to a non-existent resource.

未找到资源:如果补丁请求的有效负载无法应用于不存在的资源,则应返回4.04(未找到)错误。

Failed precondition: In case the client uses the conditional If-Match or If-None-Match option to define a precondition for the PATCH request, and that precondition fails, then the server can return the 4.12 (Precondition Failed) CoAP error.

失败的前提条件:如果客户端使用条件If Match或If None Match选项为补丁请求定义前提条件,并且该前提条件失败,则服务器可以返回4.12(前提条件失败)CoAP错误。

Request too large: If the payload of the PATCH request is larger than a CoAP server can process, then it can return the 4.13 (Request Entity Too Large) CoAP error.

请求太大:如果补丁请求的负载大于CoAP服务器可以处理的负载,那么它可以返回4.13(请求实体太大)CoAP错误。

Conflicting state: If the modification specified by a PATCH or iPATCH request causes the resource to enter an inconsistent state that the server cannot resolve, the server can return the 4.09 (Conflict) CoAP response. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict. The server MAY return the actual resource state to provide the client with the means to create a new consistent resource state. Such a situation might be encountered when a structural modification is applied to a configuration data store but the structures being modified do not exist.

冲突状态:如果补丁或iPATCH请求指定的修改导致资源进入服务器无法解决的不一致状态,服务器可以返回4.09(冲突)CoAP响应。服务器应该生成一个有效负载,其中包含足够的信息,以便用户识别冲突的来源。服务器可以返回实际的资源状态,以向客户端提供创建新的一致资源状态的方法。当结构修改应用于配置数据存储,但被修改的结构不存在时,可能会遇到这种情况。

Concurrent modification: Resource-constrained devices might need to process requests in the order they are received. In case requests are received concurrently to modify the same resource but they cannot be queued, the server can return a 5.03 (Service Unavailable) CoAP response code.

并发修改:资源受限的设备可能需要按接收顺序处理请求。如果同时收到修改同一资源的请求,但这些请求无法排队,服务器可以返回5.03(服务不可用)CoAP响应代码。

Conflict handling failure: If the modification implies the reservation of resources or the wait time for conditions to become true leads to a too-long request execution time, the server can return a 5.03 (Service Unavailable) response code.

冲突处理失败:如果修改意味着保留资源或等待条件变为真的时间导致请求执行时间过长,服务器可以返回5.03(服务不可用)响应代码。

It is possible that other error situations not mentioned here are encountered by a CoAP server while processing the PATCH request. In these situations, other appropriate CoAP status codes can also be returned.

在处理补丁请求时,CoAP服务器可能会遇到此处未提及的其他错误情况。在这些情况下,还可以返回其他适当的CoAP状态代码。

4. The New Set of CoAP Methods
4. 一组新的CoAP方法

Adding three new methods to CoAP's existing four may seem like a major change. However, FETCH and the two PATCH variants fit well into the REST paradigm and have been anticipated on the HTTP side. Adding both a non-idempotent and an idempotent PATCH variant allows interoperability with HTTP's PATCH method to be kept and allows the use/indication of an idempotent PATCH when that is possible, which saves significant effort on the server side.

在CoAP现有的四种方法基础上增加三种新方法似乎是一个重大变化。然而,FETCH和这两个补丁变体非常适合REST范式,并且已经在HTTP端得到了预期。添加非幂等和幂等修补程序变体可以保持与HTTP修补程序方法的互操作性,并允许在可能的情况下使用/指示幂等修补程序,从而节省服务器端的大量工作。

Interestingly, the three new methods fit into the old table of methods with a surprising similarity in the idempotence and safety attributes:

有趣的是,这三种新方法与旧的方法表相吻合,在幂等性和安全属性方面具有惊人的相似性:

           +------+--------+------+--------+------+------------+
           | Code | Name   | Code | Name   | safe | idempotent |
           +------+--------+------+--------+------+------------+
           | 0.01 | GET    | 0.05 | FETCH  | yes  | yes        |
           | 0.02 | POST   | 0.06 | PATCH  | no   | no         |
           | 0.03 | PUT    | 0.07 | iPATCH | no   | yes        |
           | 0.04 | DELETE |      |        | no   | yes        |
           +------+--------+------+--------+------+------------+
        
           +------+--------+------+--------+------+------------+
           | Code | Name   | Code | Name   | safe | idempotent |
           +------+--------+------+--------+------+------------+
           | 0.01 | GET    | 0.05 | FETCH  | yes  | yes        |
           | 0.02 | POST   | 0.06 | PATCH  | no   | no         |
           | 0.03 | PUT    | 0.07 | iPATCH | no   | yes        |
           | 0.04 | DELETE |      |        | no   | yes        |
           +------+--------+------+--------+------+------------+
        
5. Security Considerations
5. 安全考虑

This section analyzes the possible threats to the CoAP FETCH and PATCH or iPATCH methods. It is meant to inform protocol and application developers about the security limitations of CoAP FETCH and PATCH or iPATCH as described in this document.

本节分析了CoAP获取和修补或iPATCH方法可能面临的威胁。它旨在告知协议和应用程序开发人员本文档中所述的CoAP获取和修补或iPATCH的安全限制。

The FETCH method is subject to the same general security considerations as all CoAP methods as described in Section 11 of [RFC7252]. Specifically, the security considerations for FETCH are closest to those of GET, except that the FETCH request carries a payload that may need additional protection. The payload of a FETCH request may reveal more detailed information about the specific portions of a resource of interest to the requester than a GET request for the entire resource would; this may mean that confidentiality protection of the request by Datagram Transport Layer Security (DTLS) or other means is needed for FETCH where it wouldn't be needed for GET.

FETCH方法与[RFC7252]第11节中所述的所有CoAP方法一样,需要遵守相同的一般安全注意事项。具体地说,FETCH的安全注意事项与GET的安全注意事项最接近,只是FETCH请求携带可能需要额外保护的负载。取回请求的有效载荷可揭示关于请求者感兴趣的资源的特定部分的比对整个资源的取回请求更详细的信息;这可能意味着数据报传输层安全性(DTLS)或其他方法需要对请求进行保密保护,以获取GET不需要的内容。

The PATCH and iPATCH methods are subject to the same general security considerations as all CoAP methods as described in Section 11 of [RFC7252]. The specific security considerations for PATCH or iPATCH are nearly identical to the security considerations for PUT [RFC7252]; the security considerations of Section 5 of [RFC5789] also apply to PATCH and iPATCH. Specifically, there is likely to be a need for authorizing requests (possibly through access control and/or authentication) and for ensuring that data is not corrupted through transport errors or through accidental overwrites. The mechanisms used for PUT can be used for PATCH or iPATCH as well.

与[RFC7252]第11节所述的所有CoAP方法一样,PATCH和iPATCH方法也需要遵守相同的一般安全注意事项。PATCH或iPATCH的具体安全注意事项与PUT[RFC7252]的安全注意事项几乎相同;[RFC5789]第5节的安全注意事项也适用于PATCH和iPATCH。具体而言,可能需要授权请求(可能通过访问控制和/或身份验证),并确保数据不会因传输错误或意外覆盖而损坏。用于PUT的机构也可用于PATCH或iPATCH。

The new methods defined in the present specification are secured following the CoAP recommendations for the existing methods as specified in Section 9 of [RFC7252]. When additional security techniques are standardized for CoAP (e.g., Object Security), these techniques are then also available for securing the new methods.

本规范中定义的新方法按照[RFC7252]第9节中规定的CoAP对现有方法的建议进行保护。当为CoAP标准化其他安全技术(例如,对象安全性)时,这些技术也可用于保护新方法。

6. IANA Considerations
6. IANA考虑

IANA has added the following entries to the subregistry "CoAP Method Codes":

IANA已将以下条目添加到分区“CoAP方法代码”:

                       +------+--------+-----------+
                       | Code | Name   | Reference |
                       +------+--------+-----------+
                       | 0.05 | FETCH  | RFC 8132  |
                       | 0.06 | PATCH  | RFC 8132  |
                       | 0.07 | iPATCH | RFC 8132  |
                       +------+--------+-----------+
        
                       +------+--------+-----------+
                       | Code | Name   | Reference |
                       +------+--------+-----------+
                       | 0.05 | FETCH  | RFC 8132  |
                       | 0.06 | PATCH  | RFC 8132  |
                       | 0.07 | iPATCH | RFC 8132  |
                       +------+--------+-----------+
        

The FETCH method is idempotent and safe, and it returns the same response codes that GET can return, plus 4.13 (Request Entity Too Large), 4.15 (Unsupported Content-Format), and 4.22 (Unprocessable Entity) with the semantics specified in Section 2.2.

FETCH方法是幂等且安全的,它返回GET可以返回的相同响应代码,加上4.13(请求实体太大)、4.15(不支持的内容格式)和4.22(不可处理的实体),其语义在第2.2节中指定。

The PATCH method is neither idempotent nor safe. It returns the same response codes that POST can return, plus 4.09 (Conflict) and 4.22 (Unprocessable Entity) with the semantics specified in Section 3.4.

PATCH方法既不是幂等的,也不是安全的。它返回POST可以返回的相同响应代码,加上4.09(冲突)和4.22(不可处理实体),其语义在第3.4节中指定。

The iPATCH method is identical to the PATCH method, except that it is idempotent.

iPATCH方法与PATCH方法相同,只是它是幂等的。

IANA has added the following code to the subregistry "CoAP Response Codes":

IANA已将以下代码添加到子区域“CoAP响应代码”:

                +------+----------------------+-----------+
                | Code | Name                 | Reference |
                +------+----------------------+-----------+
                | 4.09 | Conflict             | RFC 8132  |
                | 4.22 | Unprocessable Entity | RFC 8132  |
                +------+----------------------+-----------+
        
                +------+----------------------+-----------+
                | Code | Name                 | Reference |
                +------+----------------------+-----------+
                | 4.09 | Conflict             | RFC 8132  |
                | 4.22 | Unprocessable Entity | RFC 8132  |
                +------+----------------------+-----------+
        

IANA has added entries to the subregistry "CoAP Content-Formats":

IANA已将条目添加到子区域“CoAP内容格式”:

    +------------------------------+----------------+----+-----------+
    | Media Type                   | Content Coding | ID | Reference |
    +------------------------------+----------------+----+-----------+
    | application/json-patch+json  | identity       | 51 | [RFC6902] |
    | application/merge-patch+json | identity       | 52 | [RFC7396] |
    +------------------------------+----------------+----+-----------+
        
    +------------------------------+----------------+----+-----------+
    | Media Type                   | Content Coding | ID | Reference |
    +------------------------------+----------------+----+-----------+
    | application/json-patch+json  | identity       | 51 | [RFC6902] |
    | application/merge-patch+json | identity       | 52 | [RFC7396] |
    +------------------------------+----------------+----+-----------+
        
7. References
7. 工具书类
7.1. Normative References
7.1. 规范性引用文件

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.

[RFC2119]Bradner,S.,“RFC中用于表示需求水平的关键词”,BCP 14,RFC 2119,DOI 10.17487/RFC2119,1997年3月<http://www.rfc-editor.org/info/rfc2119>.

[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, March 2010, <http://www.rfc-editor.org/info/rfc5789>.

[RFC5789]Dusseault,L.和J.Snell,“HTTP的补丁方法”,RFC 5789,DOI 10.17487/RFC5789,2010年3月<http://www.rfc-editor.org/info/rfc5789>.

[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <http://www.rfc-editor.org/info/rfc7231>.

[RFC7231]Fielding,R.,Ed.和J.Reschke,Ed.,“超文本传输协议(HTTP/1.1):语义和内容”,RFC 7231,DOI 10.17487/RFC72312014年6月<http://www.rfc-editor.org/info/rfc7231>.

[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, <http://www.rfc-editor.org/info/rfc7252>.

[RFC7252]Shelby,Z.,Hartke,K.,和C.Bormann,“受限应用协议(CoAP)”,RFC 7252,DOI 10.17487/RFC7252,2014年6月<http://www.rfc-editor.org/info/rfc7252>.

[RFC7641] Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/RFC7641, September 2015, <http://www.rfc-editor.org/info/rfc7641>.

[RFC7641]Hartke,K.,“受限应用协议(CoAP)中的观测资源”,RFC 7641,DOI 10.17487/RFC7641,2015年9月<http://www.rfc-editor.org/info/rfc7641>.

[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in the Constrained Application Protocol (CoAP)", RFC 7959, DOI 10.17487/RFC7959, August 2016, <http://www.rfc-editor.org/info/rfc7959>.

[RFC7959]Bormann,C.和Z.Shelby,编辑,“受限应用协议(CoAP)中的分块传输”,RFC 7959,DOI 10.17487/RFC7959,2016年8月<http://www.rfc-editor.org/info/rfc7959>.

7.2. Informative References
7.2. 资料性引用

[RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, "Web Distributed Authoring and Versioning (WebDAV) SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, <http://www.rfc-editor.org/info/rfc5323>.

[RFC5323]Reschke,J.,Ed.,Reddy,S.,Davis,J.,和A.Babich,“Web分布式创作和版本控制(WebDAV)搜索”,RFC 5323,DOI 10.17487/RFC5323,2008年11月<http://www.rfc-editor.org/info/rfc5323>.

[RFC6902] Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902, April 2013, <http://www.rfc-editor.org/info/rfc6902>.

[RFC6902]Bryan,P.,Ed.和M.Nottingham,Ed.,“JavaScript对象表示法(JSON)补丁”,RFC 6902,DOI 10.17487/RFC6902,2013年4月<http://www.rfc-editor.org/info/rfc6902>.

[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.

[RFC7159]Bray,T.,Ed.“JavaScript对象表示法(JSON)数据交换格式”,RFC 7159,DOI 10.17487/RFC7159,2014年3月<http://www.rfc-editor.org/info/rfc7159>.

[RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, DOI 10.17487/RFC7396, October 2014, <http://www.rfc-editor.org/info/rfc7396>.

[RFC7396]Hoffman,P.和J.Snell,“JSON合并补丁”,RFC 7396,DOI 10.17487/RFC7396,2014年10月<http://www.rfc-editor.org/info/rfc7396>.

[COAP-MGMNT] Stok, P., Bierman, A., Veillette, M., and A. Pelov, "CoAP Management Interface", Work in Progress, draft-ietf-core-comi-00, January 2017.

[COAP-MGMNT]Stok,P.,Bierman,A.,Veillette,M.,和A.Pelov,“COAP管理接口”,在建工程,草案-ietf-core-comi-00,2017年1月。

[CORE-APP] Hartke, K., "CoRE Application Descriptions", Work in Progress, draft-hartke-core-apps-07, February 2017.

[CORE-APP]Hartke,K.,“核心应用程序说明”,正在进行的工作,草稿-Hartke-CORE-apps-072017年2月。

[HTTP-SEARCH] Reschke, J., Malhotra, A., and J. Snell, "HTTP SEARCH Method", Work in Progress, draft-snell-search-method-00, April 2015.

[HTTP-SEARCH]Reschke,J.,Malhotra,A.,和J.Snell,“HTTP搜索方法”,正在进行的工作,草稿-Snell-SEARCH-Method-00,2015年4月。

Acknowledgements

致谢

Klaus Hartke has pointed out some essential differences between CoAP and HTTP concerning PATCH and found a number of problems in an earlier draft version of Section 2. We are grateful for discussions with Christian Amsuss, Andy Bierman, Timothy Carey, Paul Duffy, Matthias Kovatsch, Michel Veillette, Michael Verschoor, Thomas Watteyne, and Gengyu Wei. Christian Groves provided detailed comments during the Working Group Last Call, and Christer Holmberg's Gen-ART review provided some further editorial improvement. Further Last Call reviews were provided by Sheng Jiang and Phillip Hallam-Baker. As usual, the IESG had some very good reviews, and we would like to specifically call out those by Alexey Melnikov (responsible AD) and Alissa Cooper.

Klaus Hartke指出了CoAP和HTTP在补丁方面的一些本质区别,并在第2节的早期草案中发现了一些问题。我们感谢与Christian Amsus、Andy Bierman、Timothy Carey、Paul Duffy、Matthias Kovatsch、Michel Veillette、Michael Verschoor、Thomas Watteyne和Gengyu Wei的讨论。克里斯蒂安·格罗夫斯(Christian Groves)在工作组上次电话会议期间提供了详细的评论,克里斯特·霍姆伯格(Christer Holmberg)的《当代艺术评论》(Gen ART review)提供了一些进一步的编辑改进。盛江和Phillip Hallam Baker提供了进一步的最后通话回顾。和往常一样,IESG有一些非常好的评论,我们想特别指出Alexey Melnikov(负责任的广告)和Alissa Cooper的评论。

Authors' Addresses

作者地址

Peter van der Stok Consultant

彼得·范德斯托克顾问

   Email: consultancy@vanderstok.org
        
   Email: consultancy@vanderstok.org
        

Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany

卡斯滕·鲍曼大学不来梅邮政学院330440不来梅D-28359德国

   Phone: +49-421-218-63921
   Email: cabo@tzi.org
        
   Phone: +49-421-218-63921
   Email: cabo@tzi.org
        

Anuj Sehgal NAVOMI, Inc.

Anuj Sehgal NAVOMI公司。

   Email: anuj.sehgal@navomi.com
        
   Email: anuj.sehgal@navomi.com