Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8072 YumaWorks
Category: Standards Track M. Bjorklund
ISSN: 2070-1721 Tail-f Systems
K. Watsen
Juniper Networks
February 2017
Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8072 YumaWorks
Category: Standards Track M. Bjorklund
ISSN: 2070-1721 Tail-f Systems
K. Watsen
Juniper Networks
February 2017
YANG Patch Media Type
杨补丁媒体类型
Abstract
摘要
This document describes a method for applying patches to configuration datastores using data defined with the YANG data modeling language.
本文档描述了使用数据建模语言定义的数据将修补程序应用于配置数据存储的方法。
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/rfc8072.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc8072.
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. Terminology ................................................3
1.1.1. NETCONF .............................................3
1.1.2. HTTP ................................................4
1.1.3. YANG ................................................4
1.1.4. RESTCONF ............................................4
1.1.5. YANG Patch ..........................................5
1.1.6. Examples ............................................5
1.1.7. Tree Diagram Notations ..............................6
2. YANG Patch ......................................................6
2.1. Target Resource ............................................7
2.2. yang-patch Request .........................................8
2.3. yang-patch-status Response .................................9
2.4. Target Data Node ..........................................10
2.5. Edit Operations ...........................................11
2.6. Successful Edit Response Handling .........................11
2.7. Error Handling ............................................12
2.8. ":yang-patch" RESTCONF Capability .........................12
3. YANG Module ....................................................13
4. IANA Considerations ............................................22
4.1. Registrations for New URI and YANG Module .................22
4.2. Media Types ...............................................23
4.2.1. Media Type "application/yang-patch+xml" ............23
4.2.2. Media Type "application/yang-patch+json" ...........24
4.3. RESTCONF Capability URNs ..................................25
5. Security Considerations ........................................25
6. References .....................................................26
6.1. Normative References ......................................26
6.2. Informative References ....................................27
Appendix A. Example YANG Module ...................................28
A.1. YANG Patch Examples ........................................29
A.1.1. Add Resources: Error ...................................29
A.1.2. Add Resources: Success .................................33
A.1.3. Insert List Entry ......................................35
A.1.4. Move List Entry ........................................36
A.1.5. Edit Datastore Resource ................................37
Acknowledgements ..................................................39
Authors' Addresses ................................................39
1. Introduction ....................................................3
1.1. Terminology ................................................3
1.1.1. NETCONF .............................................3
1.1.2. HTTP ................................................4
1.1.3. YANG ................................................4
1.1.4. RESTCONF ............................................4
1.1.5. YANG Patch ..........................................5
1.1.6. Examples ............................................5
1.1.7. Tree Diagram Notations ..............................6
2. YANG Patch ......................................................6
2.1. Target Resource ............................................7
2.2. yang-patch Request .........................................8
2.3. yang-patch-status Response .................................9
2.4. Target Data Node ..........................................10
2.5. Edit Operations ...........................................11
2.6. Successful Edit Response Handling .........................11
2.7. Error Handling ............................................12
2.8. ":yang-patch" RESTCONF Capability .........................12
3. YANG Module ....................................................13
4. IANA Considerations ............................................22
4.1. Registrations for New URI and YANG Module .................22
4.2. Media Types ...............................................23
4.2.1. Media Type "application/yang-patch+xml" ............23
4.2.2. Media Type "application/yang-patch+json" ...........24
4.3. RESTCONF Capability URNs ..................................25
5. Security Considerations ........................................25
6. References .....................................................26
6.1. Normative References ......................................26
6.2. Informative References ....................................27
Appendix A. Example YANG Module ...................................28
A.1. YANG Patch Examples ........................................29
A.1.1. Add Resources: Error ...................................29
A.1.2. Add Resources: Success .................................33
A.1.3. Insert List Entry ......................................35
A.1.4. Move List Entry ........................................36
A.1.5. Edit Datastore Resource ................................37
Acknowledgements ..................................................39
Authors' Addresses ................................................39
There is a need for standard mechanisms to patch datastores defined in [RFC6241], which contain conceptual data that conforms to schema specified with YANG [RFC7950]. An "ordered 'edit' list" approach is needed to provide RESTCONF client developers with more precise RESTCONF client control of the edit procedure than the "plain patch" mechanism found in [RFC8040].
需要标准机制来修补[RFC6241]中定义的数据存储，这些数据存储包含符合YANG[RFC7950]指定模式的概念数据。与[RFC8040]中的“普通补丁”机制相比，需要一种“有序的‘编辑’列表”方法为RESTCONF客户端开发人员提供对编辑过程更精确的RESTCONF客户端控制。
This document defines a media type for a YANG-based editing mechanism that can be used with the HTTP PATCH method [RFC5789]. YANG Patch is designed to support the RESTCONF protocol, defined in [RFC8040]. This document only specifies the use of the YANG Patch media type with the RESTCONF protocol.
本文档定义了基于YANG的编辑机制的媒体类型，该机制可与HTTP补丁方法[RFC5789]一起使用。YANG补丁旨在支持[RFC8040]中定义的RESTCONF协议。本文档仅指定在RESTCONF协议中使用修补程序媒体类型。
It may be possible to use YANG Patch with other protocols besides RESTCONF. This is outside the scope of this document. For any protocol that supports the YANG Patch media type, if the entire patch document cannot be successfully applied, then the server MUST NOT apply any of the changes. It may be possible to use YANG Patch with datastore types other than a configuration datastore. This is outside the scope of this document.
除了RESTCONF之外，还可以将YANG Patch与其他协议一起使用。这超出了本文件的范围。对于任何支持修补程序介质类型的协议，如果无法成功应用整个修补程序文档，则服务器不得应用任何更改。可以将YANG Patch与配置数据存储以外的数据存储类型一起使用。这超出了本文件的范围。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。
The following terms are defined in [RFC6241]:
[RFC6241]中定义了以下术语：
o configuration data
o 配置数据
o datastore
o 数据存储
o configuration datastore
o 配置数据存储
o protocol operation
o 协议操作
o running configuration datastore
o 运行配置数据存储
o state data
o 状态数据
o user
o 使用者
The following terms are defined in [RFC7230]:
[RFC7230]中定义了以下术语：
o header field
o 标题字段
o message-body
o 消息体
o query
o 查询
o request URI
o 请求URI
The following terms are defined in [RFC7231]:
[RFC7231]中定义了以下术语：
o method
o 方法
o request
o 要求
o resource
o 资源
The following terms are defined in [RFC7950]:
[RFC7950]中定义了以下术语：
o container
o 容器
o data node
o 数据节点
o leaf
o 叶
o leaf-list
o 叶列表
o list
o 列表
The following terms are defined in [RFC8040]:
[RFC8040]中定义了以下术语：
o application/yang-data+xml
o 应用程序/数据+xml
o application/yang-data+json
o 应用程序/数据+json
o data resource
o 数据资源
o datastore resource
o 数据存储资源
o patch
o 色斑
o RESTCONF capability
o RESTCONF能力
o target resource
o 目标资源
o YANG data template
o 杨氏数据模板
The following terms are used within this document:
本文件中使用了以下术语：
o RESTCONF client: a client that implements the RESTCONF protocol.
o RESTCONF客户端：实现RESTCONF协议的客户端。
o RESTCONF server: a server that implements the RESTCONF protocol.
o RESTCONF服务器：实现RESTCONF协议的服务器。
o YANG Patch: a conceptual edit request using the "yang-patch" YANG Patch template, defined in Section 3. In HTTP, refers to a PATCH method where a representation uses either the media type "application/yang-patch+xml" or "application/yang-patch+json".
o YANG Patch：使用第3节中定义的“YANG Patch”YANG Patch模板的概念性编辑请求。在HTTP中，是指一种补丁方法，其中表示使用媒体类型“application/yang PATCH+xml”或“application/yang PATCH+json”。
o YANG Patch Status: a conceptual edit status response using the YANG "yang-patch-status" YANG data template, defined in Section 3. In HTTP, refers to a response message for a PATCH method, where it has a representation with either the media type "application/yang-data+xml" or "application/yang-data+json".
o YANG Patch Status：使用第3节中定义的YANG“YANG Patch Status”YANG数据模板的概念性编辑状态响应。在HTTP中，是指修补程序方法的响应消息，其中它具有媒体类型“application/yang data+xml”或“application/yang data+json”的表示形式。
o YANG Patch template: similar to a YANG data template, except that it has a representation with the media type "application/yang-patch+xml" or "application/yang-patch+json".
o YANG Patch template：与YANG数据模板类似，只是它有一个媒体类型为“application/YANG Patch+xml”或“application/YANG Patch+json”的表示。
Some protocol message lines within examples throughout this document are split into multiple lines for display purposes only. When a line ends with a backslash ("\") as the last character, the line is wrapped for display purposes. It is to be considered to be joined to the next line by deleting the backslash, the following line break, and the leading whitespace of the next line.
本文档示例中的一些协议消息行被拆分为多行，仅用于显示目的。当一行以反斜杠（\）作为最后一个字符结束时，出于显示目的，该行将被换行。通过删除下一行的反斜杠、下一行的换行符和前导空格，可以将其视为连接到下一行。
A simplified graphical representation of the data model is used in this document. The meanings of the symbols in these diagrams are as follows:
本文件中使用了数据模型的简化图形表示。这些图表中的符号含义如下：
o Brackets "[" and "]" enclose list keys.
o 括号“[”和“]”包含列表键。
o Abbreviations before data node names: "rw" means configuration data (read-write), "ro" means state data (read-only), and "x" means operation resource (executable).
o 数据节点名称前的缩写：“rw”表示配置数据（读写），“ro”表示状态数据（只读），“x”表示操作资源（可执行）。
o Symbols after data node names: "?" means an optional node, and "*" denotes a "list" and "leaf-list".
o 数据节点名称后的符号：“？”表示可选节点，“*”表示“列表”和“叶列表”。
o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":").
o 括号括住选项和事例节点，事例节点也用冒号（“：”）标记。
o Ellipsis ("...") stands for contents of subtrees that are not shown.
o 省略号（“…”）表示未显示的子树的内容。
A "YANG Patch" is an ordered list of edits that are applied to the target datastore by the RESTCONF server. The specific fields are defined in the YANG module in Section 3.
“YANG补丁”是RESTCONF服务器应用于目标数据存储的编辑的有序列表。具体字段在第3节的YANG模块中定义。
The YANG Patch operation is invoked by the RESTCONF client by sending a PATCH method request with a representation using either the media type "application/yang-patch+xml" or "application/yang-patch+json". This message-body representing the YANG Patch input parameters MUST be present.
RESTCONF客户机通过发送一个补丁方法请求来调用YANG Patch操作，该请求使用媒体类型“application/YANG Patch+xml”或“application/YANG Patch+json”表示。表示输入参数的消息体必须存在。
YANG Patch has some features that are not possible with the "plain-patch" mechanism defined in RESTCONF [RFC8040]:
YANG Patch具有一些在RESTCONF[RFC8040]中定义的“普通补丁”机制中无法实现的功能：
o YANG Patch allows multiple sub-resources to be edited within the same PATCH method.
o YANG Patch允许在同一补丁方法中编辑多个子资源。
o YANG Patch allows a more precise edit operation than the "plain patch" mechanism found in [RFC8040]. There are seven operations supported ("create", "delete", "insert", "merge", "move", "replace", and "remove").
o YANG Patch允许比[RFC8040]中的“普通补丁”机制更精确的编辑操作。支持七种操作（“创建”、“删除”、“插入”、“合并”、“移动”、“替换”和“删除”）。
o YANG Patch uses an "edit" list with an explicit processing order. The edits are processed in client-specified order, and error processing can be precise even when multiple errors occur in the same YANG Patch request.
o YANG Patch使用带有显式处理顺序的“编辑”列表。编辑按客户端指定的顺序进行处理，即使在同一个修补程序请求中发生多个错误，错误处理也可以精确。
The YANG Patch "patch-id" may be useful for debugging and SHOULD be present in any audit logging records generated by the RESTCONF server for a patch.
补丁“补丁id”对于调试可能很有用，并且应该出现在RESTCONF服务器为补丁生成的任何审计日志记录中。
The RESTCONF server MUST return the "Accept-Patch" header field in an OPTIONS response, as specified in [RFC5789], which includes the media type for YANG Patch. This is needed by a client to determine the message-encoding formats supported by the server (e.g., XML, JSON, or both). The following is an example of an "Accept-Patch" header:
RESTCONF服务器必须在选项响应中返回“Accept Patch”头字段，如[RFC5789]中所述，其中包括修补程序的媒体类型。客户端需要这一点来确定服务器支持的消息编码格式（例如，XML、JSON或两者）。以下是“接受修补程序”标头的示例：
Accept-Patch: application/yang-patch+xml,application/yang-patch+json
Accept-Patch: application/yang-patch+xml,application/yang-patch+json
Note that YANG Patch can only edit data resources. The PATCH method cannot be used to replace the datastore resource. Although the "ietf-yang-patch" YANG module is written using YANG version 1.1 [RFC7950], an implementation of YANG Patch can be used with content defined in YANG version 1 [RFC6020] as well.
请注意，YANG Patch只能编辑数据资源。无法使用修补程序方法替换数据存储资源。尽管“ietf yang patch”yang模块是使用yang版本1.1[RFC7950]编写的，但yang patch的实现也可以与yang版本1[RFC6020]中定义的内容一起使用。
A YANG Patch can be encoded in XML format according to [W3C.REC-xml-20081126]. It can also be encoded in JSON according to "JSON Encoding of Data Modeled with YANG" [RFC7951]. If any metadata needs to be sent in a JSON message, it is encoded according to "Defining and Using Metadata with YANG" [RFC7952].
根据[W3C.REC-XML-20081126]的规定，可以用XML格式对修补程序进行编码。也可以根据“YANG建模数据的JSON编码”[RFC7951]用JSON编码。如果需要在JSON消息中发送任何元数据，则根据“定义并使用YANG元数据”[RFC7952]对其进行编码。
The YANG Patch operation uses the RESTCONF target resource URI to identify the resource that will be patched. This can be the datastore resource itself, i.e., "{+restconf}/data", to edit top-level configuration data resources, or it can be a configuration data resource within the datastore resource, e.g., "{+restconf}/data/ietf-interfaces:interfaces", to edit sub-resources within a top-level configuration data resource.
修补程序操作使用RESTCONF目标资源URI来标识要修补的资源。这可以是数据存储资源本身，即“{+restconf}/data”，用于编辑顶级配置数据资源，也可以是数据存储资源中的配置数据资源，例如“{+restconf}/data/ietf interfaces:interfaces”，用于编辑顶级配置数据资源中的子资源。
The target resource MUST identify exactly one resource instance. If more than one resource instance is identified, then the request MUST NOT be processed and a "400 Bad Request" error response MUST be sent by the server. If the target resource does not identify any existing resource instance, then the request MUST NOT be processed and a "404 Not Found" error response MUST be sent by the server.
目标资源必须准确标识一个资源实例。如果标识了多个资源实例，则不得处理该请求，服务器必须发送“400错误请求”错误响应。如果目标资源未标识任何现有资源实例，则不得处理该请求，服务器必须发送“404 not Found”错误响应。
Each edit with a YANG Patch identifies a target data node for the associated edit. This is described in Section 2.4.
每个带有修补程序的编辑都会标识关联编辑的目标数据节点。第2.4节对此进行了描述。
A YANG Patch is identified by a unique "patch-id", and it may have an optional comment. A patch is an ordered collection of edits. Each edit is identified by an "edit-id", and it has an edit operation ("create", "delete", "insert", "merge", "move", "replace", or "remove") that is applied to the target resource. Each edit can be applied to a sub-resource "target" within the target resource. If the operation is "insert" or "move", then the "where" parameter indicates how the node is inserted or moved. For values "before" and "after", the "point" parameter specifies the data node insertion point.
一个补丁由一个唯一的“补丁id”标识，它可能有一个可选的注释。修补程序是编辑的有序集合。每个编辑都由一个“编辑id”标识，它有一个应用于目标资源的编辑操作（“创建”、“删除”、“插入”、“合并”、“移动”、“替换”或“删除”）。每次编辑都可以应用于目标资源中的子资源“目标”。如果操作为“插入”或“移动”，则“where”参数指示如何插入或移动节点。对于“before”和“after”值，“point”参数指定数据节点插入点。
The "merge", "replace", "create", "delete", and "remove" edit operations have exactly the same meanings as those defined for the "operation" attribute described in Section 7.2 of [RFC6241].
“合并”、“替换”、“创建”、“删除”和“删除”编辑操作的含义与[RFC6241]第7.2节中描述的“操作”属性定义的含义完全相同。
Each edit within a YANG Patch MUST identify exactly one data resource instance. If an edit represents more than one resource instance, then the request MUST NOT be processed and a "400 Bad Request" error response MUST be sent by the server. If the edit does not identify any existing resource instance and the operation for the edit is not "create", then the request MUST NOT be processed and a "404 Not Found" error response MUST be sent by the server. A "yang-patch-status" response MUST be sent by the server identifying the edit or edits that are not valid.
修补程序中的每个编辑必须准确标识一个数据资源实例。如果一个编辑代表多个资源实例，则该请求不得处理，服务器必须发送“400错误请求”错误响应。如果编辑未标识任何现有资源实例，并且编辑操作不是“创建”，则服务器必须不处理请求并发送“404未找到”错误响应。服务器必须发送“修补程序状态”响应，以识别无效的编辑。
YANG Patch does not provide any access to specific datastores. How a server processes an edit if it is co-located with a Network Configuration Protocol (NETCONF) server that does provide access to individual datastores is left up to the implementation. A complete datastore cannot be replaced in the same manner as that provided by the <copy-config> operation defined in Section 7.3 of [RFC6241]. Only the specified nodes in a YANG Patch are affected.
YANG Patch不提供对特定数据存储的任何访问。如果服务器与提供对单个数据存储访问的网络配置协议（NETCONF）服务器位于同一位置，则服务器如何处理编辑由实现决定。不能以与[RFC6241]第7.3节中定义的<copy config>操作相同的方式替换完整的数据存储。只有面片中的指定节点受影响。
A message-body representing the YANG Patch is sent by the RESTCONF client to specify the edit operation request. When used with the HTTP PATCH method, this data is identified by the YANG Patch media type.
RESTCONF客户端将发送一个表示修补程序的消息体，以指定编辑操作请求。当与HTTP修补程序方法一起使用时，此数据由修补程序媒体类型标识。
YANG tree diagram for "yang-patch" container:
“阳补丁”容器的阳树图：
+---- yang-patch
+---- patch-id string
+---- comment? string
+---- edit* [edit-id]
+---- edit-id string
+---- operation enumeration
+---- target target-resource-offset
+---- point? target-resource-offset
+---- where? enumeration
+---- value?
+---- yang-patch
+---- patch-id string
+---- comment? string
+---- edit* [edit-id]
+---- edit-id string
+---- operation enumeration
+---- target target-resource-offset
+---- point? target-resource-offset
+---- where? enumeration
+---- value?
A message-body representing the YANG Patch Status is returned to the RESTCONF client to report the detailed status of the edit operation. When used with the HTTP PATCH method, this data is identified by the YANG Patch Status media type; the syntax specification is defined in Section 3.
表示修补程序状态的消息体将返回到RESTCONF客户端，以报告编辑操作的详细状态。当与HTTP补丁方法一起使用时，该数据由补丁状态媒体类型标识；第3节定义了语法规范。
YANG tree diagram for "yang-patch-status" container:
“阳补丁状态”容器的阳树形图：
+---- yang-patch-status
+---- patch-id string
+---- (global-status)?
| +--:(global-errors)
| | +---- errors
| | +---- error*
| | +---- error-type enumeration
| | +---- error-tag string
| | +---- error-app-tag? string
| | +---- error-path? instance-identifier
| | +---- error-message? string
| | +---- error-info?
| +--:(ok)
| +---- ok? empty
+---- edit-status
+---- edit* [edit-id]
+---- edit-id string
+---- (edit-status-choice)?
+--:(ok)
| +---- ok? empty
+--:(errors)
+---- errors
+---- error*
+---- error-type enumeration
+---- error-tag string
+---- error-app-tag? string
+---- error-path? instance-identifier
+---- error-message? string
+---- error-info?
+---- yang-patch-status
+---- patch-id string
+---- (global-status)?
| +--:(global-errors)
| | +---- errors
| | +---- error*
| | +---- error-type enumeration
| | +---- error-tag string
| | +---- error-app-tag? string
| | +---- error-path? instance-identifier
| | +---- error-message? string
| | +---- error-info?
| +--:(ok)
| +---- ok? empty
+---- edit-status
+---- edit* [edit-id]
+---- edit-id string
+---- (edit-status-choice)?
+--:(ok)
| +---- ok? empty
+--:(errors)
+---- errors
+---- error*
+---- error-type enumeration
+---- error-tag string
+---- error-app-tag? string
+---- error-path? instance-identifier
+---- error-message? string
+---- error-info?
The target data node for each edit operation is determined by the value of the target resource in the request and the "target" leaf within each "edit" entry.
每个编辑操作的目标数据节点由请求中的目标资源值和每个“编辑”条目中的“目标”叶确定。
If the target resource specified in the request URI identifies a datastore resource, then the path string in the "target" leaf is treated as an absolute path expression identifying the target data node for the corresponding edit. The first node specified in the "target" leaf is a top-level data node defined within a YANG module. The "target" leaf MUST NOT contain a single forward slash ("/"), since this would identify the datastore resource, not a data resource.
如果请求URI中指定的目标资源标识数据存储资源，“目标”叶中的路径字符串被视为标识相应编辑的目标数据节点的绝对路径表达式。“目标”叶中指定的第一个节点是在模块中定义的顶级数据节点。“目标”叶不能包含单个正斜杠（“/”），因为这将标识数据存储资源，而不是数据资源。
If the target resource specified in the request URI identifies a configuration data resource, then the path string in the "target" leaf is treated as a relative path expression. The first node specified in the "target" leaf is a child configuration data node of the data node associated with the target resource. If the "target" leaf contains a single forward slash ("/"), then the target data node is the target resource data node.
如果请求URI中指定的目标资源标识了配置数据资源，“目标”叶中的路径字符串被视为相对路径表达式。“目标”叶中指定的第一个节点是与目标资源关联的数据节点的子配置数据节点。如果“目标”叶包含一个正斜杠（“/”），则目标数据节点是目标资源数据节点。
Each YANG Patch edit specifies one edit operation on the target data node. The set of operations is aligned with the NETCONF edit operations but also includes some new operations.
每次编辑指定目标数据节点上的一次编辑操作。操作集与NETCONF编辑操作一致，但也包括一些新操作。
+-----------+-------------------------------------------------------+
| Operation | Description |
+-----------+-------------------------------------------------------+
| create | create a new data resource if it does not already |
| | exist; if it already exists, return an error |
| | |
| delete | delete a data resource if it already exists; if it |
| | does not exist, return an error |
| | |
| insert | insert a new user-ordered data resource |
| | |
| merge | merge the edit value with the target data resource; |
| | create if it does not already exist |
| | |
| move | reorder the target data resource |
| | |
| replace | replace the target data resource with the edit value |
| | |
| remove | remove a data resource if it already exists |
+-----------+-------------------------------------------------------+
+-----------+-------------------------------------------------------+
| Operation | Description |
+-----------+-------------------------------------------------------+
| create | create a new data resource if it does not already |
| | exist; if it already exists, return an error |
| | |
| delete | delete a data resource if it already exists; if it |
| | does not exist, return an error |
| | |
| insert | insert a new user-ordered data resource |
| | |
| merge | merge the edit value with the target data resource; |
| | create if it does not already exist |
| | |
| move | reorder the target data resource |
| | |
| replace | replace the target data resource with the edit value |
| | |
| remove | remove a data resource if it already exists |
+-----------+-------------------------------------------------------+
YANG Patch Edit Operations
杨补丁编辑操作
If a YANG Patch is completed without errors, the RESTCONF server MUST return a "yang-patch-status" message with a "global-status" choice set to "ok".
如果一个YANG补丁没有错误地完成，RESTCONF服务器必须返回一条“YANG补丁状态”消息，并将“全局状态”选项设置为“ok”。
Refer to Appendix A.1.2 for an example of a successful YANG Patch response.
参考附录A.1.2，了解成功的杨氏贴片响应示例。
If a well-formed, schema-valid YANG Patch message is received, then the RESTCONF server will process the supplied edits in ascending order. The following error modes apply to the processing of this "edit" list:
如果收到格式良好、模式有效的消息，RESTCONF服务器将按升序处理提供的编辑。以下错误模式适用于此“编辑”列表的处理：
If a YANG Patch is completed with errors, the RESTCONF server SHOULD return a "yang-patch-status" message. It is possible (e.g., within a distributed implementation) that an invalid request will be rejected before the YANG Patch edits are processed. In this case, the server MUST send the appropriate HTTP error response instead.
如果YANG修补程序完成时出现错误，RESTCONF服务器应返回“YANG修补程序状态”消息。在处理修补程序编辑之前，可能会拒绝无效请求（例如，在分布式实现中）。在这种情况下，服务器必须发送相应的HTTP错误响应。
Refer to Appendix A.1.1 for an example of an error YANG Patch response.
请参阅附录A.1.1，了解错误响应的示例。
A URI is defined to identify the YANG Patch extension to the base RESTCONF protocol. If the RESTCONF server supports the YANG Patch media type, then the ":yang-patch" RESTCONF capability defined in Section 4.3 MUST be present in the "capability" leaf-list in the "ietf-restconf-monitoring" module defined in [RFC8040].
定义了一个URI来标识基本RESTCONF协议的扩展。如果RESTCONF服务器支持YANG Patch媒体类型，则第4.3节中定义的“：YANG Patch”RESTCONF功能必须出现在[RFC8040]中定义的“ietf RESTCONF监控”模块的“功能”叶列表中。
The "ietf-yang-patch" module defines conceptual definitions with the "yang-data" extension statements, which are not meant to be implemented as datastore contents by a RESTCONF server.
“ietf yang patch”模块使用“yang data”扩展语句定义概念定义，这些扩展语句不打算由RESTCONF服务器实现为数据存储内容。
The "ietf-restconf" module from [RFC8040] is used by this module for the "yang-data" extension definition.
[RFC8040]中的“ietf restconf”模块由该模块用于“yang数据”扩展定义。
<CODE BEGINS>
<代码开始>
file "ietf-yang-patch@2017-02-22.yang"
文件“ietf yang”-patch@2017-02-22.杨”
module ietf-yang-patch {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch";
prefix "ypatch";
module ietf-yang-patch {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch";
prefix "ypatch";
import ietf-restconf { prefix rc; }
import ietf-restconf { prefix rc; }
organization "IETF NETCONF (Network Configuration) Working Group";
组织“IETF网络配置工作组”；
contact
"WG Web: <https://datatracker.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
contact
"WG Web: <https://datatracker.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Author: Andy Bierman
<mailto:andy@yumaworks.com>
Author: Andy Bierman
<mailto:andy@yumaworks.com>
Author: Martin Bjorklund
<mailto:mbj@tail-f.com>
Author: Martin Bjorklund
<mailto:mbj@tail-f.com>
Author: Kent Watsen
<mailto:kwatsen@juniper.net>";
Author: Kent Watsen
<mailto:kwatsen@juniper.net>";
description "This module contains conceptual YANG specifications for the YANG Patch and YANG Patch Status data structures.
说明“本模块包含YANG Patch和YANG Patch Status数据结构的概念性YANG规范。
Note that the YANG definitions within this module do not represent configuration data of any kind. The YANG grouping statements provide a normative syntax for XML and JSON message-encoding purposes.
请注意，此模块中的定义并不表示任何类型的配置数据。这些语句为XML和JSON消息编码提供了规范语法。
Copyright (c) 2017 IETF Trust and the persons identified as authors of the code. All rights reserved.
版权所有（c）2017 IETF信托基金和被确定为代码作者的人员。版权所有。
Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info).
根据IETF信托有关IETF文件的法律规定第4.c节规定的简化BSD许可证中包含的许可条款，允许以源代码和二进制格式重新分发和使用，无论是否修改(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC 8072; see the RFC itself for full legal notices.";
该模块的此版本是RFC 8072的一部分；有关完整的法律通知，请参见RFC本身。“；
revision 2017-02-22 {
description
"Initial revision.";
reference
"RFC 8072: YANG Patch Media Type.";
}
revision 2017-02-22 {
description
"Initial revision.";
reference
"RFC 8072: YANG Patch Media Type.";
}
typedef target-resource-offset {
type string;
description
"Contains a data resource identifier string representing
a sub-resource within the target resource.
The document root for this expression is the
target resource that is specified in the
protocol operation (e.g., the URI for the PATCH request).
typedef target-resource-offset {
type string;
description
"Contains a data resource identifier string representing
a sub-resource within the target resource.
The document root for this expression is the
target resource that is specified in the
protocol operation (e.g., the URI for the PATCH request).
This string is encoded according to the same rules as those
for a data resource identifier in a RESTCONF request URI.";
reference
"RFC 8040, Section 3.5.3.";
}
This string is encoded according to the same rules as those
for a data resource identifier in a RESTCONF request URI.";
reference
"RFC 8040, Section 3.5.3.";
}
rc:yang-data "yang-patch" {
uses yang-patch;
}
rc:yang-data "yang-patch" {
uses yang-patch;
}
rc:yang-data "yang-patch-status" {
uses yang-patch-status;
}
rc:yang-data "yang-patch-status" {
uses yang-patch-status;
}
grouping yang-patch {
分组阳斑{
description "A grouping that contains a YANG container representing the syntax and semantics of a YANG Patch edit request message.";
description“包含一个YANG容器的分组，该容器表示YANG补丁编辑请求消息的语法和语义。”；
container yang-patch { description "Represents a conceptual sequence of datastore edits, called a patch. Each patch is given a client-assigned patch identifier. Each edit MUST be applied in ascending order, and all edits MUST be applied. If any errors occur, then the target datastore MUST NOT be changed by the YANG Patch operation.
容器yang patch{description”表示数据存储编辑的概念序列，称为修补程序。每个修补程序都有一个客户端指定的修补程序标识符。每个编辑必须按升序应用，并且必须应用所有编辑。如果发生任何错误，则yang patch操作不得更改目标数据存储。
It is possible for a datastore constraint violation to occur due to any node in the datastore, including nodes not included in the 'edit' list. Any validation errors MUST be reported in the reply message.";
由于数据存储中的任何节点（包括未包含在“编辑”列表中的节点），可能会发生数据存储约束冲突。任何验证错误都必须在回复消息中报告。“；
reference "RFC 7950, Section 8.3.";
参考“RFC 7950，第8.3节”；
leaf patch-id {
type string;
mandatory true;
description
"An arbitrary string provided by the client to identify
the entire patch. Error messages returned by the server
that pertain to this patch will be identified by this
'patch-id' value. A client SHOULD attempt to generate
unique 'patch-id' values to distinguish between
transactions from multiple clients in any audit logs
maintained by the server.";
}
leaf patch-id {
type string;
mandatory true;
description
"An arbitrary string provided by the client to identify
the entire patch. Error messages returned by the server
that pertain to this patch will be identified by this
'patch-id' value. A client SHOULD attempt to generate
unique 'patch-id' values to distinguish between
transactions from multiple clients in any audit logs
maintained by the server.";
}
leaf comment {
type string;
description
"An arbitrary string provided by the client to describe
the entire patch. This value SHOULD be present in any
audit logging records generated by the server for the
patch.";
}
leaf comment {
type string;
description
"An arbitrary string provided by the client to describe
the entire patch. This value SHOULD be present in any
audit logging records generated by the server for the
patch.";
}
list edit {
key edit-id;
ordered-by user;
list edit {
key edit-id;
ordered-by user;
description "Represents one edit within the YANG Patch request message. The 'edit' list is applied in the following manner:
description“表示修补程序请求消息中的一个编辑。按以下方式应用“编辑”列表：
- The first edit is conceptually applied to a copy of the existing target datastore, e.g., the running configuration datastore. - Each ascending edit is conceptually applied to the result of the previous edit(s). - After all edits have been successfully processed, the result is validated according to YANG constraints. - If successful, the server will attempt to apply the result to the target datastore.";
- 第一次编辑在概念上应用于现有目标数据存储的副本，例如，正在运行的配置数据存储。-从概念上讲，每个升序编辑都应用于先前编辑的结果成功处理所有编辑后，根据杨约束验证结果。-如果成功，服务器将尝试将结果应用于目标数据存储。“；
leaf edit-id {
type string;
description
"Arbitrary string index for the edit.
Error messages returned by the server that pertain
to a specific edit will be identified by this value.";
}
leaf edit-id {
type string;
description
"Arbitrary string index for the edit.
Error messages returned by the server that pertain
to a specific edit will be identified by this value.";
}
leaf operation {
type enumeration {
enum create {
description
"The target data node is created using the supplied
value, only if it does not already exist. The
'target' leaf identifies the data node to be
created, not the parent data node.";
}
enum delete {
description
"Delete the target node, only if the data resource
currently exists; otherwise, return an error.";
}
leaf operation {
type enumeration {
enum create {
description
"The target data node is created using the supplied
value, only if it does not already exist. The
'target' leaf identifies the data node to be
created, not the parent data node.";
}
enum delete {
description
"Delete the target node, only if the data resource
currently exists; otherwise, return an error.";
}
enum insert {
description
"Insert the supplied value into a user-ordered
list or leaf-list entry. The target node must
represent a new data resource. If the 'where'
parameter is set to 'before' or 'after', then
the 'point' parameter identifies the insertion
point for the target node.";
}
enum merge {
description
"The supplied value is merged with the target data
node.";
}
enum move {
description
"Move the target node. Reorder a user-ordered
list or leaf-list. The target node must represent
an existing data resource. If the 'where' parameter
is set to 'before' or 'after', then the 'point'
parameter identifies the insertion point to move
the target node.";
}
enum replace {
description
"The supplied value is used to replace the target
data node.";
}
enum remove {
description
"Delete the target node if it currently exists.";
}
}
mandatory true;
description
"The datastore operation requested for the associated
'edit' entry.";
}
enum insert {
description
"Insert the supplied value into a user-ordered
list or leaf-list entry. The target node must
represent a new data resource. If the 'where'
parameter is set to 'before' or 'after', then
the 'point' parameter identifies the insertion
point for the target node.";
}
enum merge {
description
"The supplied value is merged with the target data
node.";
}
enum move {
description
"Move the target node. Reorder a user-ordered
list or leaf-list. The target node must represent
an existing data resource. If the 'where' parameter
is set to 'before' or 'after', then the 'point'
parameter identifies the insertion point to move
the target node.";
}
enum replace {
description
"The supplied value is used to replace the target
data node.";
}
enum remove {
description
"Delete the target node if it currently exists.";
}
}
mandatory true;
description
"The datastore operation requested for the associated
'edit' entry.";
}
leaf target {
type target-resource-offset;
mandatory true;
description
"Identifies the target data node for the edit
operation. If the target has the value '/', then
the target data node is the target resource.
The target node MUST identify a data resource,
not the datastore resource.";
}
leaf target {
type target-resource-offset;
mandatory true;
description
"Identifies the target data node for the edit
operation. If the target has the value '/', then
the target data node is the target resource.
The target node MUST identify a data resource,
not the datastore resource.";
}
leaf point {
when "(../operation = 'insert' or ../operation = 'move')"
+ "and (../where = 'before' or ../where = 'after')" {
description
"This leaf only applies for 'insert' or 'move'
operations, before or after an existing entry.";
}
type target-resource-offset;
description
"The absolute URL path for the data node that is being
used as the insertion point or move point for the
target of this 'edit' entry.";
}
leaf point {
when "(../operation = 'insert' or ../operation = 'move')"
+ "and (../where = 'before' or ../where = 'after')" {
description
"This leaf only applies for 'insert' or 'move'
operations, before or after an existing entry.";
}
type target-resource-offset;
description
"The absolute URL path for the data node that is being
used as the insertion point or move point for the
target of this 'edit' entry.";
}
leaf where {
when "../operation = 'insert' or ../operation = 'move'" {
description
"This leaf only applies for 'insert' or 'move'
operations.";
}
type enumeration {
enum before {
description
"Insert or move a data node before the data resource
identified by the 'point' parameter.";
}
enum after {
description
"Insert or move a data node after the data resource
identified by the 'point' parameter.";
}
leaf where {
when "../operation = 'insert' or ../operation = 'move'" {
description
"This leaf only applies for 'insert' or 'move'
operations.";
}
type enumeration {
enum before {
description
"Insert or move a data node before the data resource
identified by the 'point' parameter.";
}
enum after {
description
"Insert or move a data node after the data resource
identified by the 'point' parameter.";
}
enum first {
description
"Insert or move a data node so it becomes ordered
as the first entry.";
}
enum last {
description
"Insert or move a data node so it becomes ordered
as the last entry.";
}
}
default last;
description
"Identifies where a data resource will be inserted
or moved. YANG only allows these operations for
list and leaf-list data nodes that are
'ordered-by user'.";
}
enum first {
description
"Insert or move a data node so it becomes ordered
as the first entry.";
}
enum last {
description
"Insert or move a data node so it becomes ordered
as the last entry.";
}
}
default last;
description
"Identifies where a data resource will be inserted
or moved. YANG only allows these operations for
list and leaf-list data nodes that are
'ordered-by user'.";
}
anydata value {
when "../operation = 'create' "
+ "or ../operation = 'merge' "
+ "or ../operation = 'replace' "
+ "or ../operation = 'insert'" {
description
"The anydata 'value' is only used for 'create',
'merge', 'replace', and 'insert' operations.";
}
description
"Value used for this edit operation. The anydata 'value'
contains the target resource associated with the
'target' leaf.
anydata value {
when "../operation = 'create' "
+ "or ../operation = 'merge' "
+ "or ../operation = 'replace' "
+ "or ../operation = 'insert'" {
description
"The anydata 'value' is only used for 'create',
'merge', 'replace', and 'insert' operations.";
}
description
"Value used for this edit operation. The anydata 'value'
contains the target resource associated with the
'target' leaf.
For example, suppose the target node is a YANG container named foo:
例如，假设目标节点是一个名为foo的容器：
container foo {
leaf a { type string; }
leaf b { type int32; }
}
container foo {
leaf a { type string; }
leaf b { type int32; }
}
The 'value' node contains one instance of foo:
“value”节点包含一个foo实例：
<value>
<foo xmlns='example-foo-namespace'>
<a>some value</a>
<b>42</b>
</foo>
</value>
";
}
}
}
<value>
<foo xmlns='example-foo-namespace'>
<a>some value</a>
<b>42</b>
</foo>
</value>
";
}
}
}
} // grouping yang-patch
} // grouping yang-patch
grouping yang-patch-status {
分组阳斑状态{
description "A grouping that contains a YANG container representing the syntax and semantics of a YANG Patch Status response message.";
description“包含表示YANG补丁状态响应消息的语法和语义的YANG容器的分组。”；
container yang-patch-status {
description
"A container representing the response message sent by the
server after a YANG Patch edit request message has been
processed.";
container yang-patch-status {
description
"A container representing the response message sent by the
server after a YANG Patch edit request message has been
processed.";
leaf patch-id {
type string;
mandatory true;
description
"The 'patch-id' value used in the request.";
}
leaf patch-id {
type string;
mandatory true;
description
"The 'patch-id' value used in the request.";
}
choice global-status {
description
"Report global errors or complete success.
If there is no case selected, then errors
are reported in the 'edit-status' container.";
choice global-status {
description
"Report global errors or complete success.
If there is no case selected, then errors
are reported in the 'edit-status' container.";
case global-errors {
uses rc:errors;
description
"This container will be present if global errors that
are unrelated to a specific edit occurred.";
}
leaf ok {
type empty;
description
"This leaf will be present if the request succeeded
and there are no errors reported in the 'edit-status'
container.";
}
}
case global-errors {
uses rc:errors;
description
"This container will be present if global errors that
are unrelated to a specific edit occurred.";
}
leaf ok {
type empty;
description
"This leaf will be present if the request succeeded
and there are no errors reported in the 'edit-status'
container.";
}
}
container edit-status {
description
"This container will be present if there are
edit-specific status responses to report.
If all edits succeeded and the 'global-status'
returned is 'ok', then a server MAY omit this
container.";
container edit-status {
description
"This container will be present if there are
edit-specific status responses to report.
If all edits succeeded and the 'global-status'
returned is 'ok', then a server MAY omit this
container.";
list edit {
key edit-id;
list edit {
key edit-id;
description "Represents a list of status responses, corresponding to edits in the YANG Patch request message. If an 'edit' entry was skipped or not reached by the server, then this list will not contain a corresponding entry for that edit.";
description“表示与修补程序请求消息中的编辑相对应的状态响应列表。如果服务器跳过或未访问“编辑”条目，则此列表将不包含该编辑的相应条目。”；
leaf edit-id {
type string;
description
"Response status is for the 'edit' list entry
with this 'edit-id' value.";
}
leaf edit-id {
type string;
description
"Response status is for the 'edit' list entry
with this 'edit-id' value.";
}
choice edit-status-choice {
description
"A choice between different types of status
responses for each 'edit' entry.";
leaf ok {
type empty;
description
"This 'edit' entry was invoked without any
errors detected by the server associated
with this edit.";
}
case errors {
uses rc:errors;
description
"The server detected errors associated with the
edit identified by the same 'edit-id' value.";
}
}
}
}
}
} // grouping yang-patch-status
choice edit-status-choice {
description
"A choice between different types of status
responses for each 'edit' entry.";
leaf ok {
type empty;
description
"This 'edit' entry was invoked without any
errors detected by the server associated
with this edit.";
}
case errors {
uses rc:errors;
description
"The server detected errors associated with the
edit identified by the same 'edit-id' value.";
}
}
}
}
}
} // grouping yang-patch-status
}
}
<CODE ENDS>
<代码结束>
This document registers one URI as a namespace in the "IETF XML Registry" [RFC3688]. It follows the format in RFC 3688.
本文档在“IETF XML注册表”[RFC3688]中将一个URI注册为命名空间。它遵循RFC 3688中的格式。
URI: urn:ietf:params:xml:ns:yang:ietf-yang-patch Registrant Contact: The IESG. XML: N/A; the requested URI is an XML namespace.
URI:urn:ietf:params:xml:ns:yang:ietf-yang补丁注册人联系人：IESG。XML：不适用；请求的URI是一个XML命名空间。
This document registers one YANG module in the "YANG Module Names" registry [RFC6020].
本文件在“阳模块名称”注册表[RFC6020]中注册了一个阳模块。
name: ietf-yang-patch
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch
prefix: ypatch
reference: RFC 8072
name: ietf-yang-patch
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch
prefix: ypatch
reference: RFC 8072
Type name: application
类型名称：应用程序
Subtype name: yang-patch+xml
子类型名称：yang patch+xml
Required parameters: None
所需参数：无
Optional parameters: None
可选参数：无
Encoding considerations: 8-bit The "utf-8" charset is always used for this type. Each conceptual YANG data node is encoded according to the XML Encoding Rules and Canonical Format for the specific YANG data node type defined in [RFC7950]. In addition, the "yang-patch" YANG Patch template found in RFC 8072 defines the structure of a YANG Patch request.
编码注意事项：8位“utf-8”字符集始终用于此类型。每个概念YANG数据节点根据[RFC7950]中定义的特定YANG数据节点类型的XML编码规则和规范格式进行编码。此外，RFC 8072中的“yang patch”yang patch模板定义了yang patch请求的结构。
Security considerations: Security considerations related to the generation and consumption of RESTCONF messages are discussed in Section 5 of RFC 8072. Additional security considerations are specific to the semantics of particular YANG data models. Each YANG module is expected to specify security considerations for the YANG data defined in that module.
安全注意事项：RFC 8072第5节讨论了与RESTCONF消息的生成和使用相关的安全注意事项。其他安全注意事项特定于特定数据模型的语义。每个YANG模块都需要为该模块中定义的YANG数据指定安全注意事项。
Interoperability considerations: RFC 8072 specifies the format of conforming messages and the interpretation thereof.
互操作性注意事项：RFC 8072规定了一致性消息的格式及其解释。
Published specification: RFC 8072
已发布规范：RFC 8072
Applications that use this media type: Instance document data parsers used within a protocol or automation tool that utilize the YANG Patch data structure.
使用此媒体类型的应用程序：在协议或自动化工具中使用的实例文档数据解析器，使用YANG Patch数据结构。
Fragment identifier considerations: The syntax and semantics of fragment identifiers are the same as the syntax and semantics specified for the "application/xml" media type.
片段标识符注意事项：片段标识符的语法和语义与为“application/xml”媒体类型指定的语法和语义相同。
Additional information:
其他信息：
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information: See the Authors' Addresses section of RFC 8072.
联系人和电子邮件地址以获取更多信息：请参阅RFC 8072的作者地址部分。
Intended usage: COMMON
预期用途：普通
Restrictions on usage: N/A
使用限制：不适用
Author: See the Authors' Addresses section of RFC 8072.
作者：参见RFC 8072的作者地址部分。
Change controller: Internet Engineering Task Force (mailto:iesg@ietf.org).
变更控制员：互联网工程任务组（邮寄：iesg@ietf.org).
Provisional registration? (standards tree only): no
临时登记？（仅限标准树）：否
Type name: application
类型名称：应用程序
Subtype name: yang-patch+json
子类型名称：yang patch+json
Required parameters: None
所需参数：无
Optional parameters: None
可选参数：无
Encoding considerations: 8-bit The "utf-8" charset is always used for this type. Each conceptual YANG data node is encoded according to RFC 7951. A metadata annotation is encoded according to RFC 7952. In addition, the "yang-patch" YANG Patch template found in RFC 8072 defines the structure of a YANG Patch request.
编码注意事项：8位“utf-8”字符集始终用于此类型。每个数据节点根据RFC 7951进行编码。元数据注释根据RFC 7952进行编码。此外，RFC 8072中的“yang patch”yang patch模板定义了yang patch请求的结构。
Security considerations: Security considerations related to the generation and consumption of RESTCONF messages are discussed in Section 5 of RFC 8072. Additional security considerations are specific to the semantics of particular YANG data models. Each YANG module is expected to specify security considerations for the YANG data defined in that module.
安全注意事项：RFC 8072第5节讨论了与RESTCONF消息的生成和使用相关的安全注意事项。其他安全注意事项特定于特定数据模型的语义。每个YANG模块都需要为该模块中定义的YANG数据指定安全注意事项。
Interoperability considerations: RFC 8072 specifies the format of conforming messages and the interpretation thereof.
互操作性注意事项：RFC 8072规定了一致性消息的格式及其解释。
Published specification: RFC 8072
已发布规范：RFC 8072
Applications that use this media type: Instance document data parsers used within a protocol or automation tool that utilize the YANG Patch data structure.
使用此媒体类型的应用程序：在协议或自动化工具中使用的实例文档数据解析器，使用YANG Patch数据结构。
Fragment identifier considerations: The syntax and semantics of fragment identifiers are the same as the syntax and semantics specified for the "application/json" media type.
片段标识符注意事项：片段标识符的语法和语义与为“application/json”媒体类型指定的语法和语义相同。
Additional information:
其他信息：
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information: See the Authors' Addresses section of RFC 8072.
联系人和电子邮件地址以获取更多信息：请参阅RFC 8072的作者地址部分。
Intended usage: COMMON
预期用途：普通
Restrictions on usage: N/A
使用限制：不适用
Author: See the Authors' Addresses section of RFC 8072.
作者：参见RFC 8072的作者地址部分。
Change controller: Internet Engineering Task Force (mailto:iesg@ietf.org).
变更控制员：互联网工程任务组（邮寄：iesg@ietf.org).
Provisional registration? (standards tree only): no
临时登记？（仅限标准树）：否
This document registers one capability identifier in the "RESTCONF Capability URNs" registry [RFC8040]. The review policy for this registry is "IETF Review" [RFC5226].
本文档在“RESTCONF capability URNs”注册表[RFC8040]中注册了一个功能标识符。此注册表的审核策略为“IETF审核”[RFC5226]。
Index Capability Identifier
------------------------------------------------------------------
:yang-patch urn:ietf:params:restconf:capability:yang-patch:1.0
Index Capability Identifier
------------------------------------------------------------------
:yang-patch urn:ietf:params:restconf:capability:yang-patch:1.0
The YANG Patch media type does not introduce any significant new security threats, beyond what is described in [RFC8040]. This document defines edit processing instructions for a variant of the PATCH method, as used within the RESTCONF protocol. Message integrity is provided by the RESTCONF protocol. There is no additional capability to validate that a patch has not been altered.
除[RFC8040]中所述的安全威胁外，YANG Patch media类型不会引入任何新的重大安全威胁。本文档定义了RESTCONF协议中使用的补丁方法变体的编辑处理指令。消息完整性由RESTCONF协议提供。没有额外的功能来验证修补程序是否未被更改。
It may be possible to use YANG Patch with other protocols besides RESTCONF; this topic is outside the scope of this document.
除了RESTCONF之外，还可以将YANG Patch与其他协议一起使用；本主题不在本文档的范围内。
For RESTCONF, both the client and server MUST be authenticated according to Section 2 of [RFC8040]. It is important for RESTCONF server implementations to carefully validate all the edit request parameters in some manner. If the entire YANG Patch request cannot be completed, then no configuration changes to the system are done. A PATCH request MUST be applied atomically, as specified in Section 2 of [RFC5789].
对于RESTCONF，必须根据[RFC8040]第2节对客户端和服务器进行身份验证。RESTCONF服务器实现必须以某种方式仔细验证所有编辑请求参数。如果无法完成整个修补程序请求，则不会对系统进行任何配置更改。按照[RFC5789]第2节的规定，必须以原子方式应用补丁请求。
A RESTCONF server implementation SHOULD attempt to prevent system disruption due to incremental processing of the YANG Patch "edit" list. It may be possible to construct an attack on such a RESTCONF server, which relies on the edit processing order mandated by YANG Patch. A server SHOULD apply only the fully validated configuration to the underlying system. For example, an "edit" list that deleted an interface and then recreated it could cause system disruption if the "edit" list was incrementally applied.
RESTCONF服务器实现应尝试防止由于对“编辑”列表进行增量处理而导致系统中断。可能会在此类RESTCONF服务器上构造攻击，该服务器依赖于修补程序强制执行的编辑处理顺序。服务器应仅将完全验证的配置应用于基础系统。例如，如果增量应用“编辑”列表，则删除接口然后重新创建的“编辑”列表可能会导致系统中断。
A RESTCONF server implementation SHOULD attempt to prevent system disruption due to excessive resource consumption required to fulfill YANG Patch edit requests. On such an implementation, it may be possible to construct an attack that attempts to consume all available memory or other resource types.
RESTCONF服务器实现应尝试防止由于完成补丁编辑请求所需的过度资源消耗而导致系统中断。在这种实现上，可能会构造一种攻击，试图消耗所有可用内存或其他资源类型。
[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>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <http://www.rfc-editor.org/info/rfc3688>.
[RFC3688]Mealling，M.，“IETF XML注册表”，BCP 81，RFC 3688，DOI 10.17487/RFC3688，2004年1月<http://www.rfc-editor.org/info/rfc3688>.
[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>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <http://www.rfc-editor.org/info/rfc6020>.
[RFC6020]Bjorklund，M.，Ed.“YANG-网络配置协议的数据建模语言（NETCONF）”，RFC 6020，DOI 10.17487/RFC6020，2010年10月<http://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <http://www.rfc-editor.org/info/rfc6241>.
[RFC6241]Enns，R.，Ed.，Bjorklund，M.，Ed.，Schoenwaeld，J.，Ed.，和A.Bierman，Ed.，“网络配置协议（NETCONF）”，RFC 6241，DOI 10.17487/RFC6241，2011年6月<http://www.rfc-editor.org/info/rfc6241>.
[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>.
[RFC7230] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.
[RFC7230]Fielding，R.，Ed.，和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：消息语法和路由”，RFC 7230，DOI 10.17487/RFC7230，2014年6月<http://www.rfc-editor.org/info/rfc7230>.
[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>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <http://www.rfc-editor.org/info/rfc7950>.
[RFC7950]Bjorklund，M.，Ed.“YANG 1.1数据建模语言”，RFC 7950，DOI 10.17487/RFC7950，2016年8月<http://www.rfc-editor.org/info/rfc7950>.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <http://www.rfc-editor.org/info/rfc7951>.
[RFC7951]Lhotka，L.，“用YANG建模的数据的JSON编码”，RFC 7951，DOI 10.17487/RFC7951，2016年8月<http://www.rfc-editor.org/info/rfc7951>.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", RFC 7952, DOI 10.17487/RFC7952, August 2016, <http://www.rfc-editor.org/info/rfc7952>.
[RFC7952]Lhotka，L.，“与YANG一起定义和使用元数据”，RFC 7952，DOI 10.17487/RFC7952，2016年8月<http://www.rfc-editor.org/info/rfc7952>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <http://www.rfc-editor.org/info/rfc8040>.
[RFC8040]Bierman，A.，Bjorklund，M.，和K.Watsen，“RESTCONF协议”，RFC 8040，DOI 10.17487/RFC8040，2017年1月<http://www.rfc-editor.org/info/rfc8040>.
[W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[W3C.REC-xml-20081126]Bray，T.，Paoli，J.，Sperberg McQueen，M.，Maler，E.，和F.Yergeau，“可扩展标记语言（xml）1.0（第五版）”，万维网联盟建议REC-xml-20081126，2008年11月<http://www.w3.org/TR/2008/REC-xml-20081126>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008, <http://www.rfc-editor.org/info/rfc5226>.
[RFC5226]Narten，T.和H.Alvestrand，“在RFCs中编写IANA注意事项部分的指南”，BCP 26，RFC 5226，DOI 10.17487/RFC5226，2008年5月<http://www.rfc-editor.org/info/rfc5226>.
The example YANG module used in this document represents a simple media jukebox interface. The "example-jukebox" YANG module is defined in [RFC8040].
本文档中使用的示例模块表示一个简单的媒体自动存储塔接口。[RFC8040]中定义了“示例自动存储塔”模块。
YANG tree diagram for the "example-jukebox" module:
“示例自动存储塔”模块的杨树图：
+--rw jukebox!
+--rw library
| +--rw artist* [name]
| | +--rw name string
| | +--rw album* [name]
| | +--rw name string
| | +--rw genre? identityref
| | +--rw year? uint16
| | +--rw admin
| | | +--rw label? string
| | | +--rw catalogue-number? string
| | +--rw song* [name]
| | +--rw name string
| | +--rw location string
| | +--rw format? string
| | +--rw length? uint32
| +--ro artist-count? uint32
| +--ro album-count? uint32
| +--ro song-count? uint32
+--rw playlist* [name]
| +--rw name string
| +--rw description? string
| +--rw song* [index]
| +--rw index uint32
| +--rw id instance-identifier
+--rw player
+--rw gap? decimal64
+--rw jukebox!
+--rw library
| +--rw artist* [name]
| | +--rw name string
| | +--rw album* [name]
| | +--rw name string
| | +--rw genre? identityref
| | +--rw year? uint16
| | +--rw admin
| | | +--rw label? string
| | | +--rw catalogue-number? string
| | +--rw song* [name]
| | +--rw name string
| | +--rw location string
| | +--rw format? string
| | +--rw length? uint32
| +--ro artist-count? uint32
| +--ro album-count? uint32
| +--ro song-count? uint32
+--rw playlist* [name]
| +--rw name string
| +--rw description? string
| +--rw song* [index]
| +--rw index uint32
| +--rw id instance-identifier
+--rw player
+--rw gap? decimal64
rpcs:
RPC：
+---x play
+--ro input
+--ro playlist string
+--ro song-number uint32
+---x play
+--ro input
+--ro playlist string
+--ro song-number uint32
This section includes RESTCONF examples. Most examples are shown in JSON encoding [RFC7159], and some are shown in XML encoding [W3C.REC-xml-20081126].
本节包括RESTCONF示例。大多数示例显示在JSON编码[RFC7159]中，一些示例显示在XML编码[W3C.REC-XML-20081126]中。
The following example shows several songs being added to an existing album. Each edit contains one song. The first song already exists, so an error will be reported for that edit. The rest of the edits were not attempted, since the first edit failed. XML encoding is used in this example.
以下示例显示了添加到现有唱片集的多首歌曲。每个编辑包含一首歌曲。第一首歌曲已存在，因此将为该编辑报告错误。由于第一次编辑失败，因此未尝试其他编辑。本例中使用XML编码。
Request from the RESTCONF client:
来自RESTCONF客户端的请求：
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
Content-Type: application/yang-patch+xml
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
Content-Type: application/yang-patch+xml
<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-songs-patch</patch-id>
<edit>
<edit-id>edit1</edit-id>
<operation>create</operation>
<target>/song=Bridge%20Burning</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Bridge Burning</name>
<location>/media/bridge_burning.mp3</location>
<format>MP3</format>
<length>288</length>
</song>
</value>
</edit>
<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-songs-patch</patch-id>
<edit>
<edit-id>edit1</edit-id>
<operation>create</operation>
<target>/song=Bridge%20Burning</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Bridge Burning</name>
<location>/media/bridge_burning.mp3</location>
<format>MP3</format>
<length>288</length>
</song>
</value>
</edit>
<edit>
<edit-id>edit2</edit-id>
<operation>create</operation>
<target>/song=Rope</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Rope</name>
<location>/media/rope.mp3</location>
<format>MP3</format>
<length>259</length>
</song>
</value>
</edit>
<edit>
<edit-id>edit3</edit-id>
<operation>create</operation>
<target>/song=Dear%20Rosemary</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Dear Rosemary</name>
<location>/media/dear_rosemary.mp3</location>
<format>MP3</format>
<length>269</length>
</song>
</value>
</edit>
</yang-patch>
<edit>
<edit-id>edit2</edit-id>
<operation>create</operation>
<target>/song=Rope</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Rope</name>
<location>/media/rope.mp3</location>
<format>MP3</format>
<length>259</length>
</song>
</value>
</edit>
<edit>
<edit-id>edit3</edit-id>
<operation>create</operation>
<target>/song=Dear%20Rosemary</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Dear Rosemary</name>
<location>/media/dear_rosemary.mp3</location>
<format>MP3</format>
<length>269</length>
</song>
</value>
</edit>
</yang-patch>
XML response from the RESTCONF server:
来自RESTCONF服务器的XML响应：
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+xml
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+xml
<yang-patch-status
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-songs-patch</patch-id>
<edit-status>
<edit>
<edit-id>edit1</edit-id>
<errors>
<error>
<error-type>application</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:jb="http://example.com/ns/example-jukebox">
/jb:jukebox/jb:library
/jb:artist[jb:name='Foo Fighters']
/jb:album[jb:name='Wasting Light']
/jb:song[jb:name='Bridge Burning']
</error-path>
<error-message>
Data already exists; cannot be created
</error-message>
</error>
</errors>
</edit>
</edit-status>
</yang-patch-status>
<yang-patch-status
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-songs-patch</patch-id>
<edit-status>
<edit>
<edit-id>edit1</edit-id>
<errors>
<error>
<error-type>application</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:jb="http://example.com/ns/example-jukebox">
/jb:jukebox/jb:library
/jb:artist[jb:name='Foo Fighters']
/jb:album[jb:name='Wasting Light']
/jb:song[jb:name='Bridge Burning']
</error-path>
<error-message>
Data already exists; cannot be created
</error-message>
</error>
</errors>
</edit>
</edit-status>
</yang-patch-status>
JSON response from the RESTCONF server:
来自RESTCONF服务器的JSON响应：
The following response is shown in JSON format to highlight the difference in the "error-path" object encoding. For JSON, the instance-identifier encoding specified in [RFC7951] is used.
以下响应以JSON格式显示，以突出显示“错误路径”对象编码中的差异。对于JSON，使用[RFC7951]中指定的实例标识符编码。
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch",
"edit-status" : {
"edit" : [
{
"edit-id" : "edit1",
"errors" : {
"error" : [
{
"error-type": "application",
"error-tag": "data-exists",
"error-path": "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']",
"error-message":
"Data already exists; cannot be created"
}
]
}
}
]
}
}
}
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch",
"edit-status" : {
"edit" : [
{
"edit-id" : "edit1",
"errors" : {
"error" : [
{
"error-type": "application",
"error-tag": "data-exists",
"error-path": "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']",
"error-message":
"Data already exists; cannot be created"
}
]
}
}
]
}
}
}
The following example shows several songs being added to an existing album.
以下示例显示了添加到现有唱片集的多首歌曲。
o Each of two edits contains one song.
o 两次编辑中的每一次都包含一首歌曲。
o Both edits succeed, and new sub-resources are created.
o 两次编辑都成功，并创建了新的子资源。
Request from the RESTCONF client:
来自RESTCONF客户端的请求：
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light \
HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light \
HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "add-songs-patch-2",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "create",
"target" : "/song=Rope",
"value" : {
"song" : [
{
"name" : "Rope",
"location" : "/media/rope.mp3",
"format" : "MP3",
"length" : 259
}
]
}
},
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "add-songs-patch-2",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "create",
"target" : "/song=Rope",
"value" : {
"song" : [
{
"name" : "Rope",
"location" : "/media/rope.mp3",
"format" : "MP3",
"length" : 259
}
]
}
},
{
"edit-id" : "edit2",
"operation" : "create",
"target" : "/song=Dear%20Rosemary",
"value" : {
"song" : [
{
"name" : "Dear Rosemary",
"location" : "/media/dear_rosemary.mp3",
"format" : "MP3",
"length" : 269
}
]
}
}
]
}
}
{
"edit-id" : "edit2",
"operation" : "create",
"target" : "/song=Dear%20Rosemary",
"value" : {
"song" : [
{
"name" : "Dear Rosemary",
"location" : "/media/dear_rosemary.mp3",
"format" : "MP3",
"length" : 269
}
]
}
}
]
}
}
Response from the RESTCONF server:
来自RESTCONF服务器的响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch-2",
"ok" : [null]
}
}
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch-2",
"ok" : [null]
}
}
The following example shows a song being inserted within an existing playlist. Song "6" in playlist "Foo-One" is being inserted after song "5" in the playlist. The operation succeeds, so a non-error reply can be provided.
以下示例显示正在现有播放列表中插入的歌曲。播放列表“Foo One”中的歌曲“6”将插入播放列表中歌曲“5”之后。操作成功，因此可以提供无错误回复。
Request from the RESTCONF client:
来自RESTCONF客户端的请求：
PATCH /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
PATCH /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "insert-song-patch",
"comment" : "Insert song 6 after song 5",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "insert",
"target" : "/song=6",
"point" : "/song=5",
"where" : "after",
"value" : {
"example-jukebox:song" : [
{
"index" : 6,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
}
]
}
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "insert-song-patch",
"comment" : "Insert song 6 after song 5",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "insert",
"target" : "/song=6",
"point" : "/song=5",
"where" : "after",
"value" : {
"example-jukebox:song" : [
{
"index" : 6,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
}
]
}
Response from the RESTCONF server:
来自RESTCONF服务器的响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "insert-song-patch",
"ok" : [null]
}
}
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "insert-song-patch",
"ok" : [null]
}
}
The following example shows a song being moved within an existing playlist. Song "1" in playlist "Foo-One" is being moved after song "3" in the playlist. Note that no "value" parameter is needed for a "move" operation. The operation succeeds, so a non-error reply can be provided.
以下示例显示正在现有播放列表中移动的歌曲。正在将播放列表“Foo One”中的歌曲“1”移动到播放列表中的歌曲“3”之后。请注意，“移动”操作不需要“值”参数。操作成功，因此可以提供无错误回复。
Request from the RESTCONF client:
来自RESTCONF客户端的请求：
PATCH /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
PATCH /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "move-song-patch",
"comment" : "Move song 1 after song 3",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "move",
"target" : "/song=1",
"point" : "/song=3",
"where" : "after"
}
]
}
}
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "move-song-patch",
"comment" : "Move song 1 after song 3",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "move",
"target" : "/song=1",
"point" : "/song=3",
"where" : "after"
}
]
}
}
Response from the RESTCONF server:
来自RESTCONF服务器的响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-restconf:yang-patch-status" : {
"patch-id" : "move-song-patch",
"ok" : [null]
}
}
{
"ietf-restconf:yang-patch-status" : {
"patch-id" : "move-song-patch",
"ok" : [null]
}
}
The following example shows how three top-level data nodes from different modules can be edited at the same time.
以下示例显示了如何同时编辑来自不同模块的三个顶级数据节点。
Example module "foo" defines leaf X. Example module "bar" defines container Y, with child leafs A and B. Example module "baz" defines list Z, with key C and child leafs D and E.
示例模块“foo”定义了叶X。示例模块“bar”定义了容器Y，其中包含子叶A和B。示例模块“baz”定义了列表Z，其中包含键C和子叶D和E。
Request from the RESTCONF client:
来自RESTCONF客户端的请求：
PATCH /restconf/data HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
PATCH /restconf/data HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "datastore-patch-1",
"comment" : "Edit 3 top-level data nodes at once",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "create",
"target" : "/foo:X",
"value" : {
"foo:X" : 42
}
},
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "datastore-patch-1",
"comment" : "Edit 3 top-level data nodes at once",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "create",
"target" : "/foo:X",
"value" : {
"foo:X" : 42
}
},
{
"edit-id" : "edit2",
"operation" : "merge",
"target" : "/bar:Y",
"value" : {
"bar:Y" : {
"A" : "test1",
"B" : 99
}
}
},
{
"edit-id" : "edit3",
"operation" : "replace",
"target" : "/baz:Z=2",
"value" : {
"baz:Z" : [
{
"C" : 2,
"D" : 100,
"E" : false
}
]
}
}
]
}
}
{
"edit-id" : "edit2",
"operation" : "merge",
"target" : "/bar:Y",
"value" : {
"bar:Y" : {
"A" : "test1",
"B" : 99
}
}
},
{
"edit-id" : "edit3",
"operation" : "replace",
"target" : "/baz:Z=2",
"value" : {
"baz:Z" : [
{
"C" : 2,
"D" : 100,
"E" : false
}
]
}
}
]
}
}
Response from the RESTCONF server:
来自RESTCONF服务器的响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:55:30 GMT
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:55:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "datastore-patch-1",
"ok" : [null]
}
}
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "datastore-patch-1",
"ok" : [null]
}
}
Acknowledgements
致谢
The authors would like to thank Rex Fernando for his contributions to this document.
作者要感谢Rex Fernando对本文件的贡献。
Contributions to this material by Andy Bierman are based upon work supported by the United States Army, Space & Terrestrial Communications Directorate (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the S&TCD.
Andy Bierman对本材料的贡献基于美国陆军空间与地面通信局（S&TCD）根据编号为W15P7T-13-C-A616的合同支持的工作。本材料中表达的任何意见、发现和结论或建议均为作者的意见、发现和结论或建议，不一定反映s&TCD的观点。
Authors' Addresses
作者地址
Andy Bierman YumaWorks
安迪·比尔曼·尤马沃斯
Email: andy@yumaworks.com
Email: andy@yumaworks.com
Martin Bjorklund Tail-f Systems
Martin Bjorklund Tail-f系统
Email: mbj@tail-f.com
Email: mbj@tail-f.com
Kent Watsen Juniper Networks
肯特沃特森刺柏网络公司
Email: kwatsen@juniper.net
Email: kwatsen@juniper.net