Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8040 YumaWorks
Category: Standards Track M. Bjorklund
ISSN: 2070-1721 Tail-f Systems
K. Watsen
Juniper Networks
January 2017
Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8040 YumaWorks
Category: Standards Track M. Bjorklund
ISSN: 2070-1721 Tail-f Systems
K. Watsen
Juniper Networks
January 2017
RESTCONF Protocol
RESTCONF协议
Abstract
摘要
This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF).
本文档描述了一个基于HTTP的协议，该协议使用网络配置协议（NETCONF）中定义的数据存储概念，为访问YANG中定义的数据提供编程接口。
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/rfc8040.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问http://www.rfc-editor.org/info/rfc8040.
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 ....................................................5
1.1. Terminology ................................................5
1.1.1. NETCONF .............................................6
1.1.2. HTTP ................................................6
1.1.3. YANG ................................................7
1.1.4. NETCONF Notifications ...............................7
1.1.5. Terms ...............................................8
1.1.6. URI Template and Examples ..........................10
1.1.7. Tree Diagrams ......................................11
1.2. Subset of NETCONF Functionality ...........................11
1.3. Data-Model-Driven API .....................................12
1.4. Coexistence with NETCONF ..................................13
1.5. RESTCONF Extensibility ....................................14
2. Transport Protocol .............................................15
2.1. Integrity and Confidentiality .............................15
2.2. HTTPS with X.509v3 Certificates ...........................16
2.3. Certificate Validation ....................................16
2.4. Authenticated Server Identity .............................16
2.5. Authenticated Client Identity .............................16
3. Resources ......................................................17
3.1. Root Resource Discovery ...................................18
3.2. RESTCONF Media Types ......................................20
3.3. API Resource ..............................................20
3.3.1. {+restconf}/data ...................................21
3.3.2. {+restconf}/operations .............................22
3.3.3. {+restconf}/yang-library-version ...................22
3.4. Datastore Resource ........................................23
3.4.1. Edit Collision Prevention ..........................23
3.5. Data Resource .............................................24
3.5.1. Timestamp ..........................................25
3.5.2. Entity-Tag .........................................25
3.5.3. Encoding Data Resource Identifiers in the
Request URI ........................................26
3.5.4. Default Handling ...................................29
3.6. Operation Resource ........................................30
3.6.1. Encoding Operation Resource Input Parameters .......31
3.6.2. Encoding Operation Resource Output Parameters ......36
3.6.3. Encoding Operation Resource Errors .................38
3.7. Schema Resource ...........................................40
3.8. Event Stream Resource .....................................41
3.9. "errors" YANG Data Template ...............................41
4. RESTCONF Methods ...............................................42
4.1. OPTIONS ...................................................43
4.2. HEAD ......................................................43
4.3. GET .......................................................43
4.4. POST ......................................................45
1. Introduction ....................................................5
1.1. Terminology ................................................5
1.1.1. NETCONF .............................................6
1.1.2. HTTP ................................................6
1.1.3. YANG ................................................7
1.1.4. NETCONF Notifications ...............................7
1.1.5. Terms ...............................................8
1.1.6. URI Template and Examples ..........................10
1.1.7. Tree Diagrams ......................................11
1.2. Subset of NETCONF Functionality ...........................11
1.3. Data-Model-Driven API .....................................12
1.4. Coexistence with NETCONF ..................................13
1.5. RESTCONF Extensibility ....................................14
2. Transport Protocol .............................................15
2.1. Integrity and Confidentiality .............................15
2.2. HTTPS with X.509v3 Certificates ...........................16
2.3. Certificate Validation ....................................16
2.4. Authenticated Server Identity .............................16
2.5. Authenticated Client Identity .............................16
3. Resources ......................................................17
3.1. Root Resource Discovery ...................................18
3.2. RESTCONF Media Types ......................................20
3.3. API Resource ..............................................20
3.3.1. {+restconf}/data ...................................21
3.3.2. {+restconf}/operations .............................22
3.3.3. {+restconf}/yang-library-version ...................22
3.4. Datastore Resource ........................................23
3.4.1. Edit Collision Prevention ..........................23
3.5. Data Resource .............................................24
3.5.1. Timestamp ..........................................25
3.5.2. Entity-Tag .........................................25
3.5.3. Encoding Data Resource Identifiers in the
Request URI ........................................26
3.5.4. Default Handling ...................................29
3.6. Operation Resource ........................................30
3.6.1. Encoding Operation Resource Input Parameters .......31
3.6.2. Encoding Operation Resource Output Parameters ......36
3.6.3. Encoding Operation Resource Errors .................38
3.7. Schema Resource ...........................................40
3.8. Event Stream Resource .....................................41
3.9. "errors" YANG Data Template ...............................41
4. RESTCONF Methods ...............................................42
4.1. OPTIONS ...................................................43
4.2. HEAD ......................................................43
4.3. GET .......................................................43
4.4. POST ......................................................45
4.4.1. Create Resource Mode ...............................45
4.4.2. Invoke Operation Mode ..............................47
4.5. PUT .......................................................48
4.6. PATCH .....................................................50
4.6.1. Plain Patch ........................................50
4.7. DELETE ....................................................51
4.8. Query Parameters ..........................................52
4.8.1. The "content" Query Parameter ......................54
4.8.2. The "depth" Query Parameter ........................54
4.8.3. The "fields" Query Parameter .......................55
4.8.4. The "filter" Query Parameter .......................56
4.8.5. The "insert" Query Parameter .......................57
4.8.6. The "point" Query Parameter ........................57
4.8.7. The "start-time" Query Parameter ...................58
4.8.8. The "stop-time" Query Parameter ....................58
4.8.9. The "with-defaults" Query Parameter ................59
5. Messages .......................................................60
5.1. Request URI Structure .....................................61
5.2. Message Encoding ..........................................62
5.3. RESTCONF Metadata .........................................63
5.3.1. XML Metadata Encoding Example ......................64
5.3.2. JSON Metadata Encoding Example .....................65
5.4. Return Status .............................................65
5.5. Message Caching ...........................................66
6. Notifications ..................................................66
6.1. Server Support ............................................66
6.2. Event Streams .............................................67
6.3. Subscribing to Receive Notifications ......................68
6.3.1. NETCONF Event Stream ...............................70
6.4. Receiving Event Notifications .............................70
7. Error Reporting ................................................73
7.1. Error Response Message ....................................75
8. RESTCONF Module ................................................79
9. RESTCONF Monitoring ............................................85
9.1. restconf-state/capabilities ...............................86
9.1.1. Query Parameter URIs ...............................87
9.1.2. The "defaults" Protocol Capability URI .............87
9.2. restconf-state/streams ....................................88
9.3. RESTCONF Monitoring Module ................................89
10. YANG Module Library ...........................................93
10.1. modules-state/module .....................................93
11. IANA Considerations ...........................................94
11.1. The "restconf" Relation Type .............................94
11.2. Registrations for New URIs and YANG Modules ..............94
11.3. Media Types ..............................................95
11.3.1. Media Type "application/yang-data+xml" ............95
11.3.2. Media Type "application/yang-data+json" ...........96
4.4.1. Create Resource Mode ...............................45
4.4.2. Invoke Operation Mode ..............................47
4.5. PUT .......................................................48
4.6. PATCH .....................................................50
4.6.1. Plain Patch ........................................50
4.7. DELETE ....................................................51
4.8. Query Parameters ..........................................52
4.8.1. The "content" Query Parameter ......................54
4.8.2. The "depth" Query Parameter ........................54
4.8.3. The "fields" Query Parameter .......................55
4.8.4. The "filter" Query Parameter .......................56
4.8.5. The "insert" Query Parameter .......................57
4.8.6. The "point" Query Parameter ........................57
4.8.7. The "start-time" Query Parameter ...................58
4.8.8. The "stop-time" Query Parameter ....................58
4.8.9. The "with-defaults" Query Parameter ................59
5. Messages .......................................................60
5.1. Request URI Structure .....................................61
5.2. Message Encoding ..........................................62
5.3. RESTCONF Metadata .........................................63
5.3.1. XML Metadata Encoding Example ......................64
5.3.2. JSON Metadata Encoding Example .....................65
5.4. Return Status .............................................65
5.5. Message Caching ...........................................66
6. Notifications ..................................................66
6.1. Server Support ............................................66
6.2. Event Streams .............................................67
6.3. Subscribing to Receive Notifications ......................68
6.3.1. NETCONF Event Stream ...............................70
6.4. Receiving Event Notifications .............................70
7. Error Reporting ................................................73
7.1. Error Response Message ....................................75
8. RESTCONF Module ................................................79
9. RESTCONF Monitoring ............................................85
9.1. restconf-state/capabilities ...............................86
9.1.1. Query Parameter URIs ...............................87
9.1.2. The "defaults" Protocol Capability URI .............87
9.2. restconf-state/streams ....................................88
9.3. RESTCONF Monitoring Module ................................89
10. YANG Module Library ...........................................93
10.1. modules-state/module .....................................93
11. IANA Considerations ...........................................94
11.1. The "restconf" Relation Type .............................94
11.2. Registrations for New URIs and YANG Modules ..............94
11.3. Media Types ..............................................95
11.3.1. Media Type "application/yang-data+xml" ............95
11.3.2. Media Type "application/yang-data+json" ...........96
11.4. RESTCONF Capability URNs .................................97
11.5. Registration of "restconf" URN Sub-namespace .............98
12. Security Considerations .......................................99
13. References ...................................................100
13.1. Normative References ....................................100
13.2. Informative References ..................................104
Appendix A. Example YANG Module ..................................105
A.1. "example-jukebox" YANG Module .............................106
Appendix B. RESTCONF Message Examples ............................112
B.1. Resource Retrieval Examples ...............................112
B.1.1. Retrieve the Top-Level API Resource ...................112
B.1.2. Retrieve the Server Module Information ................114
B.1.3. Retrieve the Server Capability Information ............117
B.2. Data Resource and Datastore Resource Examples .............118
B.2.1. Create New Data Resources .............................118
B.2.2. Detect Datastore Resource Entity-Tag Change ...........119
B.2.3. Edit a Datastore Resource .............................121
B.2.4. Replace a Datastore Resource ..........................122
B.2.5. Edit a Data Resource ..................................122
B.3. Query Parameter Examples ..................................123
B.3.1. "content" Parameter ...................................123
B.3.2. "depth" Parameter .....................................126
B.3.3. "fields" Parameter ....................................130
B.3.4. "insert" Parameter ....................................132
B.3.5. "point" Parameter .....................................133
B.3.6. "filter" Parameter ....................................134
B.3.7. "start-time" Parameter ................................134
B.3.8. "stop-time" Parameter .................................135
B.3.9. "with-defaults" Parameter .............................135
Acknowledgements .................................................137
Authors' Addresses ...............................................137
11.4. RESTCONF Capability URNs .................................97
11.5. Registration of "restconf" URN Sub-namespace .............98
12. Security Considerations .......................................99
13. References ...................................................100
13.1. Normative References ....................................100
13.2. Informative References ..................................104
Appendix A. Example YANG Module ..................................105
A.1. "example-jukebox" YANG Module .............................106
Appendix B. RESTCONF Message Examples ............................112
B.1. Resource Retrieval Examples ...............................112
B.1.1. Retrieve the Top-Level API Resource ...................112
B.1.2. Retrieve the Server Module Information ................114
B.1.3. Retrieve the Server Capability Information ............117
B.2. Data Resource and Datastore Resource Examples .............118
B.2.1. Create New Data Resources .............................118
B.2.2. Detect Datastore Resource Entity-Tag Change ...........119
B.2.3. Edit a Datastore Resource .............................121
B.2.4. Replace a Datastore Resource ..........................122
B.2.5. Edit a Data Resource ..................................122
B.3. Query Parameter Examples ..................................123
B.3.1. "content" Parameter ...................................123
B.3.2. "depth" Parameter .....................................126
B.3.3. "fields" Parameter ....................................130
B.3.4. "insert" Parameter ....................................132
B.3.5. "point" Parameter .....................................133
B.3.6. "filter" Parameter ....................................134
B.3.7. "start-time" Parameter ................................134
B.3.8. "stop-time" Parameter .................................135
B.3.9. "with-defaults" Parameter .............................135
Acknowledgements .................................................137
Authors' Addresses ...............................................137
There is a need for standard mechanisms to allow Web applications to access the configuration data, state data, data-model-specific Remote Procedure Call (RPC) operations, and event notifications within a networking device, in a modular and extensible manner.
需要标准机制来允许Web应用程序以模块化和可扩展的方式访问网络设备内的配置数据、状态数据、数据模型特定远程过程调用（RPC）操作和事件通知。
This document defines a protocol based on HTTP [RFC7230] called "RESTCONF", for configuring data defined in YANG version 1 [RFC6020] or YANG version 1.1 [RFC7950], using the datastore concepts defined in the Network Configuration Protocol (NETCONF) [RFC6241].
本文档定义了一个基于HTTP[RFC7230]的协议，称为“RESTCONF”，用于使用网络配置协议（NETCONF）[RFC6241]中定义的数据存储概念，配置YANG版本1[RFC6020]或YANG版本1.1[RFC7950]中定义的数据。
NETCONF defines configuration datastores and a set of Create, Read, Update, Delete (CRUD) operations that can be used to access these datastores. NETCONF also defines a protocol for invoking these operations. The YANG language defines the syntax and semantics of datastore content, configuration, state data, RPC operations, and event notifications.
NETCONF定义了配置数据存储和一组可用于访问这些数据存储的创建、读取、更新、删除（CRUD）操作。NETCONF还定义了调用这些操作的协议。YANG语言定义了数据存储内容、配置、状态数据、RPC操作和事件通知的语法和语义。
RESTCONF uses HTTP methods to provide CRUD operations on a conceptual datastore containing YANG-defined data, which is compatible with a server that implements NETCONF datastores.
RESTCONF使用HTTP方法在包含定义数据的概念数据存储上提供CRUD操作，该数据存储与实现NETCONF数据存储的服务器兼容。
If a RESTCONF server is co-located with a NETCONF server, then there are protocol interactions with the NETCONF protocol; these interactions are described in Section 1.4. The RESTCONF server MAY provide access to specific datastores using operation resources, as described in Section 3.6. The RESTCONF protocol does not specify any mandatory operation resources. The semantics of each operation resource determine if and how datastores are accessed.
如果RESTCONF服务器与NETCONF服务器位于同一位置，则存在与NETCONF协议的协议交互；第1.4节描述了这些相互作用。RESTCONF服务器可以使用操作资源提供对特定数据存储的访问，如第3.6节所述。RESTCONF协议没有指定任何必需的操作资源。每个操作资源的语义决定是否以及如何访问数据存储。
Configuration data and state data are exposed as resources that can be retrieved with the GET method. Resources representing configuration data can be modified with the DELETE, PATCH, POST, and PUT methods. Data is encoded with either XML [W3C.REC-xml-20081126] or JSON [RFC7159].
配置数据和状态数据作为资源公开，可以使用GET方法检索。可以使用DELETE、PATCH、POST和PUT方法修改表示配置数据的资源。数据用XML[W3C.REC-XML-20081126]或JSON[RFC7159]编码。
Data-model-specific RPC operations defined with the YANG "rpc" or "action" statements can be invoked with the POST method. Data-model-specific event notifications defined with the YANG "notification" statement can be accessed.
可以使用POST方法调用使用“RPC”或“action”语句定义的特定于数据模型的RPC操作。可以访问使用“notification”语句定义的特定于数据模型的事件通知。
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 candidate configuration datastore
o 候选配置数据存储
o configuration data
o 配置数据
o datastore
o 数据存储
o configuration datastore
o 配置数据存储
o running configuration datastore
o 运行配置数据存储
o startup configuration datastore
o 启动配置数据存储
o state data
o 状态数据
o user
o 使用者
The following terms are defined in [RFC3986]:
[RFC3986]中定义了以下术语：
o fragment
o 碎片
o path
o 路径
o query
o 查询
The following terms are defined in [RFC7230]:
[RFC7230]中定义了以下术语：
o header field
o 标题字段
o message-body
o 消息体
o request-line
o 请求行
o request URI
o 请求URI
o status-line
o 状态行
The following terms are defined in [RFC7231]:
[RFC7231]中定义了以下术语：
o method
o 方法
o request
o 要求
o resource
o 资源
The following term is defined in [RFC7232]:
[RFC7232]中定义了以下术语：
o entity-tag
o 实体标签
The following terms are defined in [RFC7950]:
[RFC7950]中定义了以下术语：
o action
o 行动
o container
o 容器
o data node
o 数据节点
o key leaf
o 钥匙片
o leaf
o 叶
o leaf-list
o 叶列表
o list
o 列表
o mandatory node
o 强制节点
o ordered-by user
o 按用户订购
o presence container
o 存在容器
o RPC operation
o RPC操作
o top-level data node
o 顶级数据节点
The following term is defined in [RFC5277]:
[RFC5277]中定义了以下术语：
o notification replay
o 通知重播
The following terms are used within this document:
本文件中使用了以下术语：
o API resource: the resource that models the RESTCONF root resource and the sub-resources to access YANG-defined content. It is defined with the YANG data template named "yang-api" in the "ietf-restconf" module.
o API资源：为RESTCONF根资源和子资源建模以访问已定义内容的资源。它是用“ietf restconf”模块中名为“YANG api”的YANG数据模板定义的。
o client: a RESTCONF client.
o 客户机：RESTCONF客户机。
o data resource: a resource that models a YANG data node. It is defined with YANG data definition statements.
o 数据资源：为数据节点建模的资源。它是用数据定义语句定义的。
o datastore resource: the resource that models a programmatic interface using NETCONF datastore concepts. By default, RESTCONF methods access a unified view of the underlying datastore implementation on the server. It is defined as a sub-resource within the API resource.
o 数据存储资源：使用NETCONF数据存储概念对编程接口建模的资源。默认情况下，RESTCONF方法访问服务器上底层数据存储实现的统一视图。它被定义为API资源中的子资源。
o edit operation: a RESTCONF operation on a data resource using either a POST, PUT, PATCH, or DELETE method. This is not the same as the NETCONF edit operation (i.e., one of the values for the "nc:operation" attribute: "create", "replace", "merge", "delete", or "remove").
o 编辑操作：使用POST、PUT、PATCH或DELETE方法对数据资源执行RESTCONF操作。这与NETCONF编辑操作不同（即“nc:operation”属性的一个值：“创建”、“替换”、“合并”、“删除”或“删除”）。
o event stream resource: a resource that represents an SSE (Server-Sent Events) event stream. The content consists of text using the media type "text/event-stream", as defined by the SSE specification [W3C.REC-eventsource-20150203]. Event stream contents are described in Section 3.8.
o 事件流资源：表示SSE（服务器发送事件）事件流的资源。内容包括使用SSE规范[W3C.REC-eventsource-20150203]定义的媒体类型“文本/事件流”的文本。第3.8节描述了事件流内容。
o media type: HTTP uses Internet media types [RFC2046] in the "Content-Type" and "Accept" header fields in order to provide open and extensible data typing and type negotiation.
o 媒体类型：HTTP在“内容类型”和“接受”标题字段中使用Internet媒体类型[RFC2046]，以便提供开放和可扩展的数据类型和类型协商。
o NETCONF client: a client that implements the NETCONF protocol. Called "client" in [RFC6241].
o NETCONF客户端：实现NETCONF协议的客户端。在[RFC6241]中称为“客户机”。
o NETCONF server: a server that implements the NETCONF protocol. Called "server" in [RFC6241].
o NETCONF服务器：实现NETCONF协议的服务器。在[RFC6241]中称为“服务器”。
o operation: the conceptual RESTCONF operation for a message, derived from the HTTP method, request URI, header fields, and message-body.
o 操作：消息的概念性RESTCONF操作，派生自HTTP方法、请求URI、头字段和消息体。
o operation resource: a resource that models a data-model-specific operation that is in turn defined with a YANG "rpc" or "action" statement. It is invoked with the POST method.
o 操作资源：为数据模型特定的操作建模的资源，该操作由“rpc”或“action”语句定义。它是通过POST方法调用的。
o patch: a PATCH method on the target datastore or data resource. The media type of the message-body content will identify the patch type in use.
o 补丁：目标数据存储或数据资源上的补丁方法。消息正文内容的媒体类型将标识正在使用的修补程序类型。
o plain patch: a specific media type for use with the PATCH method; see Section 4.6.1. It can be used for simple "merge" edit operations. It is specified by a request Content-Type of "application/yang-data+xml" or "application/yang-data+json".
o 普通补丁：与补丁方法一起使用的特定媒体类型；见第4.6.1节。它可以用于简单的“合并”编辑操作。它由请求内容类型“application/yang data+xml”或“application/yang data+json”指定。
o query parameter: a parameter (and its value, if any), encoded within the query component of the request URI.
o 查询参数：在请求URI的查询组件中编码的参数（及其值，如果有）。
o resource type: one of the RESTCONF resource classes defined in this document. One of "api", "datastore", "data", "operation", "schema", or "event stream".
o 资源类型：本文档中定义的RESTCONF资源类之一。“api”、“数据存储”、“数据”、“操作”、“模式”或“事件流”之一。
o RESTCONF capability: an optional RESTCONF protocol feature that is advertised by a particular server if the feature is supported on that server. The feature is identified by an IANA-registered NETCONF Capability URI and advertised with an entry in the "capability" leaf-list defined in Section 9.3.
o RESTCONF功能：一种可选的RESTCONF协议功能，如果该功能在特定服务器上受支持，则由该服务器公布。该功能由一个IANA注册的NETCONF功能URI标识，并在第9.3节定义的“功能”叶列表中用一个条目发布。
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 retrieval request: a request using the GET or HEAD methods.
o 检索请求：使用GET或HEAD方法的请求。
o schema resource: a resource that is used by the client to retrieve a YANG schema with the GET method. It has a representation with the media type "application/yang".
o schema resource：客户端用于使用GET方法检索模式的资源。它有一个媒体类型为“application/yang”的表示。
o server: a RESTCONF server.
o 服务器：RESTCONF服务器。
o "stream" list: the set of data resource instances that describe the event stream resources available from the server. This information is defined in the "ietf-restconf-monitoring" module as the "stream" list. It can be retrieved using the target resource "{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ stream". The "stream" list contains information about each stream, such as the URL to retrieve the event stream data.
o “流”列表：描述服务器可用事件流资源的数据资源实例集。该信息在“ietf restconf监控”模块中定义为“流”列表。可以使用目标资源“{+restconf}/data/ietf restconf monitoring:restconf state/streams/stream”检索它。“流”列表包含关于每个流的信息，例如检索事件流数据的URL。
o stream resource: an event stream resource.
o 流资源：事件流资源。
o target resource: the resource that is associated with a particular message, identified by the "path" component of the request URI.
o 目标资源：与特定消息关联的资源，由请求URI的“路径”组件标识。
o yang-data extension: a YANG external statement that conforms to the "yang-data" extension statement, found in Section 8. The yang-data extension is used to define YANG data structures that are meant to be used as YANG data templates. These data structures are not intended to be implemented as part of a configuration datastore or as an operational state within the server, so normal YANG data definition statements cannot be used.
o yang数据扩展：符合第8节“yang数据”扩展语句的yang外部语句。yang数据扩展用于定义用作yang数据模板的yang数据结构。这些数据结构不打算作为配置数据存储的一部分或作为服务器内的操作状态来实现，因此不能使用正常的数据定义语句。
o YANG data template: a schema for modeling protocol message components as conceptual data structures using YANG. This allows the messages to be defined in an encoding-independent manner. Each YANG data template is defined with the "yang-data" extension, found in Section 8. Representations of instances conforming to a particular YANG data template can be defined for YANG. The XML representation is defined in YANG version 1.1 [RFC7950] and supported with the "application/yang-data+xml" media type. The JSON representation is defined in "JSON Encoding of Data Modeled with YANG" [RFC7951] and supported with the "application/yang-data+json" media type.
o YANG数据模板：使用YANG将协议消息组件建模为概念数据结构的模式。这允许以独立于编码的方式定义消息。每个YANG数据模板都定义了“YANG数据”扩展，见第8节。可以为YANG定义符合特定YANG数据模板的实例表示。XML表示在YANG版本1.1[RFC7950]中定义，并由“application/YANG data+XML”媒体类型支持。JSON表示在“使用YANG建模的数据的JSON编码”[RFC7951]中定义，并由“application/YANG Data+JSON”媒体类型支持。
Throughout this document, the URI template [RFC6570] syntax "{+restconf}" is used to refer to the RESTCONF root resource outside of an example. See Section 3.1 for details.
在本文档中，URI模板[RFC6570]语法“{+restconf}”用于引用示例之外的restconf根资源。详见第3.1节。
For simplicity, all of the examples in this document use "/restconf" as the discovered RESTCONF API root path. Many of the examples throughout the document are based on the "example-jukebox" YANG module defined in Appendix A.1.
为简单起见，本文中的所有示例都使用“/restconf”作为发现的restconf API根路径。本文件中的许多示例都基于附录A.1中定义的“示例光盘机”模块。
Many protocol header lines and message-body text within examples throughout the 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, "!" means a presence container, 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 省略号（“…”）表示未显示的子树的内容。
RESTCONF does not need to mirror the full functionality of the NETCONF protocol, but it does need to be compatible with NETCONF. RESTCONF achieves this by implementing a subset of the interaction capabilities provided by the NETCONF protocol -- for instance, by eliminating datastores and explicit locking.
RESTCONF不需要镜像NETCONF协议的全部功能，但它需要与NETCONF兼容。RESTCONF通过实现NETCONF协议提供的交互功能的子集来实现这一点，例如，通过消除数据存储和显式锁定。
RESTCONF uses HTTP methods to implement the equivalent of NETCONF operations, enabling basic CRUD operations on a hierarchy of conceptual resources.
RESTCONF使用HTTP方法实现与NETCONF操作等效的操作，在概念资源的层次结构上启用基本的CRUD操作。
The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data resources represented by YANG data models. These basic edit operations allow the running configuration to be altered by a RESTCONF client.
HTTP POST、PUT、PATCH和DELETE方法用于编辑由数据模型表示的数据资源。这些基本编辑操作允许RESTCONF客户端更改正在运行的配置。
RESTCONF is not intended to replace NETCONF, but rather to provide an HTTP interface that follows Representational State Transfer (REST) principles [REST-Dissertation] and is compatible with the NETCONF datastore model.
RESTCONF的目的不是取代NETCONF，而是提供一个遵循表示性状态转移（REST）原则[REST]并与NETCONF数据存储模型兼容的HTTP接口。
RESTCONF combines the simplicity of HTTP with the predictability and automation potential of a schema-driven API. Knowing the YANG modules used by the server, a client can derive all management resource URLs and the proper structure of all RESTCONF requests and responses. This strategy obviates the need for responses provided by the server to contain Hypermedia as the Engine of Application State (HATEOAS) links, originally described in Roy Fielding's doctoral dissertation [REST-Dissertation], because the client can determine the links it needs from the YANG modules.
RESTCONF将HTTP的简单性与模式驱动API的可预测性和自动化潜力结合起来。了解服务器使用的模块后，客户机可以派生所有管理资源URL以及所有RESTCONF请求和响应的适当结构。这种策略避免了服务器提供的响应需要包含超媒体作为应用程序状态引擎（HATEOAS）链接的情况，这一点最初在Roy Fielding的博士论文[REST论文]中进行了描述，因为客户端可以从模块中确定它需要的链接。
RESTCONF utilizes the YANG library [RFC7895] to allow a client to discover the YANG module conformance information for the server, in case the client wants to use it.
RESTCONF利用YANG库[RFC7895]允许客户机发现服务器的YANG模块一致性信息，以防客户机想要使用它。
The server can optionally support the retrieval of the YANG modules it uses, as identified in its YANG library. See Section 3.7 for details.
服务器可以选择支持检索其使用的YANG模块，如其YANG库中所示。详见第3.7节。
The URIs for data-model-specific RPC operations and datastore content are predictable, based on the YANG module definitions.
基于模块定义，数据模型特定RPC操作和数据存储内容的URI是可预测的。
The RESTCONF protocol operates on a conceptual datastore defined with the YANG data modeling language. The server lists each YANG module it supports using the "ietf-yang-library" YANG module defined in [RFC7895]. The server MUST implement the "ietf-yang-library" module, which MUST identify all of the YANG modules used by the server, in the "modules-state/module" list. The conceptual datastore contents, data-model-specific RPC operations, and event notifications are identified by this set of YANG modules.
RESTCONF协议在使用数据建模语言定义的概念数据存储上运行。服务器使用[RFC7895]中定义的“ietf YANG library”YANG模块列出其支持的每个YANG模块。服务器必须实现“ietf yang library”模块，该模块必须在“模块状态/模块”列表中标识服务器使用的所有yang模块。概念数据存储内容、特定于数据模型的RPC操作和事件通知由这组模块标识。
The classification of data as configuration data or non-configuration data is derived from the YANG "config" statement. Behavior related to the ordering of data is derived from the YANG "ordered-by" statement. Non-configuration data is also called "state data".
将数据分类为配置数据或非配置数据来自于“config”语句。与数据排序相关的行为源自YANG“ordered by”语句。非配置数据也称为“状态数据”。
The RESTCONF datastore editing model is simple and direct, similar to the behavior of the :writable-running capability in NETCONF. Each RESTCONF edit of a data resource within the datastore resource is activated upon successful completion of the edit.
RESTCONF数据存储编辑模型简单直接，类似于NETCONF中的：writable running功能的行为。成功完成编辑后，将激活数据存储资源中数据资源的每个RESTCONF编辑。
RESTCONF can be implemented on a device that supports the NETCONF protocol.
RESTCONF可以在支持NETCONF协议的设备上实现。
The following figure shows the system components if a RESTCONF server is co-located with a NETCONF server:
下图显示了RESTCONF服务器与NETCONF服务器共存时的系统组件：
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------+ | +-----------+ |
| NETCONF | <-------> | | datastore | |
| Client | NETCONF | | | |
+-----------+ | +-----------+ |
+-----------------+
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------+ | +-----------+ |
| NETCONF | <-------> | | datastore | |
| Client | NETCONF | | | |
+-----------+ | +-----------+ |
+-----------------+
The following figure shows the system components if a RESTCONF server is implemented in a device that does not have a NETCONF server:
下图显示了在没有NETCONF服务器的设备中实现RESTCONF服务器时的系统组件：
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------------+
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------------+
There are interactions between the NETCONF protocol and RESTCONF protocol related to edit operations. It is possible that locks are in use on a RESTCONF server, even though RESTCONF cannot manipulate locks. In such a case, the RESTCONF protocol will not be granted write access to data resources within a datastore.
NETCONF协议和RESTCONF协议之间存在与编辑操作相关的交互。RESTCONF服务器上可能正在使用锁，即使RESTCONF无法操作锁。在这种情况下，RESTCONF协议将不会被授予对数据存储中的数据资源的写访问权限。
If the NETCONF server supports :writable-running, all edits to configuration nodes in {+restconf}/data are performed in the running configuration datastore. The URI template "{+restconf}" is defined in Section 1.1.6.
如果NETCONF服务器支持：writable running，则对{+restconf}/data中配置节点的所有编辑都在运行的配置数据存储中执行。URI模板“{+restconf}”在第1.1.6节中定义。
Otherwise, if the device supports :candidate, all edits to configuration nodes in {+restconf}/data are performed in the candidate configuration datastore. The candidate MUST be automatically committed to running immediately after each successful edit. Any edits from other sources that are in the candidate datastore will also be committed. If a confirmed commit procedure is in progress by any NETCONF client, then any new commit will act as the confirming commit. If the NETCONF server is expecting a
否则，如果设备支持：candidate，则对{+restconf}/data中的配置节点的所有编辑都将在候选配置数据存储中执行。候选人必须在每次成功编辑后立即自动提交运行。来自候选数据存储中其他源的任何编辑也将提交。如果任何NETCONF客户端正在执行确认提交过程，则任何新提交都将作为确认提交。如果NETCONF服务器需要
"persist-id" parameter to complete the confirmed commit procedure, then the RESTCONF edit operation MUST fail with a "409 Conflict" status-line. The error-tag "in-use" is used in this case.
“persist id”参数以完成确认的提交过程，则RESTCONF编辑操作必须失败，并显示“409冲突”状态行。本例中使用了错误标记“正在使用”。
If the NETCONF server supports :startup, the RESTCONF server MUST automatically update the non-volatile startup configuration datastore, after the "running" datastore has been altered as a consequence of a RESTCONF edit operation.
如果NETCONF服务器支持：startup，则RESTCONF服务器必须在RESTCONF编辑操作改变“正在运行”的数据存储后自动更新非易失性启动配置数据存储。
If a datastore that would be modified by a RESTCONF operation has an active lock from a NETCONF client, the RESTCONF edit operation MUST fail with a "409 Conflict" status-line. The error-tag value "in-use" is returned in this case.
如果将由RESTCONF操作修改的数据存储具有来自NETCONF客户端的活动锁，则RESTCONF编辑操作必须失败，并显示“409冲突”状态行。在这种情况下，返回错误标记值“正在使用”。
There are two extensibility mechanisms built into RESTCONF:
RESTCONF中内置了两种扩展机制：
o protocol version
o 协议版本
o optional capabilities
o 可选功能
This document defines version 1 of the RESTCONF protocol. If a future version of this protocol is defined, then that document will specify how the new version of RESTCONF is identified. It is expected that a different RESTCONF root resource will be used, which will be located using a different link relation (see Section 3.1).
本文档定义了RESTCONF协议的版本1。如果定义了此协议的未来版本，则该文档将指定如何识别新版本的RESTCONF。预计将使用不同的RESTCONF根资源，该资源将使用不同的链接关系定位（请参见第3.1节）。
The server will advertise all protocol versions that it supports in its host-meta data.
服务器将在其主机元数据中公布其支持的所有协议版本。
In this example, the server supports both RESTCONF version 1 and a fictitious version 2.
在本例中，服务器同时支持RESTCONF版本1和虚构的版本2。
The client might send the following:
客户端可能会发送以下内容：
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
<Link rel='restconf2' href='/restconf2'/>
</XRD>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
<Link rel='restconf2' href='/restconf2'/>
</XRD>
RESTCONF also supports a server-defined list of optional capabilities, which are listed by a server using the "ietf-restconf-monitoring" module defined in Section 9.3. This document defines several query parameters in Section 4.8. Each optional parameter has a corresponding capability URI, defined in Section 9.1.1, that is advertised by the server if supported.
RESTCONF还支持服务器定义的可选功能列表，这些功能由服务器使用第9.3节中定义的“ietf RESTCONF监控”模块列出。本文件在第4.8节中定义了几个查询参数。每个可选参数都有一个相应的功能URI，在9.1.1节中定义，如果支持，服务器会公布该URI。
The "capability" leaf-list can identify any sort of server extension. Currently, this extension mechanism is used to identify optional query parameters that are supported, but it is not limited to that purpose. For example, the "defaults" URI defined in Section 9.1.2 specifies a mandatory URI identifying server default-handling behavior.
“能力”叶列表可以识别任何类型的服务器扩展。目前，此扩展机制用于标识支持的可选查询参数，但不限于此目的。例如，第9.1.2节中定义的“默认”URI指定了一个标识服务器默认处理行为的强制URI。
A new sub-resource type could be identified with a capability if it is optional to implement. Mandatory protocol features and new resource types require a new revision of the RESTCONF protocol.
如果一个新的子资源类型是可选的，则可以通过一个功能来识别它。强制协议功能和新的资源类型要求对RESTCONF协议进行新的修订。
HTTP [RFC7230] is an application-layer protocol that may be layered on any reliable transport-layer protocol. RESTCONF is defined on top of HTTP, but due to the sensitive nature of the information conveyed, RESTCONF requires that the transport-layer protocol provide both data integrity and confidentiality. A RESTCONF server MUST support the Transport Layer Security (TLS) protocol [RFC5246] and SHOULD adhere to [RFC7525]. The RESTCONF protocol MUST NOT be used over HTTP without using the TLS protocol.
HTTP[RFC7230]是一种应用层协议，可以在任何可靠的传输层协议上分层。RESTCONF是在HTTP之上定义的，但由于所传递信息的敏感性，RESTCONF要求传输层协议同时提供数据完整性和机密性。RESTCONF服务器必须支持传输层安全（TLS）协议[RFC5246]，并应遵守[RFC7525]。在未使用TLS协议的情况下，不得通过HTTP使用RESTCONF协议。
RESTCONF does not require a specific version of HTTP. However, it is RECOMMENDED that at least HTTP/1.1 [RFC7230] be supported by all implementations.
RESTCONF不需要特定版本的HTTP。但是，建议所有实现至少支持HTTP/1.1[RFC7230]。
Given the nearly ubiquitous support for HTTP over TLS [RFC7230], RESTCONF implementations MUST support the "https" URI scheme, which has the IANA-assigned default port 443.
鉴于对HTTP over TLS[RFC7230]几乎无处不在的支持，RESTCONF实现必须支持“https”URI方案，该方案具有IANA分配的默认端口443。
RESTCONF servers MUST present an X.509v3-based certificate when establishing a TLS connection with a RESTCONF client. The use of X.509v3-based certificates is consistent with NETCONF over TLS [RFC7589].
当与RESTCONF客户端建立TLS连接时，RESTCONF服务器必须提供基于X.509v3的证书。基于X.509v3的证书的使用与TLS上的NETCONF一致[RFC7589]。
The RESTCONF client MUST either (1) use X.509 certificate path validation [RFC5280] to verify the integrity of the RESTCONF server's TLS certificate or (2) match the server's TLS certificate with a certificate obtained by a trusted mechanism (e.g., a pinned certificate). If X.509 certificate path validation fails and the presented X.509 certificate does not match a certificate obtained by a trusted mechanism, the connection MUST be terminated, as described in Section 7.2.1 of [RFC5246].
RESTCONF客户端必须（1）使用X.509证书路径验证[RFC5280]来验证RESTCONF服务器的TLS证书的完整性，或者（2）将服务器的TLS证书与通过受信任机制获得的证书（例如，固定证书）匹配。如果X.509证书路径验证失败，并且提供的X.509证书与受信任机制获得的证书不匹配，则必须终止连接，如[RFC5246]第7.2.1节所述。
The RESTCONF client MUST check the identity of the server according to Section 3.1 of [RFC2818].
RESTCONF客户端必须根据[RFC2818]的第3.1节检查服务器的标识。
The RESTCONF server MUST authenticate client access to any protected resource. If the RESTCONF client is not authenticated, the server SHOULD send an HTTP response with a "401 Unauthorized" status-line, as defined in Section 3.1 of [RFC7235]. The error-tag value "access-denied" is used in this case.
RESTCONF服务器必须验证客户端对任何受保护资源的访问。如果RESTCONF客户端未经过身份验证，服务器应发送一个HTTP响应，并带有[RFC7235]第3.1节中定义的“401 Unauthorized”状态行。在这种情况下使用错误标记值“拒绝访问”。
To authenticate a client, a RESTCONF server SHOULD require authentication based on TLS client certificates (Section 7.4.6 of [RFC5246]). If certificate-based authentication is not feasible (e.g., because one cannot build the required PKI for clients), then HTTP authentication MAY be used. In the latter case, one of the HTTP authentication schemes defined in the "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" (Section 5.1 in [RFC7235]) MUST be used.
要对客户端进行身份验证，RESTCONF服务器应要求基于TLS客户端证书进行身份验证（RFC5246第7.4.6节）。如果基于证书的身份验证不可行（例如，因为无法为客户端构建所需的PKI），则可以使用HTTP身份验证。在后一种情况下，必须使用“超文本传输协议（HTTP）认证方案注册表”（RFC7235中的第5.1节）中定义的HTTP认证方案之一。
A server MAY also support the combination of both client certificates and an HTTP client authentication scheme, with the determination of how to process this combination left as an implementation decision.
服务器还可以支持客户端证书和HTTP客户端身份验证方案的组合，如何处理该组合的确定作为实现决策。
The RESTCONF client identity derived from the authentication mechanism used is hereafter known as the "RESTCONF username" and subject to the NETCONF Access Control Model (NACM) [RFC6536]. When a client certificate is presented, the RESTCONF username MUST be derived using the algorithm defined in Section 7 of [RFC7589]. For all other cases, when HTTP authentication is used, the RESTCONF username MUST be provided by the HTTP authentication scheme used.
从使用的身份验证机制派生的RESTCONF客户端标识在下文中称为“RESTCONF用户名”，并受NETCONF访问控制模型（NACM）[RFC6536]的约束。提供客户端证书时，必须使用[RFC7589]第7节中定义的算法派生RESTCONF用户名。对于所有其他情况，当使用HTTP身份验证时，所使用的HTTP身份验证方案必须提供RESTCONF用户名。
The RESTCONF protocol operates on a hierarchy of resources, starting with the top-level API resource itself (Section 3.1). Each resource represents a manageable component within the device.
RESTCONF协议在资源层次结构上运行，从顶级API资源本身开始（第3.1节）。每个资源表示设备中的一个可管理组件。
A resource can be considered as a collection of data and the set of allowed methods on that data. It can contain nested child resources. The child resource types and the methods allowed on them are specific to the data model.
可以将资源视为数据的集合以及该数据上允许的方法集。它可以包含嵌套的子资源。子资源类型及其允许的方法特定于数据模型。
A resource has a representation associated with a media type identifier, as represented by the "Content-Type" header field in the HTTP response message. A resource has one or more representations, each associated with a different media type. When a representation of a resource is sent in an HTTP message, the associated media type is given in the "Content-Type" header. A resource can contain zero or more nested resources. A resource can be created and deleted independently of its parent resource, as long as the parent resource exists.
资源具有与媒体类型标识符关联的表示，如HTTP响应消息中的“内容类型”头字段所示。资源有一个或多个表示，每个表示都与不同的媒体类型相关联。在HTTP消息中发送资源表示时，“内容类型”标题中给出了相关的媒体类型。资源可以包含零个或多个嵌套资源。只要父资源存在，就可以独立于父资源创建和删除资源。
The RESTCONF resources are accessed via a set of URIs defined in this document. The set of YANG modules supported by the server will determine the data-model-specific RPC operations, top-level data nodes, and event notification messages supported by the server.
RESTCONF资源通过本文档中定义的一组uri进行访问。服务器支持的模块集将确定服务器支持的特定于数据模型的RPC操作、顶级数据节点和事件通知消息。
The RESTCONF protocol does not include a data resource discovery mechanism. Instead, the definitions within the YANG modules advertised by the server are used to construct an RPC operation or data resource identifier.
RESTCONF协议不包括数据资源发现机制。相反，服务器播发的模块中的定义用于构造RPC操作或数据资源标识符。
In line with the best practices defined by [RFC7320], RESTCONF enables deployments to specify where the RESTCONF API is located. When first connecting to a RESTCONF server, a RESTCONF client MUST determine the root of the RESTCONF API. There MUST be exactly one "restconf" link relation returned by the device.
根据[RFC7320]定义的最佳实践，RESTCONF允许部署指定RESTCONF API的位置。当第一次连接到RESTCONF服务器时，RESTCONF客户端必须确定RESTCONF API的根。设备必须返回一个“restconf”链接关系。
The client discovers this by getting the "/.well-known/host-meta" resource ([RFC6415]) and using the <Link> element containing the "restconf" attribute:
客户端通过获取“/.well-known/host meta”资源（[RFC6415]）并使用包含“restconf”属性的<Link>元素来发现这一点：
Example returning /restconf:
返回/restconf的示例：
The client might send the following:
客户端可能会发送以下内容：
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>
After discovering the RESTCONF API root, the client MUST use this value as the initial part of the path in the request URI, in any subsequent request for a RESTCONF resource.
在发现RESTCONF API根之后，客户机必须在RESTCONF资源的任何后续请求中使用此值作为请求URI中路径的初始部分。
In this example, the client would use the path "/restconf" as the RESTCONF root resource.
在本例中，客户机将使用路径“/restconf”作为restconf根资源。
Example returning /top/restconf:
返回/top/restconf的示例：
The client might send the following:
客户端可能会发送以下内容：
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/top/restconf'/>
</XRD>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/top/restconf'/>
</XRD>
In this example, the client would use the path "/top/restconf" as the RESTCONF root resource.
在本例中，客户机将使用路径“/top/restconf”作为restconf根资源。
The client can now determine the operation resources supported by the server. In this example, a custom "play" operation is supported:
客户端现在可以确定服务器支持的操作资源。在此示例中，支持自定义“播放”操作：
The client might send the following:
客户端可能会发送以下内容：
GET /top/restconf/operations HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /top/restconf/operations HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
Content-Type: application/yang-data+json
{ "operations" : { "example-jukebox:play" : [null] } }
{ "operations" : { "example-jukebox:play" : [null] } }
If the Extensible Resource Descriptor (XRD) contains more than one link relation, then only the relation named "restconf" is relevant to this specification.
如果可扩展资源描述符（XRD）包含多个链接关系，则只有名为“restconf”的关系与此规范相关。
Note that any given endpoint (host:port) can only support one RESTCONF server, due to the root resource discovery mechanism. This limits the number of RESTCONF servers that can run concurrently on a host, since each server must use a different port.
注意，由于根资源发现机制，任何给定的端点（主机：端口）只能支持一个RESTCONF服务器。这限制了可以在主机上并发运行的RESTCONF服务器的数量，因为每个服务器必须使用不同的端口。
The RESTCONF protocol defines two application-specific media types to identify representations of data that conforms to the schema for a particular YANG construct.
RESTCONF协议定义了两种特定于应用程序的媒体类型，以标识符合特定构造模式的数据表示。
This document defines media types for XML and JSON serialization of YANG data. Other documents MAY define other media types for different serializations of YANG data. The "application/yang-data+xml" media type is defined in Section 11.3.1. The "application/yang-data+json" media type is defined in Section 11.3.2.
本文档定义了数据的XML和JSON序列化的媒体类型。其他文档可能会为数据的不同序列化定义其他媒体类型。第11.3.1节定义了“应用程序/数据+xml”媒体类型。第11.3.2节定义了“应用程序/数据+json”媒体类型。
The API resource contains the RESTCONF root resource for the RESTCONF datastore and operation resources. It is the top-level resource located at {+restconf} and has the media type "application/yang-data+xml" or "application/yang-data+json".
API资源包含RESTCONF数据存储和操作资源的RESTCONF根资源。它是位于{+restconf}的顶级资源，媒体类型为“application/yang data+xml”或“application/yang data+json”。
YANG tree diagram for an API resource:
API资源的树图：
+---- {+restconf}
+---- data
| ...
+---- operations?
| ...
+--ro yang-library-version string
+---- {+restconf}
+---- data
| ...
+---- operations?
| ...
+--ro yang-library-version string
The "yang-api" YANG data template is defined using the "yang-data" extension in the "ietf-restconf" module, found in Section 8. It specifies the structure and syntax of the conceptual child resources within the API resource.
“yang api”yang数据模板是使用第8节“ietf restconf”模块中的“yang数据”扩展定义的。它指定API资源中概念子资源的结构和语法。
The API resource can be retrieved with the GET method.
可以使用GET方法检索API资源。
The {+restconf} root resource name used in responses representing the root of the "ietf-restconf" module MUST identify the "ietf-restconf" YANG module. For example, a request to GET the root resource "/restconf" in JSON format will return a representation of the API resource named "ietf-restconf:restconf".
响应中使用的{+restconf}根资源名称表示“ietf restconf”模块的根，必须标识“ietf restconf”模块。例如，以JSON格式获取根资源“/restconf”的请求将返回名为“ietf restconf:restconf”的API资源的表示形式。
This resource has the following child resources:
此资源具有以下子资源：
+----------------------+---------------------------------+
| Child Resource | Description |
+----------------------+---------------------------------+
| data | Contains all data resources |
| operations | Data-model-specific operations |
| yang-library-version | "ietf-yang-library" module date |
+----------------------+---------------------------------+
+----------------------+---------------------------------+
| Child Resource | Description |
+----------------------+---------------------------------+
| data | Contains all data resources |
| operations | Data-model-specific operations |
| yang-library-version | "ietf-yang-library" module date |
+----------------------+---------------------------------+
RESTCONF API Resource
RESTCONF API资源
This mandatory resource represents the combined configuration and state data resources that can be accessed by a client. It cannot be created or deleted by the client. The datastore resource type is defined in Section 3.4.
此强制资源表示客户端可以访问的组合配置和状态数据资源。客户端无法创建或删除它。第3.4节定义了数据存储资源类型。
Example:
例子：
This example request by the client would retrieve only the non-configuration data nodes that exist within the "library" resource, using the "content" query parameter (see Section 4.8.1).
客户机的此示例请求将使用“内容”查询参数仅检索“库”资源中存在的非配置数据节点（请参见第4.8.1节）。
GET /restconf/data/example-jukebox:jukebox/library\
?content=nonconfig HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf/data/example-jukebox:jukebox/library\
?content=nonconfig HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+xml
<library xmlns="https://example.com/ns/example-jukebox">
<artist-count>42</artist-count>
<album-count>59</album-count>
<song-count>374</song-count>
</library>
<library xmlns="https://example.com/ns/example-jukebox">
<artist-count>42</artist-count>
<album-count>59</album-count>
<song-count>374</song-count>
</library>
This optional resource is a container that provides access to the data-model-specific RPC operations supported by the server. The server MAY omit this resource if no data-model-specific RPC operations are advertised.
此可选资源是一个容器，提供对服务器支持的数据模型特定RPC操作的访问。如果没有公布特定于数据模型的RPC操作，服务器可能会忽略此资源。
Any data-model-specific RPC operations defined in the YANG modules advertised by the server MUST be available as child nodes of this resource.
服务器播发的模块中定义的任何特定于数据模型的RPC操作都必须作为此资源的子节点可用。
The access point for each RPC operation is represented as an empty leaf. If an operation resource is retrieved, the empty leaf representation is returned by the server.
每个RPC操作的访问点都表示为空叶。如果检索到操作资源，服务器将返回空叶表示。
Operation resources are defined in Section 3.6.
第3.6节定义了运营资源。
This mandatory leaf identifies the revision date of the "ietf-yang-library" YANG module that is implemented by this server. In the example that follows, the revision date for the module version found in [RFC7895] is used.
此必填页标识此服务器实现的“ietf yang library”yang模块的修订日期。在下面的示例中，使用[RFC7895]中找到的模块版本的修订日期。
Example:
例子：
GET /restconf/yang-library-version HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf/yang-library-version HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+xml
<yang-library-version
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">\
2016-06-21\
</yang-library-version>
<yang-library-version
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">\
2016-06-21\
</yang-library-version>
The "{+restconf}/data" subtree represents the datastore resource, which is a collection of configuration data and state data nodes.
“{+restconf}/data”子树表示数据存储资源，它是配置数据和状态数据节点的集合。
This resource type is an abstraction of the system's underlying datastore implementation. The client uses it to edit and retrieve data resources, as the conceptual root of all configuration and state data that is present on the device.
此资源类型是系统底层数据存储实现的抽象。客户端使用它来编辑和检索数据资源，作为设备上所有配置和状态数据的概念根。
Configuration edit transaction management and configuration persistence are handled by the server and not controlled by the client. A datastore resource can be written directly with the POST and PATCH methods. Each RESTCONF edit of a datastore resource is saved to non-volatile storage by the server if the server supports non-volatile storage of configuration data, as described in Section 1.4.
配置编辑事务管理和配置持久性由服务器处理，而不是由客户端控制。可以使用POST和PATCH方法直接写入数据存储资源。如第1.4节所述，如果服务器支持配置数据的非易失性存储，则数据存储资源的每个RESTCONF编辑将由服务器保存到非易失性存储。
If the datastore resource represented by the "{+restconf}/data" subtree is retrieved, then the datastore and its contents are returned by the server. The datastore is represented by a node named "data" in the "ietf-restconf" module namespace.
如果检索到由“{+restconf}/data”子树表示的数据存储资源，那么服务器将返回数据存储及其内容。数据存储由“ietf restconf”模块名称空间中名为“data”的节点表示。
Two edit collision detection and prevention mechanisms are provided in RESTCONF for the datastore resource: a timestamp and an entity-tag. Any change to configuration data resources updates the timestamp and entity-tag of the datastore resource. In addition, the RESTCONF server MUST return an error if the datastore is locked by an external source (e.g., NETCONF server).
RESTCONF为数据存储资源提供了两种编辑冲突检测和预防机制：时间戳和实体标记。对配置数据资源的任何更改都会更新数据存储资源的时间戳和实体标记。此外，如果数据存储被外部源（例如NETCONF服务器）锁定，RESTCONF服务器必须返回错误。
The last change time is maintained, and the "Last-Modified" header field (Section 2.2 of [RFC7232]) is returned in the response for a retrieval request. The "If-Unmodified-Since" header field (Section 3.4 of [RFC7232]) can be used in edit operation requests to cause the server to reject the request if the resource has been modified since the specified timestamp.
保留最后更改时间，并在检索请求的响应中返回“last Modified”标题字段（RFC7232的第2.2节）。“If Unmodified Since”标头字段（RFC7232的第3.4节）可用于编辑操作请求，以使服务器拒绝自指定时间戳后修改资源的请求。
The server SHOULD maintain a last-modified timestamp for the datastore resource, defined in Section 3.4. This timestamp is only affected by configuration child data resources and MUST NOT be updated for changes to non-configuration child data resources. Last-modified timestamps for data resources are discussed in Section 3.5.
服务器应为第3.4节中定义的数据存储资源维护最后修改的时间戳。此时间戳仅受配置子数据资源的影响，不得因对非配置子数据资源的更改而更新。第3.5节讨论了数据资源最后修改的时间戳。
If the RESTCONF server is co-located with a NETCONF server, then the last-modified timestamp MUST be for the "running" datastore. Note that it is possible that other protocols can cause the last-modified timestamp to be updated. Such mechanisms are out of scope for this document.
如果RESTCONF服务器与NETCONF服务器位于同一位置，那么最后修改的时间戳必须是“正在运行”的数据存储。请注意，其他协议可能会导致最后修改的时间戳被更新。此类机制超出了本文件的范围。
The server MUST maintain a unique opaque entity-tag for the datastore resource and MUST return it in the "ETag" (Section 2.3 of [RFC7232]) header in the response for a retrieval request. The client MAY use an "If-Match" header in edit operation requests to cause the server to reject the request if the resource entity-tag does not match the specified value.
服务器必须为数据存储资源维护一个唯一的不透明实体标记，并且必须在检索请求响应的“ETag”（RFC7232的第2.3节）头中返回该标记。如果资源实体标记与指定值不匹配，则客户端可以在编辑操作请求中使用“If Match”标头，以使服务器拒绝请求。
The server MUST maintain an entity-tag for the top-level {+restconf}/data resource. This entity-tag is only affected by configuration data resources and MUST NOT be updated for changes to non-configuration data. Entity-tags for data resources are discussed in Section 3.5. Note that each representation (e.g., XML vs. JSON) requires a different entity-tag.
服务器必须为顶级{+restconf}/data资源维护一个实体标记。此实体标记仅受配置数据资源的影响，不得因非配置数据的更改而更新。第3.5节讨论了数据资源的实体标记。请注意，每个表示（例如，XML与JSON）都需要不同的实体标记。
If the RESTCONF server is co-located with a NETCONF server, then this entity-tag MUST be for the "running" datastore. Note that it is possible that other protocols can cause the entity-tag to be updated. Such mechanisms are out of scope for this document.
如果RESTCONF服务器与NETCONF服务器位于同一位置，则此实体标记必须用于“正在运行”的数据存储。请注意，其他协议可能会导致实体标记被更新。此类机制超出了本文件的范围。
Changes to configuration data resources affect the timestamp and entity-tag for that resource, any ancestor data resources, and the datastore resource.
对配置数据资源的更改会影响该资源、任何祖先数据资源和数据存储资源的时间戳和实体标记。
For example, an edit to disable an interface might be done by setting the leaf "/interfaces/interface/enabled" to "false". The "enabled" data node and its ancestors (one "interface" list instance, and the "interfaces" container) are considered to be changed. The datastore is considered to be changed when any top-level configuration data node is changed (e.g., "interfaces").
例如，禁用接口的编辑可以通过将叶“/interfaces/interface/enabled”设置为“false”来完成。“已启用”数据节点及其祖先（一个“接口”列表实例和“接口”容器）被视为已更改。当任何顶级配置数据节点发生更改（例如，“接口”）时，数据存储被视为已更改。
A data resource represents a YANG data node that is a descendant node of a datastore resource. Each YANG-defined data node can be uniquely targeted by the request-line of an HTTP method. Containers, leafs, leaf-list entries, list entries, anydata nodes, and anyxml nodes are data resources.
数据资源表示数据节点，该数据节点是数据存储资源的子节点。HTTP方法的请求行可以唯一地将每个定义的数据节点作为目标。容器、叶、叶列表项、列表项、anydata节点和anyxml节点都是数据资源。
The representation maintained for each data resource is the YANG-defined subtree for that node. HTTP methods on a data resource affect both the targeted data node and all of its descendants, if any.
为每个数据资源维护的表示是为该节点定义的子树。数据资源上的HTTP方法会影响目标数据节点及其所有子节点（如果有）。
A data resource can be retrieved with the GET method. Data resources are accessed via the "{+restconf}/data" URI. This subtree is used to retrieve and edit data resources.
可以使用GET方法检索数据资源。通过“{+restconf}/Data”URI访问数据资源。此子树用于检索和编辑数据资源。
For configuration data resources, the server MAY maintain a last-modified timestamp for the resource and return the "Last-Modified" header field when it is retrieved with the GET or HEAD methods.
对于配置数据资源，服务器可以维护资源的上次修改时间戳，并在使用GET或HEAD方法检索时返回“last modified”报头字段。
The "Last-Modified" header field can be used by a RESTCONF client in subsequent requests, within the "If-Modified-Since" and "If-Unmodified-Since" header fields.
RESTCONF客户机可以在后续请求中使用“Last Modified”头字段，“If Modified Since”和“If Unmodified Since”头字段。
If maintained, the resource timestamp MUST be set to the current time whenever the resource or any configuration resource within the resource is altered. If not maintained, then the resource timestamp for the datastore MUST be used instead. If the RESTCONF server is co-located with a NETCONF server, then the last-modified timestamp for a configuration data resource MUST represent the instance within the "running" datastore.
如果保持，则无论何时更改资源或资源中的任何配置资源，都必须将资源时间戳设置为当前时间。如果未维护，则必须使用数据存储的资源时间戳。如果RESTCONF服务器与NETCONF服务器位于同一位置，那么配置数据资源的最后修改时间戳必须表示“正在运行”数据存储中的实例。
This timestamp is only affected by configuration data resources and MUST NOT be updated for changes to non-configuration data.
此时间戳仅受配置数据资源的影响，不得因非配置数据的更改而更新。
For configuration data resources, the server SHOULD maintain a resource entity-tag for each resource and return the "ETag" header field when it is retrieved as the target resource with the GET or HEAD methods. If maintained, the resource entity-tag MUST be updated whenever the resource or any configuration resource within the resource is altered. If not maintained, then the resource entity-tag for the datastore MUST be used instead.
对于配置数据资源，服务器应该为每个资源维护一个资源实体标记，并在使用GET或HEAD方法将其作为目标资源检索时返回“ETag”头字段。如果维护，则无论何时更改资源或资源中的任何配置资源，都必须更新资源实体标记。如果未维护，则必须使用数据存储的资源实体标记。
The "ETag" header field can be used by a RESTCONF client in subsequent requests, within the "If-Match" and "If-None-Match" header fields.
RESTCONF客户机可以在后续请求中使用“ETag”头字段，“If Match”和“If None Match”头字段。
This entity-tag is only affected by configuration data resources and MUST NOT be updated for changes to non-configuration data. If the RESTCONF server is co-located with a NETCONF server, then the entity-tag for a configuration data resource MUST represent the instance within the "running" datastore.
此实体标记仅受配置数据资源的影响，不得因非配置数据的更改而更新。如果RESTCONF服务器与NETCONF服务器位于同一位置，那么配置数据资源的实体标记必须表示“正在运行”数据存储中的实例。
In YANG, data nodes can be identified with an absolute XPath expression, defined in [XPath], starting from the document root to the target resource. In RESTCONF, URI-encoded path expressions are used instead.
在YANG中，可以使用[XPath]中定义的绝对XPath表达式标识数据节点，从文档根到目标资源。在RESTCONF中，使用URI编码的路径表达式。
A predictable location for a data resource is important, since applications will code to the YANG data model module, which uses static naming and defines an absolute path location for all data nodes.
数据资源的可预测位置很重要，因为应用程序将编码到YANG数据模型模块，该模块使用静态命名并为所有数据节点定义绝对路径位置。
A RESTCONF data resource identifier is encoded from left to right, starting with the top-level data node, according to the "api-path" rule in Section 3.5.3.1. The node name of each ancestor of the target resource node is encoded in order, ending with the node name for the target resource. If a node in the path is defined in a module other than its parent node or its parent is the datastore, then the module name followed by a colon character (":") MUST be prepended to the node name in the resource identifier. See Section 3.5.3.1 for details.
根据第3.5.3.1节中的“api路径”规则，RESTCONF数据资源标识符从左到右编码，从顶级数据节点开始。目标资源节点的每个祖先的节点名按顺序编码，以目标资源的节点名结尾。如果路径中的节点是在其父节点以外的模块中定义的，或者其父节点是数据存储，则必须在资源标识符中的节点名称前面加上模块名称和冒号（“：”）。详见第3.5.3.1节。
If a data node in the path expression is a YANG leaf-list node, then the leaf-list value MUST be encoded according to the following rules:
如果路径表达式中的数据节点是YANG叶列表节点，则必须根据以下规则对叶列表值进行编码：
o The identifier for the leaf-list MUST be encoded using one path segment [RFC3986].
o 叶列表的标识符必须使用一个路径段[RFC3986]进行编码。
o The path segment is constructed by having the leaf-list name, followed by an "=" character, followed by the leaf-list value (e.g., /restconf/data/top-leaflist=fred).
o 路径段由叶列表名称、一个“=”字符和叶列表值（例如，/restconf/data/top-leaflist=fred）构成。
o The leaf-list value is specified as a string, using the canonical representation for the YANG data type. Any reserved characters MUST be percent-encoded, according to Sections 2.1 and 2.5 of [RFC3986].
o 叶列表值使用数据类型的规范表示形式指定为字符串。根据[RFC3986]第2.1节和第2.5节，任何保留字符必须进行百分比编码。
o YANG 1.1 allows duplicate leaf-list values for non-configuration data. In this case, there is no mechanism to specify the exact matching leaf-list instance.
o YANG 1.1允许对非配置数据使用重复的叶列表值。在这种情况下，没有机制来指定精确匹配的叶列表实例。
o The comma (",") character is percent-encoded [RFC3986], even though multiple key values are not possible for a leaf-list. This is more consistent and avoids special processing rules.
o 逗号（“，”）字符是百分比编码的[RFC3986]，即使叶列表不可能有多个键值。这更加一致，避免了特殊的处理规则。
If a data node in the path expression is a YANG list node, then the key values for the list (if any) MUST be encoded according to the following rules:
如果路径表达式中的数据节点是列表节点，则必须根据以下规则对列表的键值（如果有）进行编码：
o The key leaf values for a data resource representing a YANG list MUST be encoded using one path segment [RFC3986].
o 表示YANG列表的数据资源的键叶值必须使用一个路径段进行编码[RFC3986]。
o If there is only one key leaf value, the path segment is constructed by having the list name, followed by an "=" character, followed by the single key leaf value.
o 如果只有一个键叶值，则路径段由列表名、一个“=”字符和一个键叶值构成。
o If there are multiple key leaf values, the path segment is constructed by having the list name, followed by the value of each leaf identified in the "key" statement, encoded in the order specified in the YANG "key" statement. Each key leaf value except the last one is followed by a comma character.
o 如果有多个键叶值，则路径段的构造方法是：列表名后跟“key”语句中标识的每个叶的值，并按照“key”语句中指定的顺序进行编码。除最后一个外，每个键叶值后面都跟一个逗号字符。
o The key value is specified as a string, using the canonical representation for the YANG data type. Any reserved characters MUST be percent-encoded, according to Sections 2.1 and 2.5 of [RFC3986]. The comma (",") character MUST be percent-encoded if it is present in the key value.
o 键值被指定为字符串，使用数据类型的规范表示。根据[RFC3986]第2.1节和第2.5节，任何保留字符必须进行百分比编码。如果逗号（“，”）字符出现在键值中，则必须对其进行百分比编码。
o All of the components in the "key" statement MUST be encoded. Partial instance identifiers are not supported.
o “key”语句中的所有组件都必须进行编码。不支持部分实例标识符。
o Missing key values are not allowed, so two consecutive commas are interpreted as a comma, followed by a zero-length string, followed by a comma. For example, "list1=foo,,baz" would be interpreted as a list named "list1" with three key values, and the second key value is a zero-length string.
o 不允许缺少键值，因此两个连续的逗号被解释为逗号，后跟长度为零的字符串，后跟逗号。例如，“list1=foo，，baz”将被解释为一个名为“list1”的列表，其中包含三个键值，第二个键值是一个长度为零的字符串。
o Note that non-configuration lists are not required to define keys. In this case, a single list instance cannot be accessed.
o 请注意，定义键不需要非配置列表。在这种情况下，无法访问单个列表实例。
o The "list-instance" Augmented Backus-Naur Form (ABNF) [RFC5234] rule defined in Section 3.5.3.1 represents the syntax of a list instance identifier.
o 第3.5.3.1节中定义的“列表实例”扩展的Backus Naur Form（ABNF）[RFC5234]规则表示列表实例标识符的语法。
Examples:
示例：
container top {
list list1 {
key "key1 key2 key3";
...
list list2 {
key "key4 key5";
...
leaf X { type string; }
}
}
leaf-list Y {
type uint32;
}
}
container top {
list list1 {
key "key1 key2 key3";
...
list list2 {
key "key4 key5";
...
leaf X { type string; }
}
}
leaf-list Y {
type uint32;
}
}
For the above YANG definition, the container "top" is defined in the "example-top" YANG module, and a target resource URI for leaf "X" would be encoded as follows:
对于上述YANG定义，容器“top”在“example top”YANG模块中定义，叶“X”的目标资源URI编码如下：
/restconf/data/example-top:top/list1=key1,key2,key3/\
list2=key4,key5/X
/restconf/data/example-top:top/list1=key1,key2,key3/\
list2=key4,key5/X
For the above YANG definition, a target resource URI for leaf-list "Y" would be encoded as follows:
对于上述定义，叶列表“Y”的目标资源URI编码如下：
/restconf/data/example-top:top/Y=instance-value
/restconf/data/example-top:top/Y=instance-value
The following example shows how reserved characters are percent-encoded within a key value. The value of "key1" contains a comma, single-quote, double-quote, colon, double-quote, space, and forward slash (,'":" /). Note that double-quote is not a reserved character and does not need to be percent-encoded. The value of "key2" is the empty string, and the value of "key3" is the string "foo".
以下示例显示保留字符在键值中的百分比编码方式。“key1”的值包含逗号、单引号、双引号、冒号、双引号、空格和正斜杠（，'：“/）。请注意，双引号不是保留字符，不需要进行百分比编码。“key2”的值是空字符串，“key3”的值是字符串“foo”。
Example URL:
示例URL：
/restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo
/restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo
The "api-path" ABNF [RFC5234] syntax is used to construct RESTCONF path identifiers. Note that this syntax is used for all resources, and the API path starts with the RESTCONF root resource. Data resources are required to be identified under the "{+restconf}/data" subtree.
“api path”ABNF[RFC5234]语法用于构造RESTCONF路径标识符。请注意，此语法用于所有资源，API路径以RESTCONF根资源开始。需要在“{+restconf}/Data”子树下标识数据资源。
An identifier is not allowed to start with the case-insensitive string "XML", according to YANG identifier rules. The syntax for "api-identifier" and "key-value" MUST conform to the JSON identifier encoding rules in Section 4 of [RFC7951]: The RESTCONF root resource path is required. Additional sub-resource identifiers are optional. The characters in a key value string are constrained, and some characters need to be percent-encoded, as described in Section 3.5.3.
根据标识符规则，标识符不允许以不区分大小写的字符串“XML”开头。“api标识符”和“键值”的语法必须符合[RFC7951]第4节中的JSON标识符编码规则：需要RESTCONF根资源路径。附加子资源标识符是可选的。键值字符串中的字符受到约束，一些字符需要进行百分比编码，如第3.5.3节所述。
api-path = root *("/" (api-identifier / list-instance))
api-path = root *("/" (api-identifier / list-instance))
root = string ;; replacement string for {+restconf}
root = string ;; replacement string for {+restconf}
api-identifier = [module-name ":"] identifier
api-identifier = [module-name ":"] identifier
module-name = identifier
module-name = identifier
list-instance = api-identifier "=" key-value *("," key-value)
list-instance = api-identifier "=" key-value *("," key-value)
key-value = string ;; constrained chars are percent-encoded
key-value = string ;; constrained chars are percent-encoded
string = <an unquoted string>
string = <an unquoted string>
identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".")
identifier = (ALPHA / "_")
*(ALPHA / DIGIT / "_" / "-" / ".")
RESTCONF requires that a server report its default-handling mode (see Section 9.1.2 for details). If the optional "with-defaults" query parameter is supported by the server, a client may use it to control the retrieval of default values (see Section 4.8.9 for details).
RESTCONF要求服务器报告其默认处理模式（有关详细信息，请参阅第9.1.2节）。如果服务器支持可选的“with defaults”查询参数，则客户端可以使用它来控制默认值的检索（有关详细信息，请参阅第4.8.9节）。
If a leaf or leaf-list is missing from the configuration and there is a YANG-defined default for that data resource, then the server MUST use the YANG-defined default as the configured value.
如果配置中缺少一个叶或叶列表，并且该数据资源有一个YANG定义的默认值，那么服务器必须使用YANG定义的默认值作为配置值。
If the target of a GET method is a data node that represents a leaf or leaf-list that has a default value and the leaf or leaf-list has not been instantiated yet, the server MUST return the default value or values that are in use by the server. In this case, the server MUST ignore its "basic-mode", described in Section 4.8.9, and return the default value.
如果GET方法的目标是表示具有默认值的叶或叶列表的数据节点，并且该叶或叶列表尚未实例化，则服务器必须返回服务器正在使用的一个或多个默认值。在这种情况下，服务器必须忽略第4.8.9节所述的“基本模式”，并返回默认值。
If the target of a GET method is a data node that represents a container or list that has any child resources with default values, for the child resources that have not been given values yet, the
如果GET方法的目标是一个数据节点，它表示一个容器或列表，该容器或列表中有任何具有默认值的子资源，则对于尚未给定值的子资源
server MAY return the default values that are in use by the server in accordance with its reported default-handling mode and query parameters passed by the client.
服务器可以根据其报告的默认处理模式和客户端传递的查询参数返回服务器正在使用的默认值。
An operation resource represents an RPC operation defined with the YANG "rpc" statement or a data-model-specific action defined with a YANG "action" statement. It is invoked using a POST method on the operation resource.
操作资源表示使用YANG“RPC”语句定义的RPC操作或使用YANG“action”语句定义的数据模型特定操作。它是使用操作资源上的POST方法调用的。
An RPC operation is invoked as:
RPC操作被调用为：
POST {+restconf}/operations/<operation>
POST {+restconf}/operations/<operation>
The <operation> field identifies the module name and rpc identifier string for the desired operation.
<operation>字段标识所需操作的模块名称和rpc标识符字符串。
For example, if "module-A" defined a "reset" RPC operation, then invoking the operation would be requested as follows:
例如，如果“module-A”定义了“reset”RPC操作，则调用该操作的请求如下：
POST /restconf/operations/module-A:reset HTTP/1.1
Server: example.com
POST /restconf/operations/module-A:reset HTTP/1.1
Server: example.com
An action is invoked as:
操作的调用方式如下：
POST {+restconf}/data/<data-resource-identifier>/<action>
POST {+restconf}/data/<data-resource-identifier>/<action>
where <data-resource-identifier> contains the path to the data node where the action is defined, and <action> is the name of the action.
其中<data resource identifier>包含定义操作的数据节点的路径，<action>是操作的名称。
For example, if "module-A" defined a "reset-all" action in the container "interfaces", then invoking this action would be requested as follows:
例如，如果“module-A”在容器“interfaces”中定义了一个“reset all”操作，那么调用该操作的请求如下：
POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1
Server: example.com
POST /restconf/data/module-A:interfaces/reset-all HTTP/1.1
Server: example.com
If the RPC operation is invoked without errors and if the "rpc" or "action" statement has no "output" section, the response message MUST NOT include a message-body and MUST send a "204 No Content" status-line instead.
如果在没有错误的情况下调用RPC操作，并且如果“RPC”或“action”语句没有“output”部分，则响应消息不得包含消息正文，而必须发送“204无内容”状态行。
All operation resources representing RPC operations supported by the server MUST be identified in the "{+restconf}/operations" subtree, defined in Section 3.3.2. Operation resources representing YANG actions are not identified in this subtree, since they are invoked using a URI within the "{+restconf}/data" subtree.
必须在第3.3.2节中定义的“{+restconf}/operations”子树中标识表示服务器支持的RPC操作的所有操作资源。此子树中未标识表示操作的操作资源，因为它们是使用“{+restconf}/data”子树中的URI调用的。
If the "rpc" or "action" statement has an "input" section, then instances of these input parameters are encoded in the module namespace where the "rpc" or "action" statement is defined, in an XML element or JSON object named "input", which is in the module namespace where the "rpc" or "action" statement is defined.
如果“rpc”或“action”语句具有“input”部分，则这些输入参数的实例将编码在定义“rpc”或“action”语句的模块命名空间中，编码在名为“input”的XML元素或JSON对象中，该对象位于定义“rpc”或“action”语句的模块命名空间中。
If the "rpc" or "action" statement has an "input" section and the "input" object tree contains any child data nodes that are considered mandatory nodes, then a message-body MUST be sent by the client in the request.
如果“rpc”或“action”语句有一个“input”部分，并且“input”对象树包含任何被视为强制节点的子数据节点，那么客户端必须在请求中发送消息体。
If the "rpc" or "action" statement has an "input" section and the "input" object tree does not contain any child nodes that are considered mandatory nodes, then a message-body MAY be sent by the client in the request.
如果“rpc”或“action”语句具有“input”部分，并且“input”对象树不包含任何被视为强制节点的子节点，则客户端可以在请求中发送消息体。
If the "rpc" or "action" statement has no "input" section, the request message MUST NOT include a message-body.
如果“rpc”或“action”语句没有“input”部分，则请求消息不得包含消息体。
Examples:
示例：
The following YANG module is used for the RPC operation examples in this section.
以下模块用于本节中的RPC操作示例。
module example-ops {
namespace "https://example.com/ns/example-ops";
prefix "ops";
module example-ops {
namespace "https://example.com/ns/example-ops";
prefix "ops";
organization "Example, Inc.";
contact "support at example.com";
description "Example Operations Data Model Module.";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 3-3373.";
}
organization "Example, Inc.";
contact "support at example.com";
description "Example Operations Data Model Module.";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 3-3373.";
}
rpc reboot {
description "Reboot operation.";
input {
leaf delay {
type uint32;
units "seconds";
default 0;
description
"Number of seconds to wait before initiating the
reboot operation.";
}
leaf message {
type string;
description
"Log message to display when reboot is started.";
}
leaf language {
type string;
description "Language identifier string.";
reference "RFC 5646.";
}
}
}
rpc reboot {
description "Reboot operation.";
input {
leaf delay {
type uint32;
units "seconds";
default 0;
description
"Number of seconds to wait before initiating the
reboot operation.";
}
leaf message {
type string;
description
"Log message to display when reboot is started.";
}
leaf language {
type string;
description "Language identifier string.";
reference "RFC 5646.";
}
}
}
rpc get-reboot-info {
description
"Retrieve parameters used in the last reboot operation.";
output {
leaf reboot-time {
type uint32;
description
"The 'delay' parameter used in the last reboot
operation.";
}
leaf message {
type string;
description
"The 'message' parameter used in the last reboot
operation.";
}
leaf language {
type string;
description
"The 'language' parameter used in the last reboot
operation.";
}
}
}
}
rpc get-reboot-info {
description
"Retrieve parameters used in the last reboot operation.";
output {
leaf reboot-time {
type uint32;
description
"The 'delay' parameter used in the last reboot
operation.";
}
leaf message {
type string;
description
"The 'message' parameter used in the last reboot
operation.";
}
leaf language {
type string;
description
"The 'language' parameter used in the last reboot
operation.";
}
}
}
}
The following YANG module is used for the YANG action examples in this section.
以下阳模块用于本节中的阳动作示例。
module example-actions {
yang-version 1.1;
namespace "https://example.com/ns/example-actions";
prefix "act";
import ietf-yang-types { prefix yang; }
module example-actions {
yang-version 1.1;
namespace "https://example.com/ns/example-actions";
prefix "act";
import ietf-yang-types { prefix yang; }
organization "Example, Inc.";
contact "support at example.com";
description "Example Actions Data Model Module.";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 2-9973.";
}
organization "Example, Inc.";
contact "support at example.com";
description "Example Actions Data Model Module.";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 2-9973.";
}
container interfaces {
description "System interfaces.";
list interface {
key name;
description "One interface entry.";
leaf name {
type string;
description "Interface name.";
}
container interfaces {
description "System interfaces.";
list interface {
key name;
description "One interface entry.";
leaf name {
type string;
description "Interface name.";
}
action reset {
description "Reset an interface.";
input {
leaf delay {
type uint32;
units "seconds";
default 0;
description
"Number of seconds to wait before starting the
interface reset.";
}
}
}
action reset {
description "Reset an interface.";
input {
leaf delay {
type uint32;
units "seconds";
default 0;
description
"Number of seconds to wait before starting the
interface reset.";
}
}
}
action get-last-reset-time {
description
"Retrieve the last interface reset time.";
output {
leaf last-reset {
type yang:date-and-time;
mandatory true;
description
"Date and time of the last interface reset, or
the last reboot time of the device.";
}
}
}
}
}
action get-last-reset-time {
description
"Retrieve the last interface reset time.";
output {
leaf last-reset {
type yang:date-and-time;
mandatory true;
description
"Date and time of the last interface reset, or
the last reboot time of the device.";
}
}
}
}
}
}
}
RPC Input Example:
RPC输入示例：
The client might send the following POST request message to invoke the "reboot" RPC operation:
客户端可能会发送以下POST请求消息以调用“重新启动”RPC操作：
POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-ops">
<delay>600</delay>
<message>Going down for system maintenance</message>
<language>en-US</language>
</input>
<input xmlns="https://example.com/ns/example-ops">
<delay>600</delay>
<message>Going down for system maintenance</message>
<language>en-US</language>
</input>
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
The same example request message is shown here using JSON encoding:
此处使用JSON编码显示了相同的请求消息示例：
POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-ops:input" : {
"delay" : 600,
"message" : "Going down for system maintenance",
"language" : "en-US"
}
}
{
"example-ops:input" : {
"delay" : 600,
"message" : "Going down for system maintenance",
"language" : "en-US"
}
}
Action Input Example:
动作输入示例：
The client might send the following POST request message to invoke the "reset" action:
客户端可能会发送以下POST请求消息以调用“重置”操作：
POST /restconf/data/example-actions:interfaces/\
interface=eth0/reset HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
POST /restconf/data/example-actions:interfaces/\
interface=eth0/reset HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-actions">
<delay>600</delay>
</input>
<input xmlns="https://example.com/ns/example-actions">
<delay>600</delay>
</input>
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
The same example request message is shown here using JSON encoding:
此处使用JSON编码显示了相同的请求消息示例：
POST /restconf/data/example-actions:interfaces/\
interface=eth0/reset HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
POST /restconf/data/example-actions:interfaces/\
interface=eth0/reset HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{ "example-actions:input" : {
"delay" : 600
}
}
{ "example-actions:input" : {
"delay" : 600
}
}
If the "rpc" or "action" statement has an "output" section, then instances of these output parameters are encoded in the module namespace where the "rpc" or "action" statement is defined, in an XML element or JSON object named "output", which is in the module namespace where the "rpc" or "action" statement is defined.
如果“rpc”或“action”语句具有“output”部分，则这些输出参数的实例将编码在定义“rpc”或“action”语句的模块命名空间中，编码在名为“output”的XML元素或JSON对象中，该对象位于定义“rpc”或“action”语句的模块命名空间中。
If the RPC operation is invoked without errors, and if the "rpc" or "action" statement has an "output" section and the "output" object tree contains any child data nodes that are considered mandatory nodes, then a response message-body MUST be sent by the server in the response.
如果调用RPC操作时没有错误，并且如果“RPC”或“action”语句具有“output”部分，“output”对象树包含任何被视为强制节点的子数据节点，则服务器必须在响应中发送响应消息体。
If the RPC operation is invoked without errors, and if the "rpc" or "action" statement has an "output" section and the "output" object tree does not contain any child nodes that are considered mandatory nodes, then a response message-body MAY be sent by the server in the response.
如果调用RPC操作时没有错误，并且如果“RPC”或“action”语句具有“output”部分，“output”对象树不包含任何被视为强制节点的子节点，则服务器可能会在响应中发送响应消息体。
The request URI is not returned in the response. Knowledge of the request URI may be needed to associate the output with the specific "rpc" or "action" statement used in the request.
响应中未返回请求URI。可能需要了解请求URI，才能将输出与请求中使用的特定“rpc”或“action”语句相关联。
Examples:
示例：
RPC Output Example:
RPC输出示例：
The "example-ops" YANG module defined in Section 3.6.1 is used for this example.
本示例使用第3.6.1节中定义的“示例ops”模块。
The client might send the following POST request message to invoke the "get-reboot-info" operation:
客户端可能会发送以下POST请求消息以调用“获取重新启动信息”操作：
POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1
Host: example.com
Accept: application/yang-data+json
POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"example-ops:output" : {
"reboot-time" : 30,
"message" : "Going down for system maintenance",
"language" : "en-US"
}
}
{
"example-ops:output" : {
"reboot-time" : 30,
"message" : "Going down for system maintenance",
"language" : "en-US"
}
}
The same response is shown here using XML encoding:
这里使用XML编码显示了相同的响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
<output xmlns="https://example.com/ns/example-ops">
<reboot-time>30</reboot-time>
<message>Going down for system maintenance</message>
<language>en-US</language>
</output>
<output xmlns="https://example.com/ns/example-ops">
<reboot-time>30</reboot-time>
<message>Going down for system maintenance</message>
<language>en-US</language>
</output>
Action Output Example:
动作输出示例：
The "example-actions" YANG module defined in Section 3.6.1 is used for this example.
本示例使用第3.6.1节中定义的“示例动作”模块。
The client might send the following POST request message to invoke the "get-last-reset-time" action:
客户端可能会发送以下POST请求消息以调用“获取上次重置时间”操作：
POST /restconf/data/example-actions:interfaces/\
interface=eth0/get-last-reset-time HTTP/1.1
Host: example.com
Accept: application/yang-data+json
POST /restconf/data/example-actions:interfaces/\
interface=eth0/get-last-reset-time HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"example-actions:output" : {
"last-reset" : "2015-10-10T02:14:11Z"
}
}
{
"example-actions:output" : {
"last-reset" : "2015-10-10T02:14:11Z"
}
}
If any errors occur while attempting to invoke the operation or action, then an "errors" media type is returned with the appropriate error status.
如果在尝试调用操作或操作时发生任何错误，则会返回带有相应错误状态的“错误”媒体类型。
If (1) the RPC operation input is not valid or (2) the RPC operation is invoked but errors occur, then a message-body containing an "errors" resource MUST be sent by the server, as defined in Section 3.9.
如果（1）RPC操作输入无效或（2）调用RPC操作但发生错误，则服务器必须发送包含“错误”资源的消息正文，如第3.9节所定义。
Using the "reboot" RPC operation from the example in Section 3.6.1, the client might send the following POST request message:
使用第3.6.1节示例中的“重新启动”RPC操作，客户端可能会发送以下POST请求消息：
POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
POST /restconf/operations/example-ops:reboot HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<input xmlns="https://example.com/ns/example-ops">
<delay>-33</delay>
<message>Going down for system maintenance</message>
<language>en-US</language>
</input>
<input xmlns="https://example.com/ns/example-ops">
<delay>-33</delay>
<message>Going down for system maintenance</message>
<language>en-US</language>
</input>
The server might respond with an "invalid-value" error:
服务器可能会响应“无效值”错误：
HTTP/1.1 400 Bad Request
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
HTTP/1.1 400 Bad Request
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error>
<error-type>protocol</error-type>
<error-tag>invalid-value</error-tag>
<error-path xmlns:ops="https://example.com/ns/example-ops">
/ops:input/ops:delay
</error-path>
<error-message>Invalid input parameter</error-message>
</error>
</errors>
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error>
<error-type>protocol</error-type>
<error-tag>invalid-value</error-tag>
<error-path xmlns:ops="https://example.com/ns/example-ops">
/ops:input/ops:delay
</error-path>
<error-message>Invalid input parameter</error-message>
</error>
</errors>
The same response is shown here using JSON encoding:
这里使用JSON编码显示了相同的响应：
HTTP/1.1 400 Bad Request
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 400 Bad Request
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{ "ietf-restconf:errors" : {
"error" : [
{
"error-type" : "protocol",
"error-tag" : "invalid-value",
"error-path" : "/example-ops:input/delay",
"error-message" : "Invalid input parameter"
}
]
}
}
{ "ietf-restconf:errors" : {
"error" : [
{
"error-type" : "protocol",
"error-tag" : "invalid-value",
"error-path" : "/example-ops:input/delay",
"error-message" : "Invalid input parameter"
}
]
}
}
The server can optionally support the retrieval of the YANG modules it uses. If retrieval is supported, then the "schema" leaf MUST be present in the associated "module" list entry, defined in [RFC7895].
服务器可以选择支持检索它使用的模块。如果支持检索，则[RFC7895]中定义的相关“模块”列表条目中必须存在“架构”叶。
To retrieve a YANG module, a client first needs to get the URL for retrieving the schema, which is stored in the "schema" leaf. Note that there is no required structure for this URL. The URL value shown below is just an example.
要检索模块，客户机首先需要获取用于检索模式的URL，该URL存储在“模式”叶中。请注意，此URL没有必需的结构。下面显示的URL值只是一个示例。
The client might send the following GET request message:
客户端可能会发送以下GET请求消息：
GET /restconf/data/ietf-yang-library:modules-state/\
module=example-jukebox,2016-08-15/schema HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/ietf-yang-library:modules-state/\
module=example-jukebox,2016-08-15/schema HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"ietf-yang-library:schema" :
"https://example.com/mymodules/example-jukebox/2016-08-15"
}
{
"ietf-yang-library:schema" :
"https://example.com/mymodules/example-jukebox/2016-08-15"
}
Next, the client needs to retrieve the actual YANG schema.
接下来，客户机需要检索实际的模式。
The client might send the following GET request message:
客户端可能会发送以下GET请求消息：
GET https://example.com/mymodules/example-jukebox/\
2016-08-15 HTTP/1.1
Host: example.com
Accept: application/yang
GET https://example.com/mymodules/example-jukebox/\
2016-08-15 HTTP/1.1
Host: example.com
Accept: application/yang
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang
// entire YANG module contents deleted for this example...
//已删除此示例的整个模块内容。。。
An event stream resource represents a source for system-generated event notifications. Each stream is created and modified by the server only. A client can retrieve a stream resource or initiate a long-poll server-sent event stream [W3C.REC-eventsource-20150203], using the procedure specified in Section 6.3.
事件流资源表示系统生成的事件通知的源。每个流仅由服务器创建和修改。客户端可以使用第6.3节中指定的过程检索流资源或启动长轮询服务器发送的事件流[W3C.REC-eventsource-20150203]。
An event stream functions according to the "NETCONF Event Notifications" specification [RFC5277]. The available streams can be retrieved from the "stream" list, which specifies the syntax and semantics of the stream resources.
事件流根据“NETCONF事件通知”规范[RFC5277]运行。可以从“stream”列表中检索可用流，该列表指定流资源的语法和语义。
The "errors" YANG data template models a collection of error information that is sent as the message-body in a server response message if an error occurs while processing a request message. It is not considered as a resource type because no instances can be retrieved with a GET request.
“errors”数据模板对错误信息的集合进行建模，如果在处理请求消息时发生错误，则该集合将作为服务器响应消息中的消息体发送。它不被视为资源类型，因为GET请求无法检索任何实例。
The "ietf-restconf" YANG module contains the "yang-errors" YANG data template, which specifies the syntax and semantics of an "errors" container within a RESTCONF response. RESTCONF error-handling behavior is defined in Section 7.
“ietf restconf”YANG模块包含“YANG errors”YANG数据模板，该模板指定restconf响应中“errors”容器的语法和语义。RESTCONF错误处理行为在第7节中定义。
The RESTCONF protocol uses HTTP methods to identify the CRUD operations requested for a particular resource.
RESTCONF协议使用HTTP方法来标识为特定资源请求的CRUD操作。
The following table shows how the RESTCONF operations relate to NETCONF protocol operations.
下表显示了RESTCONF操作与NETCONF协议操作的关系。
+----------+-------------------------------------------------------+
| RESTCONF | NETCONF |
+----------+-------------------------------------------------------+
| OPTIONS | none |
| | |
| HEAD | <get-config>, <get> |
| | |
| GET | <get-config>, <get> |
| | |
| POST | <edit-config> (nc:operation="create") |
| | |
| POST | invoke an RPC operation |
| | |
| PUT | <copy-config> (PUT on datastore) |
| | |
| PUT | <edit-config> (nc:operation="create/replace") |
| | |
| PATCH | <edit-config> (nc:operation depends on PATCH content) |
| | |
| DELETE | <edit-config> (nc:operation="delete") |
+----------+-------------------------------------------------------+
+----------+-------------------------------------------------------+
| RESTCONF | NETCONF |
+----------+-------------------------------------------------------+
| OPTIONS | none |
| | |
| HEAD | <get-config>, <get> |
| | |
| GET | <get-config>, <get> |
| | |
| POST | <edit-config> (nc:operation="create") |
| | |
| POST | invoke an RPC operation |
| | |
| PUT | <copy-config> (PUT on datastore) |
| | |
| PUT | <edit-config> (nc:operation="create/replace") |
| | |
| PATCH | <edit-config> (nc:operation depends on PATCH content) |
| | |
| DELETE | <edit-config> (nc:operation="delete") |
+----------+-------------------------------------------------------+
CRUD Methods in RESTCONF
RESTCONF中的CRUD方法
The "remove" edit operation attribute for the NETCONF <edit-config> RPC operation is not supported by the HTTP DELETE method. The resource must exist or the DELETE method will fail. The PATCH method is equivalent to a "merge" edit operation when using a plain patch (see Section 4.6.1); other media types may provide more granular control.
HTTP DELETE方法不支持NETCONF<edit config>RPC操作的“remove”编辑操作属性。资源必须存在，否则删除方法将失败。当使用普通补丁时，补丁方法相当于“合并”编辑操作（见第4.6.1节）；其他介质类型可提供更精细的控制。
Access control mechanisms are used to limit what CRUD operations can be used. In particular, RESTCONF is compatible with the NETCONF Access Control Model (NACM) [RFC6536], as there is a specific mapping between RESTCONF and NETCONF operations. The resource path needs to be converted internally by the server to the corresponding YANG instance identifier. Using this information, the server can apply the NACM access control rules to RESTCONF messages.
访问控制机制用于限制可以使用哪些CRUD操作。特别是，RESTCONF与NETCONF访问控制模型（NACM）[RFC6536]兼容，因为RESTCONF和NETCONF操作之间存在特定的映射。服务器需要在内部将资源路径转换为相应的实例标识符。使用此信息，服务器可以将NACM访问控制规则应用于RESTCONF消息。
The server MUST NOT allow any RESTCONF operation for any resources that the client is not authorized to access.
服务器不得允许对客户端无权访问的任何资源执行任何RESTCONF操作。
The implementation of all methods (except PATCH [RFC5789]) is defined in [RFC7231]. This section defines the RESTCONF protocol usage for each HTTP method.
[RFC7231]中定义了所有方法（修补程序[RFC5789]除外）的实现。本节定义每个HTTP方法的RESTCONF协议用法。
The OPTIONS method is sent by the client to discover which methods are supported by the server for a specific resource (e.g., GET, POST, DELETE). The server MUST implement this method.
OPTIONS方法由客户端发送，以发现服务器对特定资源（例如GET、POST、DELETE）支持哪些方法。服务器必须实现此方法。
The "Accept-Patch" header field MUST be supported and returned in the response to the OPTIONS request, as defined in [RFC5789].
根据[RFC5789]中的定义，在对选项请求的响应中必须支持并返回“Accept Patch”标头字段。
The RESTCONF server MUST support the HEAD method. The HEAD method is sent by the client to retrieve just the header fields (which contain the metadata for a resource) that would be returned for the comparable GET method, without the response message-body. It is supported for all resources that support the GET method.
RESTCONF服务器必须支持HEAD方法。HEAD方法由客户端发送，以仅检索将为可比较的GET方法返回的头字段（其中包含资源的元数据），而不检索响应消息体。所有支持GET方法的资源都支持它。
The request MUST contain a request URI that contains at least the root resource. The same query parameters supported by the GET method are supported by the HEAD method.
请求必须包含至少包含根资源的请求URI。GET方法支持的查询参数与HEAD方法支持的查询参数相同。
The access control behavior is enforced as if the method was GET instead of HEAD. The server MUST respond the same as if the method was GET instead of HEAD, except that no response message-body is included.
访问控制行为被强制执行，就像方法是GET而不是HEAD一样。服务器的响应必须与方法是GET而不是HEAD的响应相同，只是没有包含响应消息体。
The RESTCONF server MUST support the GET method. The GET method is sent by the client to retrieve data and metadata for a resource. It is supported for all resource types, except operation resources. The request MUST contain a request URI that contains at least the root resource.
RESTCONF服务器必须支持GET方法。GET方法由客户端发送，用于检索资源的数据和元数据。除操作资源外，所有资源类型都支持此功能。请求必须包含至少包含根资源的请求URI。
The server MUST NOT return any data resources for which the user does not have read privileges. If the user is not authorized to read the target resource, an error response containing a "401 Unauthorized" status-line SHOULD be returned. The error-tag value "access-denied" is returned in this case. A server MAY return a "404 Not Found" status-line, as described in Section 6.5.4 in [RFC7231]. The error-tag value "invalid-value" is returned in this case.
服务器不得返回用户没有读取权限的任何数据资源。如果用户无权读取目标资源，则应返回包含“401 Unauthorized”状态行的错误响应。在这种情况下，返回错误标记值“拒绝访问”。服务器可能返回“404未找到”状态行，如[RFC7231]第6.5.4节所述。在这种情况下，返回错误标记值“invalid value”。
If the user is authorized to read some but not all of the target resource, the unauthorized content is omitted from the response message-body, and the authorized content is returned to the client.
如果用户被授权读取部分但不是全部目标资源，则响应消息正文中会忽略未经授权的内容，并将授权的内容返回给客户端。
If any content is returned to the client, then the server MUST send a valid response message-body. More than one element MUST NOT be returned for XML encoding. If multiple elements are sent in a JSON message-body, then they MUST be sent as a JSON array. In this case, any timestamp or entity-tag returned in the response MUST be associated with the first element returned.
如果将任何内容返回到客户端，则服务器必须发送有效的响应消息正文。XML编码不能返回多个元素。如果在JSON消息体中发送多个元素，那么它们必须作为JSON数组发送。在这种情况下，响应中返回的任何时间戳或实体标记都必须与返回的第一个元素相关联。
If a retrieval request for a data resource representing a YANG leaf-list or list object identifies more than one instance and XML encoding is used in the response, then an error response containing a "400 Bad Request" status-line MUST be returned by the server. The error-tag value "invalid-value" is used in this case. Note that a non-configuration list is not required to define any keys. In this case, the retrieval of a single list instance is not possible.
如果表示叶列表或列表对象的数据资源的检索请求标识了多个实例，并且响应中使用了XML编码，则服务器必须返回包含“400错误请求”状态行的错误响应。在这种情况下使用错误标记值“无效值”。请注意，定义任何键都不需要非配置列表。在这种情况下，无法检索单个列表实例。
If a retrieval request for a data resource represents an instance that does not exist, then an error response containing a "404 Not Found" status-line MUST be returned by the server. The error-tag value "invalid-value" is used in this case.
如果数据资源的检索请求表示不存在的实例，则服务器必须返回包含“404未找到”状态行的错误响应。在这种情况下使用错误标记值“无效值”。
If the target resource of a retrieval request is for an operation resource, then a "405 Method Not Allowed" status-line MUST be returned by the server. The error-tag value "operation-not-supported" is used in this case.
如果检索请求的目标资源是操作资源，则服务器必须返回“405方法不允许”状态行。在这种情况下使用错误标记值“操作不受支持”。
Note that the way that access control is applied to data resources may not be completely compatible with HTTP caching. The "Last-Modified" and "ETag" header fields maintained for a data resource are not affected by changes to the access control rules for that data resource. It is possible for the representation of a data resource that is visible to a particular client to be changed without detection via the "Last-Modified" or "ETag" values.
请注意，对数据资源应用访问控制的方式可能与HTTP缓存不完全兼容。为数据资源维护的“上次修改”和“ETag”头字段不受该数据资源访问控制规则更改的影响。通过“上次修改”或“ETag”值，可以在没有检测的情况下更改对特定客户端可见的数据资源的表示。
Example:
例子：
The client might request the response header fields for an XML representation of a specific "album" resource:
客户端可能会请求特定“相册”资源的XML表示的响应头字段：
GET /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
Cache-Control: no-cache
ETag: "a74eefc993a2b"
Last-Modified: Thu, 26 Jan 2017 14:02:14 GMT
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
Cache-Control: no-cache
ETag: "a74eefc993a2b"
Last-Modified: Thu, 26 Jan 2017 14:02:14 GMT
<album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name>
<genre>jbox:alternative</genre>
<year>2011</year>
</album>
<album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name>
<genre>jbox:alternative</genre>
<year>2011</year>
</album>
Refer to Appendix B.1 for more resource retrieval examples.
有关更多资源检索示例，请参阅附录B.1。
The RESTCONF server MUST support the POST method. The POST method is sent by the client to create a data resource or invoke an operation resource. The server uses the target resource type to determine how to process the request.
RESTCONF服务器必须支持POST方法。POST方法由客户端发送以创建数据资源或调用操作资源。服务器使用目标资源类型来确定如何处理请求。
+-----------+------------------------------------------------+
| Type | Description |
+-----------+------------------------------------------------+
| Datastore | Create a top-level configuration data resource |
| Data | Create a configuration data child resource |
| Operation | Invoke an RPC operation |
+-----------+------------------------------------------------+
+-----------+------------------------------------------------+
| Type | Description |
+-----------+------------------------------------------------+
| Datastore | Create a top-level configuration data resource |
| Data | Create a configuration data child resource |
| Operation | Invoke an RPC operation |
+-----------+------------------------------------------------+
Resource Types That Support POST
支持POST的资源类型
If the target resource type is a datastore or data resource, then the POST is treated as a request to create a top-level resource or child resource, respectively. The message-body is expected to contain the content of a child resource to create within the parent (target resource). The message-body MUST contain exactly one instance of the expected data resource. The data model for the child tree is the subtree, as defined by YANG for the child resource.
如果目标资源类型是数据存储或数据资源，则POST将分别被视为创建顶级资源或子资源的请求。消息正文应包含要在父资源（目标资源）中创建的子资源的内容。消息正文必须仅包含预期数据资源的一个实例。子树的数据模型是由YANG为子资源定义的子树。
The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query parameters MUST be supported by the POST method for datastore and data resources. These parameters are only allowed if the list or leaf-list is "ordered-by user".
数据存储和数据资源的POST方法必须支持“插入”（第4.8.5节）和“点”（第4.8.6节）查询参数。仅当列表或叶列表为“按用户排序”时，才允许使用这些参数。
If the POST method succeeds, a "201 Created" status-line is returned and there is no response message-body. A "Location" header field identifying the child resource that was created MUST be present in the response in this case.
如果POST方法成功，则返回“201已创建”状态行，并且没有响应消息正文。在这种情况下，响应中必须存在标识已创建子资源的“位置”标题字段。
If the data resource already exists, then the POST request MUST fail and a "409 Conflict" status-line MUST be returned. The error-tag value "resource-denied" is used in this case.
如果数据资源已经存在，则POST请求必须失败，并且必须返回“409冲突”状态行。在这种情况下使用错误标记值“resource denied”。
If the user is not authorized to create the target resource, an error response containing a "403 Forbidden" status-line SHOULD be returned. The error-tag value "access-denied" is used in this case. A server MAY return a "404 Not Found" status-line, as described in Section 6.5.4 in [RFC7231]. The error-tag value "invalid-value" is used in this case. All other error responses are handled according to the procedures defined in Section 7.
如果用户无权创建目标资源，则应返回包含“403禁止”状态行的错误响应。在这种情况下使用错误标记值“拒绝访问”。服务器可能返回“404未找到”状态行，如[RFC7231]第6.5.4节所述。在这种情况下使用错误标记值“无效值”。根据第7节中定义的程序处理所有其他错误响应。
Example:
例子：
To create a new "jukebox" resource, the client might send the following:
要创建新的“自动存储塔”资源，客户端可能会发送以下内容：
POST /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
POST /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{ "example-jukebox:jukebox" : {} }
{ "example-jukebox:jukebox" : {} }
If the resource is created, the server might respond as follows:
如果创建了资源，服务器可能会做出如下响应：
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b3a3e673be2"
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b3a3e673be2"
Refer to Appendix B.2.1 for more resource creation examples.
有关更多资源创建示例，请参阅附录B.2.1。
If the target resource type is an operation resource, then the POST method is treated as a request to invoke that operation. The message-body (if any) is processed as the operation input parameters. Refer to Section 3.6 for details on operation resources.
如果目标资源类型是操作资源，则POST方法将被视为调用该操作的请求。消息正文（如果有）作为操作输入参数处理。有关操作资源的详细信息，请参阅第3.6节。
If the POST request succeeds, a "200 OK" status-line is returned if there is a response message-body, and a "204 No Content" status-line is returned if there is no response message-body.
如果POST请求成功，如果有响应消息正文，则返回“200 OK”状态行，如果没有响应消息正文，则返回“204 No Content”状态行。
If the user is not authorized to invoke the target operation, an error response containing a "403 Forbidden" status-line SHOULD be returned. The error-tag value "access-denied" is used in this case. A server MAY return a "404 Not Found" status-line, as described in Section 6.5.4 in [RFC7231]. All other error responses are handled according to the procedures defined in Section 7.
如果用户无权调用目标操作，则应返回包含“403禁止”状态行的错误响应。在这种情况下使用错误标记值“拒绝访问”。服务器可能返回“404未找到”状态行，如[RFC7231]第6.5.4节所述。根据第7节中定义的程序处理所有其他错误响应。
Example:
例子：
In this example, the client is invoking the "play" operation defined in the "example-jukebox" YANG module.
在本例中，客户端正在调用“示例自动存储塔”模块中定义的“播放”操作。
A client might send a "play" request as follows:
客户端可能会发送“播放”请求，如下所示：
POST /restconf/operations/example-jukebox:play HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
POST /restconf/operations/example-jukebox:play HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:input" : {
"playlist" : "Foo-One",
"song-number" : 2
}
}
{
"example-jukebox:input" : {
"playlist" : "Foo-One",
"song-number" : 2
}
}
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
The RESTCONF server MUST support the PUT method. The PUT method is sent by the client to create or replace the target data resource. A request message-body MUST be present, representing the new data resource, or the server MUST return a "400 Bad Request" status-line. The error-tag value "invalid-value" is used in this case.
RESTCONF服务器必须支持PUT方法。PUT方法由客户端发送以创建或替换目标数据资源。必须存在表示新数据资源的请求消息正文，或者服务器必须返回“400错误请求”状态行。在这种情况下使用错误标记值“无效值”。
Both the POST and PUT methods can be used to create data resources. The difference is that for POST, the client does not provide the resource identifier for the resource that will be created. The target resource for the POST method for resource creation is the parent of the new resource. The target resource for the PUT method for resource creation is the new resource.
POST和PUT方法都可以用于创建数据资源。区别在于，对于POST，客户端不提供将要创建的资源的资源标识符。用于创建资源的POST方法的目标资源是新资源的父资源。用于创建资源的PUT方法的目标资源是新资源。
The PUT method MUST be supported for data and datastore resources. A PUT on the datastore resource is used to replace the entire contents of the datastore. A PUT on a data resource only replaces that data resource within the datastore.
数据和数据存储资源必须支持PUT方法。数据存储资源上的PUT用于替换数据存储的全部内容。数据资源上的PUT仅替换数据存储中的该数据资源。
The "insert" (Section 4.8.5) and "point" (Section 4.8.6) query parameters MUST be supported by the PUT method for data resources. These parameters are only allowed if the list or leaf-list is "ordered-by user".
数据资源的PUT方法必须支持“插入”（第4.8.5节）和“点”（第4.8.6节）查询参数。仅当列表或叶列表为“按用户排序”时，才允许使用这些参数。
Consistent with [RFC7231], if the PUT request creates a new resource, a "201 Created" status-line is returned. If an existing resource is modified, a "204 No Content" status-line is returned.
与[RFC7231]一致，如果PUT请求创建新资源，则返回“201已创建”状态行。如果修改现有资源，将返回“204无内容”状态行。
If the user is not authorized to create or replace the target resource, an error response containing a "403 Forbidden" status-line SHOULD be returned. The error-tag value "access-denied" is used in this case.
如果用户无权创建或替换目标资源，则应返回包含“403禁止”状态行的错误响应。在这种情况下使用错误标记值“拒绝访问”。
A server MAY return a "404 Not Found" status-line, as described in Section 6.5.4 in [RFC7231]. The error-tag value "invalid-value" is used in this case. All other error responses are handled according to the procedures defined in Section 7.
服务器可能返回“404未找到”状态行，如[RFC7231]第6.5.4节所述。在这种情况下使用错误标记值“无效值”。根据第7节中定义的程序处理所有其他错误响应。
If the target resource represents a YANG leaf-list, then the PUT method MUST NOT change the value of the leaf-list instance.
如果目标资源表示叶列表，则PUT方法不得更改叶列表实例的值。
If the target resource represents a YANG list instance, then the key leaf values, in message-body representation, MUST be the same as the key leaf values in the request URI. The PUT method MUST NOT be used to change the key leaf values for a data resource instance.
如果目标资源表示一个列表实例，那么消息体表示中的键叶值必须与请求URI中的键叶值相同。PUT方法不得用于更改数据资源实例的键叶值。
Example:
例子：
An "album" child resource defined in the "example-jukebox" YANG module is replaced, or it is created if it does not already exist.
替换“示例自动存储塔”模块中定义的“相册”子资源，或者如果它不存在，则创建它。
To replace the "album" resource contents, the client might send the following:
要替换“相册”资源内容，客户端可能会发送以下内容：
PUT /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
PUT /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:album" : [
{
"name" : "Wasting Light",
"genre" : "example-jukebox:alternative",
"year" : 2011
}
]
}
{
"example-jukebox:album" : [
{
"name" : "Wasting Light",
"genre" : "example-jukebox:alternative",
"year" : 2011
}
]
}
If the resource is updated, the server might respond as follows:
如果资源已更新，服务器可能会做出如下响应：
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b27480aeda4c"
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b27480aeda4c"
The same request is shown here using XML encoding:
此处使用XML编码显示了相同的请求：
PUT /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
PUT /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name>
<genre>jbox:alternative</genre>
<year>2011</year>
</album>
<album xmlns="http://example.com/ns/example-jukebox"
xmlns:jbox="http://example.com/ns/example-jukebox">
<name>Wasting Light</name>
<genre>jbox:alternative</genre>
<year>2011</year>
</album>
Refer to Appendix B.2.4 for an example using the PUT method to replace the contents of the datastore resource.
有关使用PUT方法替换数据存储资源内容的示例，请参阅附录B.2.4。
The RESTCONF server MUST support the PATCH method for a plain patch and MAY support additional media types. The media types for the PATCH method supported by the server can be discovered by the client by sending an OPTIONS request and examining the "Accept-Patch" header field in the response (see Section 4.1).
RESTCONF服务器必须支持普通补丁的补丁方法，并且可能支持其他媒体类型。客户端可以通过发送选项请求并检查响应中的“Accept PATCH”（接受补丁）标题字段来发现服务器支持的补丁方法的媒体类型（参见第4.1节）。
RESTCONF uses the HTTP PATCH method defined in [RFC5789] to provide an extensible framework for resource patching mechanisms. Each patch mechanism needs a unique media type.
RESTCONF使用[RFC5789]中定义的HTTP修补方法为资源修补机制提供可扩展的框架。每个修补机制都需要一种唯一的介质类型。
This document defines one patch mechanism (Section 4.6.1). Another patch mechanism, the YANG Patch mechanism, is defined in [YANG-Patch]. Other patch mechanisms may be defined by future specifications.
本文件定义了一种修补机制（第4.6.1节）。另一种补片机制，阳补片机制，在[YANG patch]中定义。其他补丁机制可能由未来的规范定义。
If the target resource instance does not exist, the server MUST NOT create it.
如果目标资源实例不存在，则服务器不能创建它。
If the PATCH request succeeds, a "200 OK" status-line is returned if there is a message-body, and "204 No Content" is returned if no response message-body is sent.
如果补丁请求成功，如果有消息正文，则返回“200 OK”状态行；如果没有发送响应消息正文，则返回“204 No Content”。
If the user is not authorized to alter the target resource, an error response containing a "403 Forbidden" status-line SHOULD be returned. A server MAY return a "404 Not Found" status-line, as described in Section 6.5.4 in [RFC7231]. The error-tag value "invalid-value" is used in this case. All other error responses are handled according to the procedures defined in Section 7.
如果用户无权更改目标资源，则应返回包含“403禁止”状态行的错误响应。服务器可能返回“404未找到”状态行，如[RFC7231]第6.5.4节所述。在这种情况下使用错误标记值“无效值”。根据第7节中定义的程序处理所有其他错误响应。
The plain patch mechanism merges the contents of the message-body with the target resource. The message-body for a plain patch MUST be present and MUST be represented by the media type "application/yang-data+xml" or "application/yang-data+json".
普通补丁机制将消息体的内容与目标资源合并。普通补丁的消息体必须存在，并且必须由媒体类型“application/yang data+xml”或“application/yang data+json”表示。
Plain patch can be used to create or update, but not delete, a child resource within the target resource. Please see [YANG-Patch] for an alternate media type supporting the ability to delete child resources. The YANG Patch media type allows multiple suboperations (e.g., "merge", "delete") within a single PATCH method.
普通补丁可用于创建或更新目标资源中的子资源，但不能删除。请参阅[YANG Patch]，了解支持删除子资源的备用媒体类型。修补程序介质类型允许在单个修补程序方法中执行多个子操作（例如，“合并”、“删除”）。
If the target resource represents a YANG leaf-list, then the PATCH method MUST NOT change the value of the leaf-list instance.
如果目标资源表示一个叶列表，那么补丁方法不能更改叶列表实例的值。
If the target resource represents a YANG list instance, then the key leaf values, in message-body representation, MUST be the same as the key leaf values in the request URI. The PATCH method MUST NOT be used to change the key leaf values for a data resource instance.
如果目标资源表示一个列表实例，那么消息体表示中的键叶值必须与请求URI中的键叶值相同。PATCH方法不得用于更改数据资源实例的键叶值。
After the plain patch is processed by the server, a response will be returned to the client, as specified in Section 4.6.
服务器处理普通补丁后，将向客户端返回响应，如第4.6节所述。
Example:
例子：
To replace just the "year" field in the "album" resource (instead of replacing the entire resource with the PUT method), the client might send a plain patch as follows:
要仅替换“album”资源中的“year”字段（而不是用PUT方法替换整个资源），客户端可能会发送一个普通补丁，如下所示：
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
If-Match: "b8389233a4c"
Content-Type: application/yang-data+xml
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
If-Match: "b8389233a4c"
Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox">
<year>2011</year>
</album>
<album xmlns="http://example.com/ns/example-jukebox">
<year>2011</year>
</album>
If the field is updated, the server might respond as follows:
如果该字段已更新，服务器可能会做出如下响应：
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b2788923da4c"
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b2788923da4c"
The RESTCONF server MUST support the DELETE method. The DELETE method is used to delete the target resource. If the DELETE request succeeds, a "204 No Content" status-line is returned.
RESTCONF服务器必须支持DELETE方法。DELETE方法用于删除目标资源。如果删除请求成功，则返回“204无内容”状态行。
If the user is not authorized to delete the target resource, then an error response containing a "403 Forbidden" status-line SHOULD be returned. The error-tag value "access-denied" is returned in this case. A server MAY return a "404 Not Found" status-line, as described in Section 6.5.4 in [RFC7231]. The error-tag value "invalid-value" is returned in this case. All other error responses are handled according to the procedures defined in Section 7.
如果用户无权删除目标资源，则应返回包含“403禁止”状态行的错误响应。在这种情况下，返回错误标记值“拒绝访问”。服务器可能返回“404未找到”状态行，如[RFC7231]第6.5.4节所述。在这种情况下，返回错误标记值“invalid value”。根据第7节中定义的程序处理所有其他错误响应。
If the target resource represents a configuration leaf-list or list data node, then it MUST represent a single YANG leaf-list or list instance. The server MUST NOT use the DELETE method to delete more than one such instance.
如果目标资源表示配置叶列表或列表数据节点，则它必须表示单个叶列表或列表实例。服务器不能使用DELETE方法删除多个此类实例。
Example:
例子：
To delete the "album" resource with the key "Wasting Light", the client might send the following:
要删除键为“Wasing Light”的“album”资源，客户端可能会发送以下内容：
DELETE /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
DELETE /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
If the resource is deleted, the server might respond as follows:
如果资源被删除，服务器可能会做出如下响应：
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
HTTP/1.1 204 No Content
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Each RESTCONF operation allows zero or more query parameters to be present in the request URI. Which specific parameters are allowed will depend on the resource type, and sometimes the specific target resource used, in the request.
每个RESTCONF操作都允许在请求URI中存在零个或多个查询参数。允许哪些特定参数取决于请求中的资源类型，有时还取决于所使用的特定目标资源。
o Query parameters can be given in any order.
o 查询参数可以按任意顺序给出。
o Each parameter can appear at most once in a request URI.
o 每个参数在请求URI中最多只能出现一次。
o If more than one instance of a query parameter is present, then a "400 Bad Request" status-line MUST be returned by the server. The error-tag value "invalid-value" is returned in this case.
o 如果查询参数存在多个实例，则服务器必须返回“400错误请求”状态行。在这种情况下，返回错误标记值“invalid value”。
o A default value may apply if the parameter is missing.
o 如果缺少参数，则可以应用默认值。
o Query parameter names and values are case sensitive.
o 查询参数名称和值区分大小写。
o A server MUST return an error with a "400 Bad Request" status-line if a query parameter is unexpected. The error-tag value "invalid-value" is returned in this case.
o 如果查询参数是意外的，服务器必须返回带有“400错误请求”状态行的错误。在这种情况下，返回错误标记值“invalid value”。
+---------------+---------+-----------------------------------------+
| Name | Methods | Description |
+---------------+---------+-----------------------------------------+
| content | GET, | Select config and/or non-config data |
| | HEAD | resources |
| | | |
| depth | GET, | Request limited subtree depth in the |
| | HEAD | reply content |
| | | |
| fields | GET, | Request a subset of the target resource |
| | HEAD | contents |
| | | |
| filter | GET, | Boolean notification filter for event |
| | HEAD | stream resources |
| | | |
| insert | POST, | Insertion mode for "ordered-by user" |
| | PUT | data resources |
| | | |
| point | POST, | Insertion point for "ordered-by user" |
| | PUT | data resources |
| | | |
| start-time | GET, | Replay buffer start time for event |
| | HEAD | stream resources |
| | | |
| stop-time | GET, | Replay buffer stop time for event |
| | HEAD | stream resources |
| | | |
| with-defaults | GET, | Control the retrieval of default values |
| | HEAD | |
+---------------+---------+-----------------------------------------+
+---------------+---------+-----------------------------------------+
| Name | Methods | Description |
+---------------+---------+-----------------------------------------+
| content | GET, | Select config and/or non-config data |
| | HEAD | resources |
| | | |
| depth | GET, | Request limited subtree depth in the |
| | HEAD | reply content |
| | | |
| fields | GET, | Request a subset of the target resource |
| | HEAD | contents |
| | | |
| filter | GET, | Boolean notification filter for event |
| | HEAD | stream resources |
| | | |
| insert | POST, | Insertion mode for "ordered-by user" |
| | PUT | data resources |
| | | |
| point | POST, | Insertion point for "ordered-by user" |
| | PUT | data resources |
| | | |
| start-time | GET, | Replay buffer start time for event |
| | HEAD | stream resources |
| | | |
| stop-time | GET, | Replay buffer stop time for event |
| | HEAD | stream resources |
| | | |
| with-defaults | GET, | Control the retrieval of default values |
| | HEAD | |
+---------------+---------+-----------------------------------------+
RESTCONF Query Parameters
RESTCONF查询参数
Refer to Appendix B.3 for examples of query parameter usage.
有关查询参数用法的示例，请参阅附录B.3。
If vendors define additional query parameters, they SHOULD use a prefix (such as the enterprise or organization name) for query parameter names in order to avoid collisions with other parameters.
如果供应商定义了其他查询参数，则应为查询参数名称使用前缀（如企业或组织名称），以避免与其他参数发生冲突。
The "content" query parameter controls how descendant nodes of the requested data nodes will be processed in the reply.
“content”查询参数控制在应答中如何处理请求数据节点的子节点。
The allowed values are:
允许的值为：
+-----------+-----------------------------------------------------+
| Value | Description |
+-----------+-----------------------------------------------------+
| config | Return only configuration descendant data nodes |
| | |
| nonconfig | Return only non-configuration descendant data nodes |
| | |
| all | Return all descendant data nodes |
+-----------+-----------------------------------------------------+
+-----------+-----------------------------------------------------+
| Value | Description |
+-----------+-----------------------------------------------------+
| config | Return only configuration descendant data nodes |
| | |
| nonconfig | Return only non-configuration descendant data nodes |
| | |
| all | Return all descendant data nodes |
+-----------+-----------------------------------------------------+
This parameter is only allowed for GET methods on datastore and data resources. A "400 Bad Request" status-line is returned if used for other methods or resource types.
此参数仅允许用于数据存储和数据资源上的GET方法。如果用于其他方法或资源类型，则返回“400错误请求”状态行。
If this query parameter is not present, the default value is "all". This query parameter MUST be supported by the server.
如果此查询参数不存在，则默认值为“全部”。服务器必须支持此查询参数。
The "depth" query parameter is used to limit the depth of subtrees returned by the server. Data nodes with a "depth" value greater than the "depth" parameter are not returned in a response for a GET method.
“depth”查询参数用于限制服务器返回的子树的深度。“depth”值大于“depth”参数的数据节点不会在GET方法的响应中返回。
The requested data node has a depth level of "1". If the "fields" parameter (Section 4.8.3) is used to select descendant data nodes, then these nodes and all of their ancestor nodes have a "depth" value of "1". (This has the effect of including the nodes specified by the fields, even if the "depth" value is less than the actual depth level of the specified fields.) Any other child node has a "depth" value that is 1 greater than its parent.
请求的数据节点的深度级别为“1”。如果“字段”参数（第4.8.3节）用于选择后代数据节点，则这些节点及其所有祖先节点的“深度”值为“1”。（这具有包括字段指定的节点的效果，即使“深度”值小于指定字段的实际深度级别。）任何其他子节点的“深度”值都比其父节点大1。
The value of the "depth" parameter is either an integer between 1 and 65535 or the string "unbounded". "unbounded" is the default.
“depth”参数的值是介于1和65535之间的整数或字符串“unbounded”。“无界”是默认值。
This parameter is only allowed for GET methods on API, datastore, and data resources. A "400 Bad Request" status-line is returned if used for other methods or resource types.
此参数仅允许用于API、数据存储和数据资源上的GET方法。如果用于其他方法或资源类型，则返回“400错误请求”状态行。
By default, the server will include all sub-resources within a retrieved resource that have the same resource type as the requested resource. The exception is the datastore resource. If this resource type is retrieved, then by default the datastore and all child data resources are returned.
默认情况下，服务器将包括检索到的资源中与请求的资源具有相同资源类型的所有子资源。例外情况是数据存储资源。如果检索到此资源类型，则默认情况下将返回数据存储和所有子数据资源。
If the "depth" query parameter URI is listed in the "capability" leaf-list defined in Section 9.3, then the server supports the "depth" query parameter.
如果第9.3节定义的“能力”叶列表中列出了“深度”查询参数URI，则服务器支持“深度”查询参数。
The "fields" query parameter is used to optionally identify data nodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource.
“fields”查询参数用于选择性地标识目标资源中要在GET方法中检索的数据节点。客户端可以使用此参数检索资源中所有节点的子集。
The server will return a message-body representing the target resource, with descendant nodes pruned as specified in the "fields-expr" value. The server does not return a set of separate sub-resources.
服务器将返回一个表示目标资源的消息体，并按照“fields expr”值中的指定修剪后代节点。服务器不会返回一组单独的子资源。
A value of the "fields" query parameter matches the following rule:
“fields”查询参数的值与以下规则匹配：
fields-expr = path "(" fields-expr ")" / path ";" fields-expr / path
path = api-identifier [ "/" path ]
fields-expr = path "(" fields-expr ")" / path ";" fields-expr / path
path = api-identifier [ "/" path ]
"api-identifier" is defined in Section 3.5.3.1.
第3.5.3.1节定义了“api标识符”。
";" is used to select multiple nodes. For example, to retrieve only the "genre" and "year" of an album, use "fields=genre;year".
“；”用于选择多个节点。例如，要仅检索专辑的“流派”和“年份”，请使用“fields=genre；year”。
Parentheses are used to specify sub-selectors of a node. Note that there is no path separator character "/" between a "path" field and a left parenthesis character "(".
圆括号用于指定节点的子选择器。请注意，“路径”字段和左括号字符“（”之间没有路径分隔符“/”。
For example, assume that the target resource is the "album" list. To retrieve only the "label" and "catalogue-number" of the "admin" container within an album, use "fields=admin(label;catalogue-number)".
例如，假设目标资源是“相册”列表。要仅检索相册中“admin”容器的“label”和“catalog number”，请使用“fields=admin（label；catalog number）”。
"/" is used in a path to retrieve a child node of a node. For example, to retrieve only the "label" of an album, use "fields=admin/label".
“/”在路径中用于检索节点的子节点。例如，要仅检索相册的“标签”，请使用“fields=admin/label”。
This parameter is only allowed for GET methods on API, datastore, and data resources. A "400 Bad Request" status-line is returned if used for other methods or resource types.
此参数仅允许用于API、数据存储和数据资源上的GET方法。如果用于其他方法或资源类型，则返回“400错误请求”状态行。
If the "fields" query parameter URI is listed in the "capability" leaf-list defined in Section 9.3, then the server supports the "fields" parameter.
如果第9.3节中定义的“功能”叶列表中列出了“字段”查询参数URI，则服务器支持“字段”参数。
The "filter" query parameter is used to indicate which subset of all possible events is of interest. If not present, all events not precluded by other parameters will be sent.
“filter”查询参数用于指示感兴趣的所有可能事件的子集。如果不存在，将发送其他参数未排除的所有事件。
This parameter is only allowed for GET methods on an event stream resource. A "400 Bad Request" status-line is returned if used for other methods or resource types.
此参数仅允许用于事件流资源上的GET方法。如果用于其他方法或资源类型，则返回“400错误请求”状态行。
The format of this parameter is an XPath 1.0 expression [XPath] and is evaluated in the following context:
此参数的格式为XPath 1.0表达式[XPath]，并在以下上下文中进行计算：
o The set of namespace declarations is the set of prefix and namespace pairs for all supported YANG modules, where the prefix is the YANG module name and the namespace is as defined by the "namespace" statement in the YANG module.
o 名称空间声明集是所有受支持的YANG模块的前缀和名称空间对集，其中前缀是YANG模块名称，名称空间由YANG模块中的“namespace”语句定义。
o The function library is the core function library defined in XPath 1.0, plus any functions defined by the data model.
o 函数库是XPath 1.0中定义的核心函数库，加上数据模型定义的任何函数。
o The set of variable bindings is empty.
o 变量绑定集为空。
o The context node is the root node.
o 上下文节点是根节点。
The "filter" query parameter is used as defined in Section 3.6 of [RFC5277]. If the boolean result of the expression is "true" when applied to the conceptual "notification" document root, then the event notification is delivered to the client.
按照[RFC5277]第3.6节的定义使用“过滤器”查询参数。如果将表达式的布尔结果应用于概念上的“通知”文档根时为“true”，则事件通知将传递给客户端。
If the "filter" query parameter URI is listed in the "capability" leaf-list defined in Section 9.3, then the server supports the "filter" query parameter.
如果第9.3节中定义的“功能”叶列表中列出了“过滤器”查询参数URI，则服务器支持“过滤器”查询参数。
The "insert" query parameter is used to specify how a resource should be inserted within an "ordered-by user" list.
“insert”查询参数用于指定如何将资源插入到“ordered by user”列表中。
The allowed values are:
允许的值为：
+--------+----------------------------------------------------------+
| Value | Description |
+--------+----------------------------------------------------------+
| first | Insert the new data as the new first entry. |
| | |
| last | Insert the new data as the new last entry. |
| | |
| before | Insert the new data before the insertion point, as |
| | specified by the value of the "point" parameter. |
| | |
| after | Insert the new data after the insertion point, as |
| | specified by the value of the "point" parameter. |
+--------+----------------------------------------------------------+
+--------+----------------------------------------------------------+
| Value | Description |
+--------+----------------------------------------------------------+
| first | Insert the new data as the new first entry. |
| | |
| last | Insert the new data as the new last entry. |
| | |
| before | Insert the new data before the insertion point, as |
| | specified by the value of the "point" parameter. |
| | |
| after | Insert the new data after the insertion point, as |
| | specified by the value of the "point" parameter. |
+--------+----------------------------------------------------------+
The default value is "last".
默认值为“last”。
This parameter is only supported for the POST and PUT methods. It is also only supported if the target resource is a data resource, and that data represents a YANG list or leaf-list that is "ordered-by user".
仅POST和PUT方法支持此参数。仅当目标资源是数据资源且该数据表示“按用户排序”的YANG列表或叶列表时，才支持此功能。
If the values "before" or "after" are used, then a "point" query parameter for the "insert" query parameter MUST also be present, or a "400 Bad Request" status-line is returned.
如果使用“before”或“after”值，则“insert”查询参数的“point”查询参数也必须存在，或者返回“400 Bad Request”状态行。
The "insert" query parameter MUST be supported by the server.
服务器必须支持“插入”查询参数。
The "point" query parameter is used to specify the insertion point for a data resource that is being created or moved within an "ordered-by user" list or leaf-list.
“点”查询参数用于指定在“按用户排序”列表或叶列表中创建或移动的数据资源的插入点。
The value of the "point" parameter is a string that identifies the path to the insertion point object. The format is the same as a target resource URI string.
“point”参数的值是一个字符串，用于标识插入点对象的路径。格式与目标资源URI字符串相同。
This parameter is only supported for the POST and PUT methods. It is also only supported if the target resource is a data resource, and that data represents a YANG list or leaf-list that is "ordered-by user".
仅POST和PUT方法支持此参数。仅当目标资源是数据资源且该数据表示“按用户排序”的YANG列表或叶列表时，才支持此功能。
If the "insert" query parameter is not present or has a value other than "before" or "after", then a "400 Bad Request" status-line is returned.
如果“insert”查询参数不存在或值不是“before”或“after”，则返回“400 Bad Request”状态行。
This parameter contains the instance identifier of the resource to be used as the insertion point for a POST or PUT method.
此参数包含用作POST或PUT方法插入点的资源的实例标识符。
The "point" query parameter MUST be supported by the server.
服务器必须支持“点”查询参数。
The "start-time" query parameter is used to trigger the notification replay feature defined in [RFC5277] and indicate that the replay should start at the time specified. If the stream does not support replay per the "replay-support" attribute returned by the "stream" list entry for the stream resource, then the server MUST return a "400 Bad Request" status-line.
“开始时间”查询参数用于触发[RFC5277]中定义的通知重播功能，并指示重播应在指定的时间开始。如果流不支持根据流资源的“流”列表项返回的“重播支持”属性重播，则服务器必须返回“400错误请求”状态行。
The value of the "start-time" parameter is of type "date-and-time", defined in the "ietf-yang-types" YANG module [RFC6991].
“开始时间”参数的值为“日期和时间”类型，在“ietf yang types”yang模块[RFC6991]中定义。
This parameter is only allowed for GET methods on a "text/event-stream" data resource. A "400 Bad Request" status-line is returned if used for other methods or resource types.
此参数仅允许用于“文本/事件流”数据资源上的GET方法。如果用于其他方法或资源类型，则返回“400错误请求”状态行。
If this parameter is not present, then a replay subscription is not being requested. It is not valid to specify start times that are later than the current time. If the value specified is earlier than the log can support, the replay will begin with the earliest available notification. A client can obtain a server's current time by examining the "Date" header field that the server returns in response messages, according to [RFC7231].
如果此参数不存在，则不会请求重播订阅。指定晚于当前时间的开始时间无效。如果指定的值早于日志支持的值，则重播将以最早的可用通知开始。根据[RFC7231]，客户端可以通过检查服务器在响应消息中返回的“日期”头字段来获取服务器的当前时间。
If this query parameter is supported by the server, then the "replay" query parameter URI MUST be listed in the "capability" leaf-list defined in Section 9.3, and the "stop-time" query parameter MUST also be supported by the server.
如果服务器支持此查询参数，则“replay”查询参数URI必须列在第9.3节中定义的“capability”叶列表中，服务器也必须支持“stop time”查询参数。
If the "replay-support" leaf has the value "true" in the "stream" entry (defined in Section 9.3), then the server MUST support the "start-time" and "stop-time" query parameters for that stream.
如果“replay support”叶在“stream”条目（定义见第9.3节）中的值为“true”，则服务器必须支持该流的“开始时间”和“停止时间”查询参数。
The "stop-time" query parameter is used with the replay feature to indicate the newest notifications of interest. This parameter MUST be used with, and have a value later than, the "start-time" parameter.
“停止时间”查询参数与重播功能一起使用，以指示最新的感兴趣通知。此参数必须与“开始时间”参数一起使用，且其值晚于“开始时间”参数。
The value of the "stop-time" parameter is of type "date-and-time", defined in the "ietf-yang-types" YANG module [RFC6991].
“停止时间”参数的值为“日期和时间”类型，在“ietf yang types”yang模块[RFC6991]中定义。
This parameter is only allowed for GET methods on a "text/event-stream" data resource. A "400 Bad Request" status-line is returned if used for other methods or resource types.
此参数仅允许用于“文本/事件流”数据资源上的GET方法。如果用于其他方法或资源类型，则返回“400错误请求”状态行。
If this parameter is not present, the notifications will continue until the subscription is terminated. Values in the future are valid.
如果此参数不存在，则通知将继续，直到订阅终止。未来的值是有效的。
If this query parameter is supported by the server, then the "replay" query parameter URI MUST be listed in the "capability" leaf-list defined in Section 9.3, and the "start-time" query parameter MUST also be supported by the server.
如果服务器支持此查询参数，则“replay”查询参数URI必须列在第9.3节中定义的“capability”叶列表中，服务器也必须支持“start time”查询参数。
If the "replay-support" leaf is present in the "stream" entry (defined in Section 9.3), then the server MUST support the "start-time" and "stop-time" query parameters for that stream.
如果“流”条目（定义见第9.3节）中存在“重播支持”叶，则服务器必须支持该流的“开始时间”和“停止时间”查询参数。
The "with-defaults" query parameter is used to specify how information about default data nodes should be returned in response to GET requests on data resources.
“with defaults”查询参数用于指定如何返回有关默认数据节点的信息以响应获取数据资源请求。
If the server supports this capability, then it MUST implement the behavior described in Section 4.5.1 of [RFC6243], except applied to the RESTCONF GET operation instead of the NETCONF operations.
如果服务器支持此功能，则必须实现[RFC6243]第4.5.1节中描述的行为，但应用于RESTCONF GET操作而非NETCONF操作的行为除外。
+-------------------+-----------------------------------------------+
| Value | Description |
+-------------------+-----------------------------------------------+
| report-all | All data nodes are reported |
| | |
| trim | Data nodes set to the YANG default are not |
| | reported |
| | |
| explicit | Data nodes set to the YANG default by the |
| | client are reported |
| | |
| report-all-tagged | All data nodes are reported, and defaults are |
| | tagged |
+-------------------+-----------------------------------------------+
+-------------------+-----------------------------------------------+
| Value | Description |
+-------------------+-----------------------------------------------+
| report-all | All data nodes are reported |
| | |
| trim | Data nodes set to the YANG default are not |
| | reported |
| | |
| explicit | Data nodes set to the YANG default by the |
| | client are reported |
| | |
| report-all-tagged | All data nodes are reported, and defaults are |
| | tagged |
+-------------------+-----------------------------------------------+
If the "with-defaults" parameter is set to "report-all", then the server MUST adhere to the default-reporting behavior defined in Section 3.1 of [RFC6243].
如果“with defaults”参数设置为“report all”，则服务器必须遵守[RFC6243]第3.1节中定义的默认报告行为。
If the "with-defaults" parameter is set to "trim", then the server MUST adhere to the default-reporting behavior defined in Section 3.2 of [RFC6243].
如果“with defaults”参数设置为“trim”，则服务器必须遵守[RFC6243]第3.2节中定义的默认报告行为。
If the "with-defaults" parameter is set to "explicit", then the server MUST adhere to the default-reporting behavior defined in Section 3.3 of [RFC6243].
如果“with defaults”参数设置为“explicit”，则服务器必须遵守[RFC6243]第3.3节中定义的默认报告行为。
If the "with-defaults" parameter is set to "report-all-tagged", then the server MUST adhere to the default-reporting behavior defined in Section 3.4 of [RFC6243]. Metadata is reported by the server as specified in Section 5.3. The XML encoding for the "default" attribute sent by the server for default nodes is defined in Section 6 of [RFC6243]. The JSON encoding for the "default" attribute MUST use the same values, as defined in [RFC6243], but encoded according to the rules in [RFC7952]. The module name "ietf-netconf-with-defaults" MUST be used for the "default" attribute.
如果“with defaults”参数设置为“report all taged”，则服务器必须遵守[RFC6243]第3.4节中定义的默认报告行为。元数据由服务器按照第5.3节的规定报告。[RFC6243]的第6节定义了服务器为默认节点发送的“default”属性的XML编码。“default”属性的JSON编码必须使用[RFC6243]中定义的相同值，但根据[RFC7952]中的规则进行编码。模块名称“ietf netconf with defaults”必须用于“default”属性。
If the "with-defaults" parameter is not present, then the server MUST adhere to the default-reporting behavior defined in its "basic-mode" parameter for the "defaults" protocol capability URI, defined in Section 9.1.2.
如果“with defaults”参数不存在，则服务器必须遵守第9.1.2节中定义的“defaults”协议功能URI的“基本模式”参数中定义的默认报告行为。
If the server includes the "with-defaults" query parameter URI in the "capability" leaf-list defined in Section 9.3, then the "with-defaults" query parameter MUST be supported.
如果服务器在第9.3节定义的“功能”叶列表中包含“带默认值”查询参数URI，则必须支持“带默认值”查询参数。
Since the server does not report the "also-supported" parameter as described in Section 4.3 of [RFC6243], it is possible that some values for the "with-defaults" parameter will not be supported. If the server does not support the requested value of the "with-defaults" parameter, the server MUST return a response with a "400 Bad Request" status-line. The error-tag value "invalid-value" is used in this case.
由于服务器不报告[RFC6243]第4.3节所述的“还支持”参数，因此可能不支持“带默认值”参数的某些值。如果服务器不支持“with defaults”参数的请求值，则服务器必须返回一个带有“400 Bad Request”状态行的响应。在这种情况下使用错误标记值“无效值”。
The RESTCONF protocol uses HTTP messages. A single HTTP message corresponds to a single protocol method. Most messages can perform a single task on a single resource, such as retrieving a resource or editing a resource. The exception is the PATCH method, which allows multiple datastore edits within a single message.
RESTCONF协议使用HTTP消息。单个HTTP消息对应于单个协议方法。大多数消息可以在单个资源上执行单个任务，例如检索资源或编辑资源。例外情况是PATCH方法，它允许在一条消息中编辑多个数据存储。
Resources are represented with URIs following the structure for generic URIs in [RFC3986].
资源用URI表示，URI遵循[RFC3986]中的通用URI结构。
A RESTCONF operation is derived from the HTTP method and the request URI, using the following conceptual fields:
RESTCONF操作源自HTTP方法和请求URI，使用以下概念字段：
<OP> /<restconf>/<path>?<query>
<OP> /<restconf>/<path>?<query>
^ ^ ^ ^
| | | |
method entry resource query
^ ^ ^ ^
| | | |
method entry resource query
M M O O
M M O
M=mandatory, O=optional
M=强制性，O=可选
where:
哪里：
<OP> is the HTTP method
<restconf> is the RESTCONF root resource
<path> is the target resource URI
<query> is the query parameter list
<OP> is the HTTP method
<restconf> is the RESTCONF root resource
<path> is the target resource URI
<query> is the query parameter list
o method: the HTTP method identifying the RESTCONF operation requested by the client, to act upon the target resource specified in the request URI. RESTCONF operation details are described in Section 4.
o 方法：标识客户端请求的RESTCONF操作的HTTP方法，用于对请求URI中指定的目标资源进行操作。RESTCONF操作的详细信息在第4节中描述。
o entry: the root of the RESTCONF API configured on this HTTP server, discovered by getting the "/.well-known/host-meta" resource, as described in Section 3.1.
o 条目：此HTTP服务器上配置的RESTCONF API的根，通过获取“/.well-known/host-meta”资源发现，如第3.1节所述。
o resource: the path expression identifying the resource that is being accessed by the RESTCONF operation. If this field is not present, then the target resource is the API itself, represented by the YANG data template named "yang-api", found in Section 8.
o resource：标识RESTCONF操作正在访问的资源的路径表达式。如果此字段不存在，则目标资源是API本身，由第8节中名为“YANG API”的YANG数据模板表示。
o query: the set of parameters associated with the RESTCONF message; see Section 3.4 of [RFC3986]. RESTCONF parameters have the familiar form of "name=value" pairs. Most query parameters are optional to implement by the server and optional to use by the client. Each optional query parameter is identified by a URI. The server MUST list the optional query parameter URIs it supports in the "capability" leaf-list defined in Section 9.3.
o query：与RESTCONF消息关联的参数集；参见[RFC3986]第3.4节。RESTCONF参数具有熟悉的“name=value”对形式。大多数查询参数是可选的，可由服务器实现，也可由客户端使用。每个可选查询参数都由一个URI标识。服务器必须在第9.3节定义的“功能”叶列表中列出其支持的可选查询参数URI。
There is a specific set of parameters defined, although the server MAY choose to support query parameters not defined in this document. The contents of any query parameter value MUST be encoded according to Section 3.4 of [RFC3986]. Any reserved characters MUST be percent-encoded, according to Sections 2.1 and 2.5 of [RFC3986].
虽然服务器可以选择支持本文档中未定义的查询参数，但仍定义了一组特定的参数。任何查询参数值的内容必须根据[RFC3986]第3.4节进行编码。根据[RFC3986]第2.1节和第2.5节，任何保留字符必须进行百分比编码。
Note that the fragment component is not used by the RESTCONF protocol. The fragment is excluded from the target URI by a server, as described in Section 5.1 of [RFC7230].
请注意，RESTCONF协议不使用片段组件。该片段被服务器从目标URI中排除，如[RFC7230]第5.1节所述。
When new resources are created by the client, a "Location" header field is returned, which identifies the path of the newly created resource. The client uses this exact path identifier to access the resource once it has been created.
当客户端创建新资源时，将返回一个“Location”头字段，该字段标识新创建资源的路径。一旦资源被创建，客户端就使用这个精确的路径标识符来访问它。
The target of a RESTCONF operation is a resource. The "path" field in the request URI represents the target resource for the RESTCONF operation.
RESTCONF操作的目标是一个资源。请求URI中的“路径”字段表示RESTCONF操作的目标资源。
Refer to Appendix B for examples of RESTCONF request URIs.
有关RESTCONF请求URI的示例，请参阅附录B。
RESTCONF messages are encoded in HTTP according to [RFC7230]. The "utf-8" character set is used for all messages. RESTCONF message content is sent in the HTTP message-body.
RESTCONF消息按照[RFC7230]在HTTP中编码。“utf-8”字符集用于所有消息。RESTCONF消息内容在HTTP消息体中发送。
Content is encoded in either JSON or XML format. A server MUST support one of either XML or JSON encoding. A server MAY support both XML and JSON encoding. A client will need to support both XML and JSON to interoperate with all RESTCONF servers.
内容以JSON或XML格式编码。服务器必须支持XML或JSON编码之一。服务器可能同时支持XML和JSON编码。客户端需要同时支持XML和JSON才能与所有RESTCONF服务器进行互操作。
XML encoding rules for data nodes are defined in [RFC7950]. The same encoding rules are used for all XML content. JSON encoding rules are defined in [RFC7951]. Additional JSON encoding rules for metadata are defined in [RFC7952]. This encoding is valid JSON, but it also has special encoding rules to identify module namespaces and provide consistent type processing of YANG data.
[RFC7950]中定义了数据节点的XML编码规则。所有XML内容都使用相同的编码规则。JSON编码规则在[RFC7951]中定义。[RFC7952]中定义了元数据的其他JSON编码规则。这种编码是有效的JSON，但它也有特殊的编码规则来标识模块名称空间，并提供一致的数据类型处理。
The request input content encoding format is identified with the "Content-Type" header field. This field MUST be present if a message-body is sent by the client.
请求输入内容编码格式由“内容类型”标题字段标识。如果客户端发送消息正文，则必须存在此字段。
The server MUST support the "Accept" header field and the "406 Not Acceptable" status-line, as defined in [RFC7231]. The response output content encoding formats that the client will accept are identified with the "Accept" header field in the request. If it is not specified, the request input encoding format SHOULD be used, or the server MAY choose any supported content encoding format.
服务器必须支持[RFC7231]中定义的“接受”标题字段和“406不可接受”状态行。客户端将接受的响应输出内容编码格式由请求中的“accept”头字段标识。如果未指定，则应使用请求输入编码格式，或者服务器可以选择任何支持的内容编码格式。
If there was no request input, then the default output encoding is XML or JSON, depending on server preference. File extensions encoded in the request are not used to identify format encoding.
如果没有请求输入，则默认输出编码为XML或JSON，具体取决于服务器首选项。请求中编码的文件扩展名不用于标识格式编码。
A client can determine if the RESTCONF server supports an encoding format by sending a request using a specific format in the "Content-Type" and/or "Accept" header field. If the server does not support the requested input encoding for a request, then it MUST return an error response with a "415 Unsupported Media Type" status-line. If the server does not support any of the requested output encodings for a request, then it MUST return an error response with a "406 Not Acceptable" status-line.
客户机可以通过在“内容类型”和/或“接受”标题字段中使用特定格式发送请求来确定RESTCONF服务器是否支持编码格式。如果服务器不支持请求的输入编码，那么它必须返回一个带有“415不支持的媒体类型”状态行的错误响应。如果服务器不支持请求的任何请求输出编码，那么它必须返回带有“406不可接受”状态行的错误响应。
The RESTCONF protocol needs to support the retrieval of the same metadata that is used in the NETCONF protocol. Information about default leafs, last-modified timestamps, etc. is commonly used to annotate representations of the datastore contents.
RESTCONF协议需要支持检索NETCONF协议中使用的相同元数据。有关默认叶、上次修改的时间戳等信息通常用于注释数据存储内容的表示。
With the XML encoding, the metadata is encoded as attributes in XML, according to Section 3.3 of [W3C.REC-xml-20081126]. With the JSON encoding, the metadata is encoded as specified in [RFC7952].
根据[W3C.REC-XML-20081126]的第3.3节，通过XML编码，元数据被编码为XML中的属性。使用JSON编码，元数据按照[RFC7952]中的规定进行编码。
The following examples are based on the example in Appendix B.3.9. The "report-all-tagged" mode for the "with-defaults" query parameter requires that a "default" attribute be returned for default nodes. These examples show that attribute for the "mtu" leaf.
以下示例基于附录B.3.9中的示例。“with defaults”查询参数的“report all taged”模式要求为默认节点返回“default”属性。这些示例显示了“mtu”叶的属性。
GET /restconf/data/interfaces/interface=eth1
?with-defaults=report-all-tagged HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf/data/interfaces/interface=eth1
?with-defaults=report-all-tagged HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
<interface
xmlns="urn:example.com:params:xml:ns:yang:example-interface">
<name>eth1</name>
<mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0"
wd:default="true">1500</mtu>
<status>up</status>
</interface>
<interface
xmlns="urn:example.com:params:xml:ns:yang:example-interface">
<name>eth1</name>
<mtu xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0"
wd:default="true">1500</mtu>
<status>up</status>
</interface>
Note that RFC 6243 defines the "default" attribute with the XML Schema Definition (XSD), not YANG, so the YANG module name has to be assigned instead of derived from the YANG module. The value "ietf-netconf-with-defaults" is assigned for JSON metadata encoding.
请注意，RFC6243使用XML模式定义（XSD）定义“default”属性，而不是YANG，因此必须指定YANG模块名，而不是从YANG模块派生。为JSON元数据编码分配值“ietf netconf with defaults”。
GET /restconf/data/interfaces/interface=eth1\
?with-defaults=report-all-tagged HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/interfaces/interface=eth1\
?with-defaults=report-all-tagged HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"example:interface" : [
{
"name" : "eth1",
"mtu" : 1500,
"@mtu" : {
"ietf-netconf-with-defaults:default" : true
},
"status" : "up"
}
]
}
{
"example:interface" : [
{
"name" : "eth1",
"mtu" : 1500,
"@mtu" : {
"ietf-netconf-with-defaults:default" : true
},
"status" : "up"
}
]
}
Each message represents some sort of resource access. An HTTP "status-line" header field is returned for each request. If a status code in the "4xx" range is returned in the status-line, then the error information SHOULD be returned in the response, according to the format defined in Section 7.1. If a status code in the "5xx" range is returned in the status-line, then the error information MAY be returned in the response, according to the format defined in Section 7.1. If a status code in the "1xx", "2xx", or "3xx" range is returned in the status-line, then error information MUST NOT be returned in the response, since these ranges do not represent error conditions.
每条消息代表某种资源访问。为每个请求返回一个HTTP“status line”头字段。如果在状态行中返回“4xx”范围内的状态代码，则应根据第7.1节中定义的格式在响应中返回错误信息。如果在状态行中返回“5xx”范围内的状态代码，则可根据第7.1节中定义的格式在响应中返回错误信息。如果状态行中返回“1xx”、“2xx”或“3xx”范围内的状态代码，则响应中不得返回错误信息，因为这些范围不表示错误条件。
Since the datastore contents change at unpredictable times, responses from a RESTCONF server generally SHOULD NOT be cached.
由于数据存储内容会在不可预测的时间发生更改，因此通常不应缓存来自RESTCONF服务器的响应。
The server MUST include a "Cache-Control" header field in every response that specifies whether the response should be cached.
服务器必须在每个响应中包含一个“缓存控制”头字段，该字段指定是否应缓存响应。
Instead of relying on HTTP caching, the client SHOULD track the "ETag" and/or "Last-Modified" header fields returned by the server for the datastore resource (or data resource, if the server supports it). A retrieval request for a resource can include the "If-None-Match" and/or "If-Modified-Since" header fields, which will cause the server to return a "304 Not Modified" status-line if the resource has not changed. The client MAY use the HEAD method to retrieve just the message header fields, which SHOULD include the "ETag" and "Last-Modified" header fields, if this metadata is maintained for the target resource.
客户端应该跟踪服务器为数据存储资源（或数据资源，如果服务器支持）返回的“ETag”和/或“Last Modified”头字段，而不是依赖HTTP缓存。对资源的检索请求可以包括“If None Match”和/或“If Modified Since”头字段，如果资源没有更改，这将导致服务器返回“304 Not Modified”状态行。如果为目标资源维护此元数据，则客户端可以使用HEAD方法仅检索消息头字段，其中应包括“ETag”和“Last Modified”头字段。
Note that access control can be applied to data resources, such that the values in the "Last-Modified" and "ETag" headers maintained for a data resource may not be reliable, as described in Section 4.3.
请注意，访问控制可应用于数据资源，因此为数据资源维护的“上次修改”和“ETag”标题中的值可能不可靠，如第4.3节所述。
The RESTCONF protocol supports YANG-defined event notifications. The solution preserves aspects of NETCONF event notifications [RFC5277] while utilizing the Server-Sent Events [W3C.REC-eventsource-20150203] transport strategy.
RESTCONF协议支持定义的事件通知。该解决方案在利用服务器发送的事件[W3C.REC-eventsource-20150203]传输策略时保留了NETCONF事件通知[RFC5277]的各个方面。
A RESTCONF server MAY support RESTCONF notifications. Clients may determine if a server supports RESTCONF notifications by using the HTTP OPTIONS, HEAD, or GET method on the "stream" list. The server does not support RESTCONF notifications if an HTTP error code is returned (e.g., a "404 Not Found" status-line).
RESTCONF服务器可能支持RESTCONF通知。客户端可以通过使用“stream”列表上的HTTP选项、HEAD或GET方法来确定服务器是否支持RESTCONF通知。如果返回HTTP错误代码（例如，“404未找到”状态行），则服务器不支持RESTCONF通知。
A RESTCONF server that supports notifications will populate a stream resource for each notification delivery service access point. A RESTCONF client can retrieve the list of supported event streams from a RESTCONF server using the GET method on the "stream" list.
支持通知的RESTCONF服务器将为每个通知传递服务访问点填充一个流资源。RESTCONF客户端可以使用“stream”列表上的GET方法从RESTCONF服务器检索支持的事件流列表。
The "restconf-state/streams" container definition in the "ietf-restconf-monitoring" module (defined in Section 9.3) is used to specify the structure and syntax of the conceptual child resources within the "streams" resource.
“ietf restconf监控”模块（第9.3节中定义）中的“restconf状态/流”容器定义用于指定“流”资源中概念子资源的结构和语法。
For example:
例如：
The client might send the following request:
客户端可能会发送以下请求：
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
streams HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
streams HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might send the following response:
服务器可能会发送以下响应：
HTTP/1.1 200 OK
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Content-Type: application/yang-data+xml
<streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<stream>
<name>NETCONF</name>
<description>default NETCONF event stream</description>
<replay-support>true</replay-support>
<replay-log-creation-time>\
2007-07-08T00:00:00Z\
</replay-log-creation-time>
<access>
<encoding>xml</encoding>
<location>https://example.com/streams/NETCONF\
</location>
</access>
<access>
<encoding>json</encoding>
<location>https://example.com/streams/NETCONF-JSON\
</location>
</access>
</stream>
<streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<stream>
<name>NETCONF</name>
<description>default NETCONF event stream</description>
<replay-support>true</replay-support>
<replay-log-creation-time>\
2007-07-08T00:00:00Z\
</replay-log-creation-time>
<access>
<encoding>xml</encoding>
<location>https://example.com/streams/NETCONF\
</location>
</access>
<access>
<encoding>json</encoding>
<location>https://example.com/streams/NETCONF-JSON\
</location>
</access>
</stream>
<stream>
<name>SNMP</name>
<description>SNMP notifications</description>
<replay-support>false</replay-support>
<access>
<encoding>xml</encoding>
<location>https://example.com/streams/SNMP</location>
</access>
</stream>
<stream>
<name>syslog-critical</name>
<description>Critical and higher severity</description>
<replay-support>true</replay-support>
<replay-log-creation-time>
2007-07-01T00:00:00Z
</replay-log-creation-time>
<access>
<encoding>xml</encoding>
<location>\
https://example.com/streams/syslog-critical\
</location>
</access>
</stream>
</streams>
<stream>
<name>SNMP</name>
<description>SNMP notifications</description>
<replay-support>false</replay-support>
<access>
<encoding>xml</encoding>
<location>https://example.com/streams/SNMP</location>
</access>
</stream>
<stream>
<name>syslog-critical</name>
<description>Critical and higher severity</description>
<replay-support>true</replay-support>
<replay-log-creation-time>
2007-07-01T00:00:00Z
</replay-log-creation-time>
<access>
<encoding>xml</encoding>
<location>\
https://example.com/streams/syslog-critical\
</location>
</access>
</stream>
</streams>
RESTCONF clients can determine the URL for the subscription resource (to receive notifications) by sending an HTTP GET request for the "location" leaf with the "stream" list entry. The value returned by the server can be used for the actual notification subscription.
RESTCONF客户端可以通过发送带有“stream”列表项的“location”叶的HTTP GET请求来确定订阅资源的URL（以接收通知）。服务器返回的值可用于实际通知订阅。
The client will send an HTTP GET request for the URL returned by the server with the "Accept" type "text/event-stream".
客户端将发送一个HTTP GET请求，请求服务器返回的URL，其“接受”类型为“文本/事件流”。
The server will treat the connection as an event stream, using the Server-Sent Events [W3C.REC-eventsource-20150203] transport strategy.
服务器将使用服务器发送的事件[W3C.REC-eventsource-20150203]传输策略将连接视为事件流。
The server MAY support query parameters for a GET method on this resource. These parameters are specific to each event stream.
服务器可能支持此资源上GET方法的查询参数。这些参数特定于每个事件流。
For example:
例如：
The client might send the following request:
客户端可能会发送以下请求：
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
streams/stream=NETCONF/access=xml/location HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
streams/stream=NETCONF/access=xml/location HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might send the following response:
服务器可能会发送以下响应：
HTTP/1.1 200 OK
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Content-Type: application/yang-data+xml
<location
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">\
https://example.com/streams/NETCONF\
</location>
<location
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">\
https://example.com/streams/NETCONF\
</location>
The RESTCONF client can then use this URL value to start monitoring the event stream:
然后，RESTCONF客户端可以使用此URL值开始监视事件流：
GET /streams/NETCONF HTTP/1.1
Host: example.com
Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
GET /streams/NETCONF HTTP/1.1
Host: example.com
Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
A RESTCONF client MAY request that the server compress the events using the HTTP header field "Accept-Encoding". For instance:
RESTCONF客户端可能会请求服务器使用HTTP头字段“Accept Encoding”压缩事件。例如：
GET /streams/NETCONF HTTP/1.1
Host: example.com
Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Accept-Encoding: gzip, deflate
GET /streams/NETCONF HTTP/1.1
Host: example.com
Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Accept-Encoding: gzip, deflate
The server SHOULD support the NETCONF event stream defined in Section 3.2.3 of [RFC5277]. The notification messages for this stream are encoded in XML.
服务器应支持[RFC5277]第3.2.3节中定义的NETCONF事件流。此流的通知消息以XML编码。
The server MAY support additional streams that represent the semantic content of the NETCONF event stream, but using a representation with a different media type.
服务器可能支持表示NETCONF事件流语义内容的附加流，但使用具有不同媒体类型的表示。
The server MAY support the "start-time", "stop-time", and "filter" query parameters, defined in Section 4.8. Refer to Appendix B.3.6 for filter parameter examples.
服务器可能支持第4.8节中定义的“开始时间”、“停止时间”和“过滤器”查询参数。有关过滤器参数示例，请参阅附录B.3.6。
RESTCONF notifications are encoded according to the definition of the event stream.
RESTCONF通知根据事件流的定义进行编码。
The structure of the event data is based on the <notification> element definition in Section 4 of [RFC5277]. It MUST conform to the schema for the <notification> element in Section 4 of [RFC5277], using the XML namespace as defined in the XSD as follows:
事件数据的结构基于[RFC5277]第4节中的<notification>元素定义。它必须符合[RFC5277]第4节中<notification>元素的模式，使用XSD中定义的XML命名空间，如下所示：
urn:ietf:params:xml:ns:netconf:notification:1.0
urn:ietf:params:xml:ns:netconf:notification:1.0
For JSON-encoding purposes, the module name for the "notification" element is "ietf-restconf".
出于JSON编码目的，“notification”元素的模块名为“ietf restconf”。
Two child nodes within the "notification" container are expected, representing the event time and the event payload. The "eventTime" node is defined within the same XML namespace as the <notification> element. It is defined to be within the "ietf-restconf" module namespace for JSON-encoding purposes.
“notification”容器中应有两个子节点，表示事件时间和事件负载。“eventTime”节点定义在与<notification>元素相同的XML命名空间中。出于JSON编码目的，它被定义在“ietf restconf”模块名称空间中。
The name and namespace of the payload element are determined by the YANG module containing the notification-stmt representing the notification message.
有效负载元素的名称和命名空间由包含表示通知消息的通知stmt的模块确定。
In the following example, the YANG module "example-mod" is used:
在以下示例中，使用了“示例模块”：
module example-mod {
namespace "http://example.com/event/1.0";
prefix ex;
module example-mod {
namespace "http://example.com/event/1.0";
prefix ex;
organization "Example, Inc.";
contact "support at example.com";
description "Example Notification Data Model Module.";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 2-9976.";
}
organization "Example, Inc.";
contact "support at example.com";
description "Example Notification Data Model Module.";
revision "2016-07-07" {
description "Initial version.";
reference "example.com document 2-9976.";
}
notification event {
description "Example notification event.";
leaf event-class {
type string;
description "Event class identifier.";
}
container reporting-entity {
description "Event specific information.";
leaf card {
type string;
description "Line card identifier.";
}
}
leaf severity {
type string;
description "Event severity description.";
}
}
}
notification event {
description "Example notification event.";
leaf event-class {
type string;
description "Event class identifier.";
}
container reporting-entity {
description "Event specific information.";
leaf card {
type string;
description "Line card identifier.";
}
}
leaf severity {
type string;
description "Event severity description.";
}
}
}
An example SSE event notification encoded using XML:
使用XML编码的SSE事件通知示例：
data: <notification
data: xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
data: <eventTime>2013-12-21T00:01:00Z</eventTime>
data: <event xmlns="http://example.com/event/1.0">
data: <event-class>fault</event-class>
data: <reporting-entity>
data: <card>Ethernet0</card>
data: </reporting-entity>
data: <severity>major</severity>
data: </event>
data: </notification>
data: <notification
data: xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
data: <eventTime>2013-12-21T00:01:00Z</eventTime>
data: <event xmlns="http://example.com/event/1.0">
data: <event-class>fault</event-class>
data: <reporting-entity>
data: <card>Ethernet0</card>
data: </reporting-entity>
data: <severity>major</severity>
data: </event>
data: </notification>
An example SSE event notification encoded using JSON:
使用JSON编码的SSE事件通知示例：
data: {
data: "ietf-restconf:notification" : {
data: "eventTime" : "2013-12-21T00:01:00Z",
data: "example-mod:event" : {
data: "event-class" : "fault",
data: "reporting-entity" : { "card" : "Ethernet0" },
data: "severity" : "major"
data: }
data: }
data: }
data: {
data: "ietf-restconf:notification" : {
data: "eventTime" : "2013-12-21T00:01:00Z",
data: "example-mod:event" : {
data: "event-class" : "fault",
data: "reporting-entity" : { "card" : "Ethernet0" },
data: "severity" : "major"
data: }
data: }
data: }
Alternatively, since neither XML nor JSON is whitespace sensitive, the above messages can be encoded onto a single line. For example:
或者，由于XML和JSON都不区分空格，因此可以将上述消息编码到一行。例如：
XML:
XML:
data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notif\
ication:1.0"><eventTime>2013-12-21T00:01:00Z</eventTime><event \
xmlns="http://example.com/event/1.0"><event-class>fault</event-\
class><reportingEntity><card>Ethernet0</card></reporting-entity>\
<severity>major</severity></event></notification>
data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notif\
ication:1.0"><eventTime>2013-12-21T00:01:00Z</eventTime><event \
xmlns="http://example.com/event/1.0"><event-class>fault</event-\
class><reportingEntity><card>Ethernet0</card></reporting-entity>\
<severity>major</severity></event></notification>
JSON:
JSON:
data: {"ietf-restconf:notification":{"eventTime":"2013-12-21\
T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
tingEntity":{"card":"Ethernet0"},"severity":"major"}}}
data: {"ietf-restconf:notification":{"eventTime":"2013-12-21\
T00:01:00Z","example-mod:event":{"event-class": "fault","repor\
tingEntity":{"card":"Ethernet0"},"severity":"major"}}}
The SSE specification supports the following additional fields: "event", "id", and "retry". A RESTCONF server MAY send the "retry" field, and if it does, RESTCONF clients SHOULD use it. A RESTCONF server SHOULD NOT send the "event" or "id" fields, as there are no meaningful values that could be used for them that would not be redundant to the contents of the notification itself. RESTCONF servers that do not send the "id" field also do not need to support the HTTP header field "Last-Event-ID" [W3C.REC-eventsource-20150203]. RESTCONF servers that do send the "id" field SHOULD support the "start-time" query parameter as the preferred means for a client to specify where to restart the event stream.
SSE规范支持以下附加字段：“事件”、“id”和“重试”。RESTCONF服务器可以发送“重试”字段，如果发送，RESTCONF客户端应该使用它。RESTCONF服务器不应发送“event”或“id”字段，因为没有可用于这些字段的有意义的值，这些值对于通知本身的内容来说是多余的。不发送“id”字段的RESTCONF服务器也不需要支持HTTP头字段“Last Event id”[W3C.REC-eventsource-20150203]。发送“id”字段的RESTCONF服务器应该支持“start time”查询参数，作为客户端指定在何处重新启动事件流的首选方法。
HTTP status codes are used to report success or failure for RESTCONF operations. The error information that NETCONF error responses contain in the <rpc-error> element is adapted for use in RESTCONF, and <errors> data tree information is returned for the "4xx" and "5xx" classes of status codes.
HTTP状态代码用于报告RESTCONF操作的成功或失败。NETCONF error responses包含在<rpc error>元素中的错误信息被改编用于RESTCONF，并且<errors>数据树信息被返回给“4xx”和“5xx”状态代码类。
Since an operation resource is defined with a YANG "rpc" statement and an action is defined with a YANG "action" statement, a mapping from the NETCONF <error-tag> value to the HTTP status code is needed. The specific error-tag and response code to use are specific to the data model and might be contained in the YANG "description" statement for the "action" or "rpc" statement.
由于操作资源是用YANG“rpc”语句定义的，操作是用YANG“action”语句定义的，因此需要从NETCONF<error tag>值到HTTP状态代码的映射。要使用的特定错误标记和响应代码特定于数据模型，并且可能包含在“action”或“rpc”语句的“description”语句中。
+-------------------------+------------------+
| error-tag | status code |
+-------------------------+------------------+
| in-use | 409 |
| | |
| invalid-value | 400, 404, or 406 |
| | |
| (request) too-big | 413 |
| | |
| (response) too-big | 400 |
| | |
| missing-attribute | 400 |
| | |
| bad-attribute | 400 |
| | |
| unknown-attribute | 400 |
| | |
| bad-element | 400 |
| | |
| unknown-element | 400 |
| | |
| unknown-namespace | 400 |
| | |
| access-denied | 401 or 403 |
| | |
| lock-denied | 409 |
| | |
| resource-denied | 409 |
| | |
| rollback-failed | 500 |
| | |
| data-exists | 409 |
| | |
| data-missing | 409 |
| | |
| operation-not-supported | 405 or 501 |
| | |
| operation-failed | 412 or 500 |
| | |
| partial-operation | 500 |
| | |
| malformed-message | 400 |
+-------------------------+------------------+
+-------------------------+------------------+
| error-tag | status code |
+-------------------------+------------------+
| in-use | 409 |
| | |
| invalid-value | 400, 404, or 406 |
| | |
| (request) too-big | 413 |
| | |
| (response) too-big | 400 |
| | |
| missing-attribute | 400 |
| | |
| bad-attribute | 400 |
| | |
| unknown-attribute | 400 |
| | |
| bad-element | 400 |
| | |
| unknown-element | 400 |
| | |
| unknown-namespace | 400 |
| | |
| access-denied | 401 or 403 |
| | |
| lock-denied | 409 |
| | |
| resource-denied | 409 |
| | |
| rollback-failed | 500 |
| | |
| data-exists | 409 |
| | |
| data-missing | 409 |
| | |
| operation-not-supported | 405 or 501 |
| | |
| operation-failed | 412 or 500 |
| | |
| partial-operation | 500 |
| | |
| malformed-message | 400 |
+-------------------------+------------------+
Mapping from <error-tag> to Status Code
从<error tag>映射到状态代码
When an error occurs for a request message on any resource type and the status code that will be returned is in the "4xx" range (except for status code "403 Forbidden"), the server SHOULD send a response message-body containing the information described by the "yang-errors" YANG data template within the "ietf-restconf" module found in Section 8. The Content-Type of this response message MUST be "application/yang-data", plus, optionally, a structured syntax name suffix.
当任何资源类型上的请求消息发生错误且将返回的状态代码在“4xx”范围内（状态代码“403禁止”除外）时，服务器应发送一条响应消息正文，其中包含第8节中“ietf restconf”模块内的“yang errors”yang数据模板描述的信息。此响应消息的内容类型必须是“应用程序/数据”，还可以选择添加结构化语法名称后缀。
The client SHOULD specify the desired encoding(s) for response messages by specifying the appropriate media type(s) in the "Accept" header. If the client did not specify an "Accept" header, then the same structured syntax name suffix used in the request message SHOULD be used, or the server MAY choose any supported message-encoding format. If there is no request message, the server MUST select "application/yang-data+xml" or "application/yang-data+json", depending on server preference. All of the examples in this document, except for the one below, assume that XML encoding will be returned if there is an error.
客户端应通过在“接受”标题中指定适当的媒体类型来指定响应消息所需的编码。如果客户端未指定“Accept”头，则应使用请求消息中使用的相同结构化语法名称后缀，或者服务器可以选择任何支持的消息编码格式。如果没有请求消息，服务器必须根据服务器的首选项选择“application/yang data+xml”或“application/yang data+json”。本文档中的所有示例（以下示例除外）都假定，如果出现错误，将返回XML编码。
YANG tree diagram for <errors> data:
<errors>数据的杨树图：
+---- errors
+---- error*
+---- error-type enumeration
+---- error-tag string
+---- error-app-tag? string
+---- error-path? instance-identifier
+---- error-message? string
+---- error-info?
+---- errors
+---- error*
+---- error-type enumeration
+---- error-tag string
+---- error-app-tag? string
+---- error-path? instance-identifier
+---- error-message? string
+---- error-info?
The semantics and syntax for RESTCONF error messages are defined with the "yang-errors" YANG data template extension, found in Section 8.
RESTCONF错误消息的语义和语法是通过第8节中的“yang errors”yang数据模板扩展定义的。
Examples:
示例：
The following example shows an error returned for a "lock-denied" error that can occur if a NETCONF client has locked a datastore. The RESTCONF client is attempting to delete a data resource. Note that an "Accept" header field is used to specify the desired encoding for the error message. There would be no response message-body content if this operation was successful.
以下示例显示了针对“锁定被拒绝”错误返回的错误，如果NETCONF客户端锁定了数据存储，则可能会发生该错误。RESTCONF客户端正在尝试删除数据资源。请注意，“接受”标题字段用于指定错误消息所需的编码。如果此操作成功，则不会有响应消息正文内容。
DELETE /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+json
DELETE /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"ietf-restconf:errors" : {
"error" : [
{
"error-type" : "protocol",
"error-tag" : "lock-denied",
"error-message" : "Lock failed; lock already held"
}
]
}
}
{
"ietf-restconf:errors" : {
"error" : [
{
"error-type" : "protocol",
"error-tag" : "lock-denied",
"error-message" : "Lock failed; lock already held"
}
]
}
}
The following example shows an error returned for a "data-exists" error on a data resource. The "jukebox" resource already exists, so it cannot be created.
The following example shows an error returned for a "data-exists" error on a data resource. The "jukebox" resource already exists, so it cannot be created.translate error, please retry
The client might send the following:
客户端可能会发送以下内容：
POST /restconf/data/example-jukebox:jukebox HTTP/1.1
Host: example.com
POST /restconf/data/example-jukebox:jukebox HTTP/1.1
Host: example.com
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+xml
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error>
<error-type>protocol</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
xmlns:jbox="https://example.com/ns/example-jukebox">\
/rc:restconf/rc:data/jbox:jukebox
</error-path>
<error-message>
Data already exists; cannot create new resource
</error-message>
</error>
</errors>
<errors xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<error>
<error-type>protocol</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:rc="urn:ietf:params:xml:ns:yang:ietf-restconf"
xmlns:jbox="https://example.com/ns/example-jukebox">\
/rc:restconf/rc:data/jbox:jukebox
</error-path>
<error-message>
Data already exists; cannot create new resource
</error-message>
</error>
</errors>
The "ietf-restconf" module defines conceptual definitions within an extension and two groupings, which are not meant to be implemented as datastore contents by a server. For example, the "restconf" container is not intended to be implemented as a top-level data node (under the "/restconf/data" URI).
“ietf restconf”模块在一个扩展和两个分组中定义了概念定义，这两个分组并不意味着由服务器实现为数据存储内容。例如，“restconf”容器不打算实现为顶级数据节点（在“/restconf/data”URI下）。
Note that the "ietf-restconf" module does not have any protocol-accessible objects, so no YANG tree diagram is shown.
请注意，“ietf restconf”模块没有任何协议可访问的对象，因此没有显示YANG树图。
<CODE BEGINS>
<代码开始>
file "ietf-restconf@2017-01-26.yang"
文件“ietf”-restconf@2017-01-26.杨”
module ietf-restconf {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf";
prefix "rc";
module ietf-restconf {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang: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 basic RESTCONF media type definitions used in RESTCONF protocol messages.
description“此模块包含RESTCONF协议消息中使用的基本RESTCONF媒体类型定义的规范。
Note that the YANG definitions within this module do not represent configuration data of any kind. The 'restconf-media-type' YANG extension statement provides a normative syntax for XML and JSON message-encoding purposes.
请注意，此模块中的定义并不表示任何类型的配置数据。“restconf media type”扩展语句为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 8040; see the RFC itself for full legal notices.";
该模块的此版本是RFC 8040的一部分；有关完整的法律通知，请参见RFC本身。“；
revision 2017-01-26 {
description
"Initial revision.";
reference
"RFC 8040: RESTCONF Protocol.";
}
revision 2017-01-26 {
description
"Initial revision.";
reference
"RFC 8040: RESTCONF Protocol.";
}
extension yang-data {
argument name {
yin-element true;
}
description
"This extension is used to specify a YANG data template that
represents conceptual data defined in YANG. It is
intended to describe hierarchical data independent of
protocol context or specific message-encoding format.
Data definition statements within a yang-data extension
specify the generic syntax for the specific YANG data
template, whose name is the argument of the 'yang-data'
extension statement.
extension yang-data {
argument name {
yin-element true;
}
description
"This extension is used to specify a YANG data template that
represents conceptual data defined in YANG. It is
intended to describe hierarchical data independent of
protocol context or specific message-encoding format.
Data definition statements within a yang-data extension
specify the generic syntax for the specific YANG data
template, whose name is the argument of the 'yang-data'
extension statement.
Note that this extension does not define a media type. A specification using this extension MUST specify the message-encoding rules, including the content media type.
请注意，此扩展不定义媒体类型。使用此扩展的规范必须指定消息编码规则，包括内容媒体类型。
The mandatory 'name' parameter value identifies the YANG data template that is being defined. It contains the template name.
必需的“name”参数值标识正在定义的数据模板。它包含模板名称。
This extension is ignored unless it appears as a top-level statement. It MUST contain data definition statements that result in exactly one container data node definition. An instance of a YANG data template can thus be translated into an XML instance document, whose top-level element corresponds to the top-level container.
除非此扩展名显示为顶级语句，否则将忽略它。它必须包含只产生一个容器数据节点定义的数据定义语句。因此，可以将数据模板的实例转换为XML实例文档，其顶级元素对应于顶级容器。
The module name and namespace values for the YANG module using the extension statement are assigned to instance document data conforming to the data definition statements within this extension.
使用扩展语句的模块的模块名和名称空间值被分配给符合此扩展中的数据定义语句的实例文档数据。
The substatements of this extension MUST follow the 'data-def-stmt' rule in the YANG ABNF.
此扩展的子状态必须遵循F中的“数据定义stmt”规则。
The XPath document root is the extension statement itself, such that the child nodes of the document root are represented by the data-def-stmt substatements within this extension. This conceptual document is the context for the following YANG statements:
XPath文档根是扩展语句本身，因此文档根的子节点由此扩展中的data def stmt子语句表示。本概念性文件是以下声明的上下文：
- must-stmt - when-stmt - path-stmt - min-elements-stmt - max-elements-stmt - mandatory-stmt - unique-stmt - ordered-by - instance-identifier data type
- 必须stmt-when stmt-path stmt-min elements stmt-max elements stmt-mandatory stmt-unique stmt-ordered by-实例标识符数据类型
The following data-def-stmt substatements are constrained when used within a 'yang-data' extension statement.
在“yang data”扩展语句中使用时，以下数据定义stmt子语句受到约束。
- The list-stmt is not required to have a key-stmt defined.
- The if-feature-stmt is ignored if present.
- The config-stmt is ignored if present.
- The available identity values for any 'identityref'
leaf or leaf-list nodes are limited to the module
containing this extension statement and the modules
imported into that module.
";
}
- The list-stmt is not required to have a key-stmt defined.
- The if-feature-stmt is ignored if present.
- The config-stmt is ignored if present.
- The available identity values for any 'identityref'
leaf or leaf-list nodes are limited to the module
containing this extension statement and the modules
imported into that module.
";
}
rc:yang-data yang-errors {
uses errors;
}
rc:yang-data yang-errors {
uses errors;
}
rc:yang-data yang-api {
uses restconf;
}
rc:yang-data yang-api {
uses restconf;
}
grouping errors {
description
"A grouping that contains a YANG container
representing the syntax and semantics of a
YANG Patch error report within a response message.";
grouping errors {
description
"A grouping that contains a YANG container
representing the syntax and semantics of a
YANG Patch error report within a response message.";
container errors {
description
"Represents an error report returned by the server if
a request results in an error.";
container errors {
description
"Represents an error report returned by the server if
a request results in an error.";
list error {
description
"An entry containing information about one
specific error that occurred while processing
a RESTCONF request.";
reference
"RFC 6241, Section 4.3.";
list error {
description
"An entry containing information about one
specific error that occurred while processing
a RESTCONF request.";
reference
"RFC 6241, Section 4.3.";
leaf error-type {
type enumeration {
enum transport {
description
"The transport layer.";
}
enum rpc {
description
"The rpc or notification layer.";
}
enum protocol {
description
"The protocol operation layer.";
}
enum application {
description
"The server application layer.";
}
}
mandatory true;
description
"The protocol layer where the error occurred.";
}
leaf error-type {
type enumeration {
enum transport {
description
"The transport layer.";
}
enum rpc {
description
"The rpc or notification layer.";
}
enum protocol {
description
"The protocol operation layer.";
}
enum application {
description
"The server application layer.";
}
}
mandatory true;
description
"The protocol layer where the error occurred.";
}
leaf error-tag {
type string;
mandatory true;
description
"The enumerated error-tag.";
}
leaf error-tag {
type string;
mandatory true;
description
"The enumerated error-tag.";
}
leaf error-app-tag {
type string;
description
"The application-specific error-tag.";
}
leaf error-app-tag {
type string;
description
"The application-specific error-tag.";
}
leaf error-path {
type instance-identifier;
description
"The YANG instance identifier associated
with the error node.";
}
leaf error-path {
type instance-identifier;
description
"The YANG instance identifier associated
with the error node.";
}
leaf error-message {
type string;
description
"A message describing the error.";
}
leaf error-message {
type string;
description
"A message describing the error.";
}
anydata error-info {
description
"This anydata value MUST represent a container with
zero or more data nodes representing additional
error information.";
}
}
}
}
anydata error-info {
description
"This anydata value MUST represent a container with
zero or more data nodes representing additional
error information.";
}
}
}
}
grouping restconf {
description
"Conceptual grouping representing the RESTCONF
root resource.";
grouping restconf {
description
"Conceptual grouping representing the RESTCONF
root resource.";
container restconf {
description
"Conceptual container representing the RESTCONF
root resource.";
container restconf {
description
"Conceptual container representing the RESTCONF
root resource.";
container data {
description
"Container representing the datastore resource.
Represents the conceptual root of all state data
and configuration data supported by the server.
The child nodes of this container can be any data
resources that are defined as top-level data nodes
from the YANG modules advertised by the server in
the 'ietf-yang-library' module.";
}
container data {
description
"Container representing the datastore resource.
Represents the conceptual root of all state data
and configuration data supported by the server.
The child nodes of this container can be any data
resources that are defined as top-level data nodes
from the YANG modules advertised by the server in
the 'ietf-yang-library' module.";
}
container operations { description "Container for all operation resources.
容器操作{description“容器，用于所有操作资源。
Each resource is represented as an empty leaf with the name of the RPC operation from the YANG 'rpc' statement.
每个资源都表示为一个空叶，其中包含“RPC”语句中的RPC操作的名称。
For example, the 'system-restart' RPC operation defined in the 'ietf-system' module would be represented as an empty leaf in the 'ietf-system' namespace. This is a conceptual leaf and will not actually be found in the module:
例如，“ietf系统”模块中定义的“系统重启”RPC操作将在“ietf系统”命名空间中表示为空叶。这是一个概念页，在模块中实际上找不到：
module ietf-system {
leaf system-reset {
type empty;
}
}
module ietf-system {
leaf system-reset {
type empty;
}
}
To invoke the 'system-restart' RPC operation:
要调用“系统重新启动”RPC操作，请执行以下操作：
POST /restconf/operations/ietf-system:system-restart
POST /restconf/operations/ietf-system:system-restart
To discover the RPC operations supported by the server:
要查找服务器支持的RPC操作，请执行以下操作：
GET /restconf/operations
GET/restconf/operations
In XML, the YANG module namespace identifies the module:
在XML中，模块名称空间标识模块：
<system-restart
xmlns='urn:ietf:params:xml:ns:yang:ietf-system'/>
<system-restart
xmlns='urn:ietf:params:xml:ns:yang:ietf-system'/>
In JSON, the YANG module name identifies the module:
在JSON中，模块名称标识模块：
{ 'ietf-system:system-restart' : [null] }
";
}
{ 'ietf-system:system-restart' : [null] }
";
}
leaf yang-library-version {
type string {
pattern '\d{4}-\d{2}-\d{2}';
}
config false;
mandatory true;
description
"Identifies the revision date of the 'ietf-yang-library'
module that is implemented by this RESTCONF server.
Indicates the year, month, and day in YYYY-MM-DD
numeric format.";
}
}
}
leaf yang-library-version {
type string {
pattern '\d{4}-\d{2}-\d{2}';
}
config false;
mandatory true;
description
"Identifies the revision date of the 'ietf-yang-library'
module that is implemented by this RESTCONF server.
Indicates the year, month, and day in YYYY-MM-DD
numeric format.";
}
}
}
}
}
<CODE ENDS>
<代码结束>
The "ietf-restconf-monitoring" module provides information about the RESTCONF protocol capabilities and event streams available from the server. A RESTCONF server MUST implement the "ietf-restconf-monitoring" module.
“ietf restconf监控”模块提供有关restconf协议功能和服务器可用事件流的信息。RESTCONF服务器必须实现“ietf RESTCONF监控”模块。
YANG tree diagram for the "ietf-restconf-monitoring" module:
“ietf restconf监控”模块的杨树图：
+--ro restconf-state
+--ro capabilities
| +--ro capability* inet:uri
+--ro streams
+--ro stream* [name]
+--ro name string
+--ro description? string
+--ro replay-support? boolean
+--ro replay-log-creation-time? yang:date-and-time
+--ro access* [encoding]
+--ro encoding string
+--ro location inet:uri
+--ro restconf-state
+--ro capabilities
| +--ro capability* inet:uri
+--ro streams
+--ro stream* [name]
+--ro name string
+--ro description? string
+--ro replay-support? boolean
+--ro replay-log-creation-time? yang:date-and-time
+--ro access* [encoding]
+--ro encoding string
+--ro location inet:uri
This mandatory container holds the RESTCONF protocol capability URIs supported by the server.
此强制容器包含服务器支持的RESTCONF协议功能URI。
The server MAY maintain a last-modified timestamp for this container and return the "Last-Modified" header field when this data node is retrieved with the GET or HEAD methods. Note that the last-modified timestamp for the datastore resource is not affected by changes to this subtree.
当使用GET或HEAD方法检索此数据节点时，服务器可以维护此容器的上次修改的时间戳，并返回“上次修改的”头字段。请注意，数据存储资源的上次修改的时间戳不受对此子树的更改的影响。
The server SHOULD maintain an entity-tag for this container and return the "ETag" header field when this data node is retrieved with the GET or HEAD methods. Note that the entity-tag for the datastore resource is not affected by changes to this subtree.
当使用GET或HEAD方法检索此数据节点时，服务器应维护此容器的实体标记并返回“ETag”头字段。请注意，数据存储资源的实体标记不受对此子树的更改的影响。
The server MUST include a "capability" URI leaf-list entry for the "defaults" mode used by the server, defined in Section 9.1.2.
服务器必须包含一个“功能”URI叶列表条目，用于第9.1.2节中定义的服务器使用的“默认”模式。
The server MUST include a "capability" URI leaf-list entry identifying each supported optional protocol feature. This includes optional query parameters and MAY include other capability URIs defined outside this document.
服务器必须包含一个“功能”URI叶列表条目，标识每个受支持的可选协议功能。这包括可选的查询参数，还可能包括在此文档之外定义的其他功能URI。
A new set of RESTCONF Capability URIs are defined to identify the specific query parameters (defined in Section 4.8) supported by the server.
定义了一组新的RESTCONF功能URI，以标识服务器支持的特定查询参数（在第4.8节中定义）。
The server MUST include a "capability" leaf-list entry for each optional query parameter that it supports.
服务器必须为其支持的每个可选查询参数包含一个“capability”叶列表条目。
+----------------+---------+---------------------------------------+
| Name | Section | URI |
| | | |
+----------------+---------+---------------------------------------+
| depth | 4.8.2 | urn:ietf:params:restconf:capability: |
| | | depth:1.0 |
| | | |
| fields | 4.8.3 | urn:ietf:params:restconf:capability: |
| | | fields:1.0 |
| | | |
| filter | 4.8.4 | urn:ietf:params:restconf:capability: |
| | | filter:1.0 |
| | | |
| replay | 4.8.7 | urn:ietf:params:restconf:capability: |
| | 4.8.8 | replay:1.0 |
| | | |
| with-defaults | 4.8.9 | urn:ietf:params:restconf:capability: |
| | | with-defaults:1.0 |
+----------------+---------+---------------------------------------+
+----------------+---------+---------------------------------------+
| Name | Section | URI |
| | | |
+----------------+---------+---------------------------------------+
| depth | 4.8.2 | urn:ietf:params:restconf:capability: |
| | | depth:1.0 |
| | | |
| fields | 4.8.3 | urn:ietf:params:restconf:capability: |
| | | fields:1.0 |
| | | |
| filter | 4.8.4 | urn:ietf:params:restconf:capability: |
| | | filter:1.0 |
| | | |
| replay | 4.8.7 | urn:ietf:params:restconf:capability: |
| | 4.8.8 | replay:1.0 |
| | | |
| with-defaults | 4.8.9 | urn:ietf:params:restconf:capability: |
| | | with-defaults:1.0 |
+----------------+---------+---------------------------------------+
RESTCONF Query Parameter URIs
RESTCONF查询参数URIs
This URI identifies the "basic-mode" default-handling mode that is used by the server for processing default leafs in requests for data resources. This protocol capability URI MUST be supported by the server and MUST be listed in the "capability" leaf-list defined in Section 9.3.
此URI标识“基本模式”默认处理模式，该模式由服务器用于处理数据资源的默认leaf-in请求。服务器必须支持此协议功能URI，并且必须在第9.3节定义的“功能”叶列表中列出。
+----------+--------------------------------------------------+
| Name | URI |
+----------+--------------------------------------------------+
| defaults | urn:ietf:params:restconf:capability:defaults:1.0 |
+----------+--------------------------------------------------+
+----------+--------------------------------------------------+
| Name | URI |
+----------+--------------------------------------------------+
| defaults | urn:ietf:params:restconf:capability:defaults:1.0 |
+----------+--------------------------------------------------+
RESTCONF "defaults" Capability URI
RESTCONF“默认”功能URI
The URI MUST contain a query parameter named "basic-mode" with one of the values listed below:
URI必须包含一个名为“基本模式”的查询参数，其值如下所示：
+------------+------------------------------------------------------+
| Value | Description |
+------------+------------------------------------------------------+
| report-all | No data nodes are considered default |
| | |
| trim | Values set to the YANG default-stmt value are |
| | default |
| | |
| explicit | Values set by the client are never considered |
| | default |
+------------+------------------------------------------------------+
+------------+------------------------------------------------------+
| Value | Description |
+------------+------------------------------------------------------+
| report-all | No data nodes are considered default |
| | |
| trim | Values set to the YANG default-stmt value are |
| | default |
| | |
| explicit | Values set by the client are never considered |
| | default |
+------------+------------------------------------------------------+
The "basic-mode" definitions are specified in "With-defaults Capability for NETCONF" [RFC6243].
“基本模式”定义在“NETCONF的默认功能”[RFC6243]中指定。
If the "basic-mode" is set to "report-all", then the server MUST adhere to the default-handling behavior defined in Section 2.1 of [RFC6243].
如果“基本模式”设置为“全部报告”，则服务器必须遵守[RFC6243]第2.1节中定义的默认处理行为。
If the "basic-mode" is set to "trim", then the server MUST adhere to the default-handling behavior defined in Section 2.2 of [RFC6243].
如果“基本模式”设置为“修剪”，则服务器必须遵守[RFC6243]第2.2节中定义的默认处理行为。
If the "basic-mode" is set to "explicit", then the server MUST adhere to the default-handling behavior defined in Section 2.3 of [RFC6243].
如果“基本模式”设置为“显式”，则服务器必须遵守[RFC6243]第2.3节中定义的默认处理行为。
Example (split for display purposes only):
示例（仅出于显示目的拆分）：
urn:ietf:params:restconf:capability:defaults:1.0?
basic-mode=explicit
urn:ietf:params:restconf:capability:defaults:1.0?
basic-mode=explicit
This optional container provides access to the event streams supported by the server. The server MAY omit this container if no event streams are supported.
此可选容器提供对服务器支持的事件流的访问。如果不支持任何事件流，服务器可能会忽略此容器。
The server will populate this container with a "stream" list entry for each stream type it supports. Each stream contains a leaf called "events", which contains a URI that represents an event stream resource.
服务器将为此容器填充它支持的每种流类型的“流”列表条目。每个流都包含一个称为“事件”的叶，其中包含一个表示事件流资源的URI。
Stream resources are defined in Section 3.8. Notifications are defined in Section 6.
第3.8节对河流资源进行了定义。通知的定义见第6节。
The "ietf-restconf-monitoring" module defines monitoring information for the RESTCONF protocol.
“ietf restconf监控”模块定义restconf协议的监控信息。
The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] are used by this module for some type definitions.
[RFC6991]中的“ietf yang类型”和“ietf inet类型”模块由该模块用于某些类型定义。
<CODE BEGINS>
<代码开始>
file "ietf-restconf-monitoring@2017-01-26.yang"
文件“ietf restconf”-monitoring@2017-01-26.杨”
module ietf-restconf-monitoring {
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring";
prefix "rcmon";
module ietf-restconf-monitoring {
namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring";
prefix "rcmon";
import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; }
import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; }
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 monitoring information for the RESTCONF protocol.
description“此模块包含RESTCONF协议的监视信息。
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 8040; see the RFC itself for full legal notices.";
该模块的此版本是RFC 8040的一部分；有关完整的法律通知，请参见RFC本身。“；
revision 2017-01-26 {
description
"Initial revision.";
reference
"RFC 8040: RESTCONF Protocol.";
}
revision 2017-01-26 {
description
"Initial revision.";
reference
"RFC 8040: RESTCONF Protocol.";
}
container restconf-state {
config false;
description
"Contains RESTCONF protocol monitoring information.";
container restconf-state {
config false;
description
"Contains RESTCONF protocol monitoring information.";
container capabilities {
description
"Contains a list of protocol capability URIs.";
container capabilities {
description
"Contains a list of protocol capability URIs.";
leaf-list capability {
type inet:uri;
description
"A RESTCONF protocol capability URI.";
}
}
leaf-list capability {
type inet:uri;
description
"A RESTCONF protocol capability URI.";
}
}
container streams {
description
"Container representing the notification event streams
supported by the server.";
reference
"RFC 5277, Section 3.4, <streams> element.";
container streams {
description
"Container representing the notification event streams
supported by the server.";
reference
"RFC 5277, Section 3.4, <streams> element.";
list stream {
key name;
description
"Each entry describes an event stream supported by
the server.";
list stream {
key name;
description
"Each entry describes an event stream supported by
the server.";
leaf name {
type string;
description
"The stream name.";
reference
"RFC 5277, Section 3.4, <name> element.";
}
leaf name {
type string;
description
"The stream name.";
reference
"RFC 5277, Section 3.4, <name> element.";
}
leaf description {
type string;
description
"Description of stream content.";
reference
"RFC 5277, Section 3.4, <description> element.";
}
leaf description {
type string;
description
"Description of stream content.";
reference
"RFC 5277, Section 3.4, <description> element.";
}
leaf replay-support {
type boolean;
default false;
description
"Indicates if replay buffer is supported for this stream.
If 'true', then the server MUST support the 'start-time'
and 'stop-time' query parameters for this stream.";
reference
"RFC 5277, Section 3.4, <replaySupport> element.";
}
leaf replay-support {
type boolean;
default false;
description
"Indicates if replay buffer is supported for this stream.
If 'true', then the server MUST support the 'start-time'
and 'stop-time' query parameters for this stream.";
reference
"RFC 5277, Section 3.4, <replaySupport> element.";
}
leaf replay-log-creation-time {
when "../replay-support" {
description
"Only present if notification replay is supported.";
}
type yang:date-and-time;
description
"Indicates the time the replay log for this stream
was created.";
reference
"RFC 5277, Section 3.4, <replayLogCreationTime>
element.";
}
leaf replay-log-creation-time {
when "../replay-support" {
description
"Only present if notification replay is supported.";
}
type yang:date-and-time;
description
"Indicates the time the replay log for this stream
was created.";
reference
"RFC 5277, Section 3.4, <replayLogCreationTime>
element.";
}
list access {
key encoding;
min-elements 1;
description
"The server will create an entry in this list for each
encoding format that is supported for this stream.
The media type 'text/event-stream' is expected
for all event streams. This list identifies the
subtypes supported for this stream.";
list access {
key encoding;
min-elements 1;
description
"The server will create an entry in this list for each
encoding format that is supported for this stream.
The media type 'text/event-stream' is expected
for all event streams. This list identifies the
subtypes supported for this stream.";
leaf encoding {
type string;
description
"This is the secondary encoding format within the
'text/event-stream' encoding used by all streams.
The type 'xml' is supported for XML encoding.
The type 'json' is supported for JSON encoding.";
}
leaf encoding {
type string;
description
"This is the secondary encoding format within the
'text/event-stream' encoding used by all streams.
The type 'xml' is supported for XML encoding.
The type 'json' is supported for JSON encoding.";
}
leaf location {
type inet:uri;
mandatory true;
description
"Contains a URL that represents the entry point
for establishing notification delivery via
server-sent events.";
}
}
}
}
}
leaf location {
type inet:uri;
mandatory true;
description
"Contains a URL that represents the entry point
for establishing notification delivery via
server-sent events.";
}
}
}
}
}
}
}
<CODE ENDS>
<代码结束>
The "ietf-yang-library" module defined in [RFC7895] provides information about the YANG modules and submodules used by the RESTCONF server. Implementation is mandatory for RESTCONF servers. All YANG modules and submodules used by the server MUST be identified in the YANG module library.
[RFC7895]中定义的“ietf yang library”模块提供有关RESTCONF服务器使用的yang模块和子模块的信息。RESTCONF服务器必须实现。服务器使用的所有YANG模块和子模块必须在YANG模块库中标识。
This mandatory list contains one entry for each YANG data model module supported by the server. There MUST be an instance of this list for every YANG module that is used by the server.
此强制列表包含服务器支持的每个数据模型模块的一个条目。服务器使用的每个模块都必须有此列表的实例。
The contents of this list are defined in the "module" YANG list statement in [RFC7895].
该列表的内容在[RFC7895]中的“模块”列表语句中定义。
Note that there are no protocol-accessible objects in the "ietf-restconf" module to implement, but it is possible that a server will list the "ietf-restconf" module in the YANG library if it is imported (directly or indirectly) by an implemented module.
请注意，“ietf restconf”模块中没有要实现的协议可访问对象，但如果“ietf restconf”模块由已实现的模块导入（直接或间接），则服务器可能会在库中列出该模块。
This specification registers the "restconf" relation type in the "Link Relation Types" registry defined by [RFC5988]:
本规范在[RFC5988]定义的“链接关系类型”注册表中注册“restconf”关系类型：
Relation Name: restconf
关系名称：restconf
Description: Identifies the root of the RESTCONF API as configured on this HTTP server. The "restconf" relation defines the root of the API defined in RFC 8040. Subsequent revisions of RESTCONF will use alternate relation values to support protocol versioning.
描述：标识此HTTP服务器上配置的RESTCONF API的根。“restconf”关系定义RFC8040中定义的API的根。RESTCONF的后续版本将使用备用关系值来支持协议版本控制。
Reference: RFC 8040
参考：RFC 8040
This document registers two URIs as namespaces in the "IETF XML Registry" [RFC3688]:
本文档在“IETF XML注册表”[RFC3688]中将两个URI注册为名称空间：
URI: urn:ietf:params:xml:ns:yang:ietf-restconf Registrant Contact: The IESG. XML: N/A; the requested URI is an XML namespace.
URI:urn:ietf:params:xml:ns:yang:ietf restconf注册人联系人：IESG。XML：不适用；请求的URI是一个XML命名空间。
URI: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring Registrant Contact: The IESG. XML: N/A; the requested URI is an XML namespace.
URI:urn:ietf:params:xml:ns:yang:ietf-restconf监控注册人联系人：IESG。XML：不适用；请求的URI是一个XML命名空间。
This document registers two YANG modules in the "YANG Module Names" registry [RFC6020]:
本文件在“阳模块名称”注册表[RFC6020]中注册了两个阳模块：
name: ietf-restconf
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf
prefix: rc
reference: RFC 8040
name: ietf-restconf
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf
prefix: rc
reference: RFC 8040
name: ietf-restconf-monitoring
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
prefix: rcmon
reference: RFC 8040
name: ietf-restconf-monitoring
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring
prefix: rcmon
reference: RFC 8040
Type name: application
类型名称：应用程序
Subtype name: yang-data+xml
子类型名称：yang data+xml
Required parameters: None
所需参数：无
Optional parameters: None
可选参数：无
Encoding considerations: 8-bit 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].
编码注意事项：根据[RFC7950]中定义的特定YANG数据节点类型的XML编码规则和规范格式，对每个概念YANG数据节点进行8位编码。
Security considerations: Security considerations related to the generation and consumption of RESTCONF messages are discussed in Section 12 of RFC 8040. 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 8040第12节讨论了与RESTCONF消息的生成和使用相关的安全注意事项。其他安全注意事项特定于特定数据模型的语义。每个YANG模块都需要为该模块中定义的YANG数据指定安全注意事项。
Interoperability considerations: RFC 8040 specifies the format of conforming messages and the interpretation thereof.
互操作性注意事项：RFC 8040规定了一致性消息的格式及其解释。
Published specification: RFC 8040
已发布规范：RFC 8040
Applications that use this media type: Instance document data parsers used within a protocol or automation tool that utilize YANG-defined data structures.
使用此媒体类型的应用程序：在协议或自动化工具中使用的实例文档数据解析器，这些协议或自动化工具利用了已定义的数据结构。
Fragment identifier considerations: Fragment identifiers for this type are not defined. All YANG data nodes are accessible as resources using the path in the request URI.
片段标识符注意事项：未定义此类型的片段标识符。所有数据节点都可以使用请求URI中的路径作为资源访问。
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 8040.
联系人和电子邮件地址了解更多信息：请参阅RFC 8040的作者地址部分。
Intended usage: COMMON
预期用途：普通
Restrictions on usage: N/A
使用限制：不适用
Author: See the Authors' Addresses section of RFC 8040.
作者：参见RFC 8040的作者地址部分。
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-data+json
子类型名称：yang data+json
Required parameters: None
所需参数：无
Optional parameters: None
可选参数：无
Encoding considerations: 8-bit Each conceptual YANG data node is encoded according to [RFC7951]. A metadata annotation is encoded according to [RFC7952].
编码注意事项：根据[RFC7951]对每个数据节点进行8位编码。元数据注释按照[RFC7952]进行编码。
Security considerations: Security considerations related to the generation and consumption of RESTCONF messages are discussed in Section 12 of RFC 8040. 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 8040第12节讨论了与RESTCONF消息的生成和使用相关的安全注意事项。其他安全注意事项特定于特定数据模型的语义。每个YANG模块都需要为该模块中定义的YANG数据指定安全注意事项。
Interoperability considerations: RFC 8040 specifies the format of conforming messages and the interpretation thereof.
互操作性注意事项：RFC 8040规定了一致性消息的格式及其解释。
Published specification: RFC 8040
已发布规范：RFC 8040
Applications that use this media type: Instance document data parsers used within a protocol or automation tool that utilize YANG-defined data structures.
使用此媒体类型的应用程序：在协议或自动化工具中使用的实例文档数据解析器，这些协议或自动化工具利用了已定义的数据结构。
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 8040.
联系人和电子邮件地址了解更多信息：请参阅RFC 8040的作者地址部分。
Intended usage: COMMON
预期用途：普通
Restrictions on usage: N/A
使用限制：不适用
Author: See the Authors' Addresses section of RFC 8040.
作者：参见RFC 8040的作者地址部分。
Change controller: Internet Engineering Task Force (mailto:iesg@ietf.org).
变更控制员：互联网工程任务组（邮寄：iesg@ietf.org).
Provisional registration? (standards tree only): no
临时登记？（仅限标准树）：否
This document defines a registry for RESTCONF capability identifiers. The name of the registry is "RESTCONF Capability URNs". The review policy for this registry is "IETF Review" [RFC5226]. The registry shall record the following for each entry:
本文档为RESTCONF功能标识符定义了一个注册表。注册表的名称是“RESTCONF”和“URNs”。此注册表的审核策略为“IETF审核”[RFC5226]。登记处应记录每个条目的以下内容：
o the name of the RESTCONF capability. By convention, this name begins with the colon (":") character.
o RESTCONF功能的名称。按照惯例，此名称以冒号（“：”）字符开头。
o the URN for the RESTCONF capability.
o RESTCONF功能的URN。
o the reference for the document registering the value.
o 注册该值的文档的引用。
This document registers several capability identifiers in the "RESTCONF Capability URNs" registry:
本文档在“RESTCONF capability URNs”注册表中注册了几个功能标识符：
Index Capability Identifier
---------------------------------------------------------------------
:defaults urn:ietf:params:restconf:capability:defaults:1.0
Index Capability Identifier
---------------------------------------------------------------------
:defaults urn:ietf:params:restconf:capability:defaults:1.0
:depth urn:ietf:params:restconf:capability:depth:1.0
:depth urn:ietf:params:restconf:capability:depth:1.0
:fields urn:ietf:params:restconf:capability:fields:1.0
:fields urn:ietf:params:restconf:capability:fields:1.0
:filter urn:ietf:params:restconf:capability:filter:1.0
:filter urn:ietf:params:restconf:capability:filter:1.0
:replay urn:ietf:params:restconf:capability:replay:1.0
:replay urn:ietf:params:restconf:capability:replay:1.0
:with-defaults urn:ietf:params:restconf:capability:with-defaults:1.0
:with-defaults urn:ietf:params:restconf:capability:with-defaults:1.0
IANA has registered a new URN sub-namespace within the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry defined in [RFC3553].
IANA已在[RFC3553]中定义的“注册协议参数标识符的IETF URN子命名空间”注册表中注册了一个新的URN子命名空间。
Registry Name: restconf
注册表名：restconf
Specification: RFC 8040
规格：RFC8040
Repository: "RESTCONF Capability URNs" registry (Section 11.4)
存储库：“RESTCONF功能URNs”注册表（第11.4节）
Index value: Sub-parameters MUST be specified in UTF-8, using standard URI encoding where necessary.
索引值：必须在UTF-8中指定子参数，必要时使用标准URI编码。
Section 2.1 states that "a RESTCONF server MUST support the TLS protocol [RFC5246]." This language leaves open the possibility that a RESTCONF server might also support future versions of the TLS protocol. Of specific concern, TLS 1.3 [TLS1.3] introduces support for 0-RTT handshakes that can lead to security issues for RESTCONF APIs, as described in Appendix B.1 of the TLS 1.3 document. It is therefore RECOMMENDED that RESTCONF servers do not support 0-RTT at all (not even for idempotent requests) until an update to this RFC guides otherwise.
第2.1节规定“RESTCONF服务器必须支持TLS协议[RFC5246]”。这种语言允许RESTCONF服务器也支持TLS协议的未来版本。值得特别关注的是，TLS 1.3[TLS1.3]引入了对0-RTT握手的支持，这可能导致RESTCONF API的安全问题，如TLS 1.3文档的附录B.1所述。因此，建议RESTCONF服务器完全不支持0-RTT（即使对于幂等请求也不支持），除非对该RFC进行更新。
Section 2.5 recommends authentication based on TLS client certificates but allows the use of any authentication scheme defined in the "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". Implementations need to be aware that the strengths of these methods vary greatly and that some may be considered experimental. Selection of any of these schemes SHOULD be performed after reading the Security Considerations section of the RFC associated with the scheme's registry entry.
第2.5节建议基于TLS客户端证书进行身份验证，但允许使用“超文本传输协议（HTTP）身份验证方案注册表”中定义的任何身份验证方案。实现需要注意，这些方法的优点差别很大，有些可能被认为是实验性的。在阅读RFC中与方案注册表项相关的安全注意事项部分后，应选择这些方案中的任何一个。
The "ietf-restconf-monitoring" YANG module defined in this memo is designed to be accessed via the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The NETCONF access control model [RFC6536] provides the means to restrict access for particular NETCONF users to a preconfigured subset of all available NETCONF protocol operations and content.
本备忘录中定义的“ietf restconf监控”模块旨在通过NETCONF协议[RFC6241]访问。最低的NETCONF层是安全传输层，实现安全传输的强制要求是安全Shell（SSH）[RFC6242]。NETCONF访问控制模型[RFC6536]提供了将特定NETCONF用户的访问限制为所有可用NETCONF协议操作和内容的预配置子集的方法。
The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC5246]. The RESTCONF protocol uses the NETCONF access control model [RFC6536], which provides the means to restrict access for particular RESTCONF users to a preconfigured subset of all available RESTCONF protocol operations and content.
最低的RESTCONF层是HTTPS，实现安全传输的强制层是TLS[RFC5246]。RESTCONF协议使用NETCONF访问控制模型[RFC6536]，该模型提供了将特定RESTCONF用户的访问限制为所有可用RESTCONF协议操作和内容的预配置子集的方法。
This section provides security considerations for the resources defined by the RESTCONF protocol. Security considerations for HTTPS are defined in [RFC7230]. Aside from the "ietf-restconf-monitoring" module (Section 9) and the "ietf-yang-library" module (Section 10), RESTCONF does not specify which YANG modules a server needs to support. Security considerations for the other modules manipulated by RESTCONF can be found in the documents defining those YANG modules.
本节提供RESTCONF协议定义的资源的安全注意事项。[RFC7230]中定义了HTTPS的安全注意事项。除了“ietf restconf监控”模块（第9节）和“ietf yang library”模块（第10节），restconf没有指定服务器需要支持哪些yang模块。RESTCONF操作的其他模块的安全注意事项可以在定义这些模块的文档中找到。
Configuration information is by its very nature sensitive. Its transmission in the clear and without integrity checking leaves devices open to classic eavesdropping and false data injection
配置信息本质上是敏感的。它以清晰且无完整性检查的方式传输，使得设备容易受到经典的窃听和虚假数据注入
attacks. Configuration information often contains passwords, user names, service descriptions, and topological information, all of which are sensitive. There are many patterns of attack that have been observed through operational practice with existing management interfaces. It would be wise for implementers to research them and take them into account when implementing this protocol.
攻击。配置信息通常包含密码、用户名、服务描述和拓扑信息，所有这些信息都是敏感的。通过对现有管理界面的操作实践，可以观察到许多攻击模式。对于实现者来说，研究它们并在实现该协议时考虑它们是明智的。
Different environments may well allow different rights prior to, and then after, authentication. When a RESTCONF operation is not properly authorized, the RESTCONF server MUST return a "401 Unauthorized" status-line. Note that authorization information can be exchanged in the form of configuration information, which is all the more reason to ensure the security of the connection. Note that it is possible for a client to detect configuration changes in data resources it is not authorized to access by monitoring changes in the "ETag" and "Last-Modified" header fields returned by the server for the datastore resource.
在身份验证之前和之后，不同的环境可能允许不同的权限。当RESTCONF操作未正确授权时，RESTCONF服务器必须返回“401 Unauthorized”状态行。请注意，可以以配置信息的形式交换授权信息，这更是确保连接安全的原因。请注意，客户端可以通过监视服务器为数据存储资源返回的“ETag”和“Last Modified”头字段中的更改来检测未授权访问的数据资源中的配置更改。
A RESTCONF server implementation SHOULD attempt to prevent system disruption due to excessive resource consumption required to fulfill edit requests via the POST, PUT, and PATCH methods. On such an implementation, it may be possible to construct an attack that attempts to consume all available memory or other resource types.
RESTCONF服务器实现应尝试防止由于通过POST、PUT和PATCH方法完成编辑请求所需的过度资源消耗而导致系统中断。在这种实现上，可能会构造一种攻击，试图消耗所有可用内存或其他资源类型。
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, November 1996, <http://www.rfc-editor.org/info/rfc2046>.
[RFC2046]Freed，N.和N.Borenstein，“多用途互联网邮件扩展（MIME）第二部分：媒体类型”，RFC 2046，DOI 10.17487/RFC2046，1996年11月<http://www.rfc-editor.org/info/rfc2046>.
[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>.
[RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF URN Sub-namespace for Registered Protocol Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 2003, <http://www.rfc-editor.org/info/rfc3553>.
[RFC3553]Mealling，M.，Masinter，L.，Hardie，T.，和G.Klyne，“注册协议参数的IETF URN子命名空间”，BCP 73，RFC 3553，DOI 10.17487/RFC3553，2003年6月<http://www.rfc-editor.org/info/rfc3553>.
[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>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <http://www.rfc-editor.org/info/rfc3986>.
[RFC3986]Berners Lee，T.，Fielding，R.，和L.Masinter，“统一资源标识符（URI）：通用语法”，STD 66，RFC 3986，DOI 10.17487/RFC3986，2005年1月<http://www.rfc-editor.org/info/rfc3986>.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <http://www.rfc-editor.org/info/rfc5234>.
[RFC5234]Crocker，D.，Ed.，和P.Overell，“语法规范的扩充BNF:ABNF”，STD 68，RFC 5234，DOI 10.17487/RFC5234，2008年1月<http://www.rfc-editor.org/info/rfc5234>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <http://www.rfc-editor.org/info/rfc5246>.
[RFC5246]Dierks，T.和E.Rescorla，“传输层安全（TLS）协议版本1.2”，RFC 5246，DOI 10.17487/RFC5246，2008年8月<http://www.rfc-editor.org/info/rfc5246>.
[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, <http://www.rfc-editor.org/info/rfc5277>.
[RFC5277]Chisholm，S.和H.Trevino，“NETCONF事件通知”，RFC 5277，DOI 10.17487/RFC5277，2008年7月<http://www.rfc-editor.org/info/rfc5277>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, <http://www.rfc-editor.org/info/rfc5280>.
[RFC5280]Cooper，D.，Santesson，S.，Farrell，S.，Boeyen，S.，Housley，R.，和W.Polk，“Internet X.509公钥基础设施证书和证书撤销列表（CRL）配置文件”，RFC 5280，DOI 10.17487/RFC5280，2008年5月<http://www.rfc-editor.org/info/rfc5280>.
[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>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010, <http://www.rfc-editor.org/info/rfc5988>.
[RFC5988]诺丁汉，M.，“网络链接”，RFC 5988，DOI 10.17487/RFC5988，2010年10月<http://www.rfc-editor.org/info/rfc5988>.
[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>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <http://www.rfc-editor.org/info/rfc6242>.
[RFC6242]Wasserman，M.“在安全外壳上使用NETCONF协议（SSH）”，RFC 6242，DOI 10.17487/RFC6242，2011年6月<http://www.rfc-editor.org/info/rfc6242>.
[RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, <http://www.rfc-editor.org/info/rfc6243>.
[RFC6243]Bierman，A.和B.Lengyel，“NETCONF的默认功能”，RFC 6243，DOI 10.17487/RFC6243，2011年6月<http://www.rfc-editor.org/info/rfc6243>.
[RFC6415] Hammer-Lahav, E., Ed., and B. Cook, "Web Host Metadata", RFC 6415, DOI 10.17487/RFC6415, October 2011, <http://www.rfc-editor.org/info/rfc6415>.
[RFC6415]Hammer Lahav，E.Ed.和B.Cook，“网络主机元数据”，RFC 6415，DOI 10.17487/RFC6415，2011年10月<http://www.rfc-editor.org/info/rfc6415>.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10.17487/RFC6536, March 2012, <http://www.rfc-editor.org/info/rfc6536>.
[RFC6536]Bierman，A.和M.Bjorklund，“网络配置协议（NETCONF）访问控制模型”，RFC 6536，DOI 10.17487/RFC6536，2012年3月<http://www.rfc-editor.org/info/rfc6536>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, March 2012, <http://www.rfc-editor.org/info/rfc6570>.
[RFC6570]Gregorio，J.，Fielding，R.，Hadley，M.，Nottingham，M.，和D.Orchard，“URI模板”，RFC 6570，DOI 10.17487/RFC657012年3月<http://www.rfc-editor.org/info/rfc6570>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, <http://www.rfc-editor.org/info/rfc6991>.
[RFC6991]Schoenwaeld，J.，Ed.，“常见杨数据类型”，RFC 6991，DOI 10.17487/RFC69911913年7月<http://www.rfc-editor.org/info/rfc6991>.
[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>.
[RFC7232] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI 10.17487/RFC7232, June 2014, <http://www.rfc-editor.org/info/rfc7232>.
[RFC7232]Fielding，R.，Ed.，和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：条件请求”，RFC 7232，DOI 10.17487/RFC72322014年6月<http://www.rfc-editor.org/info/rfc7232>.
[RFC7235] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 10.17487/RFC7235, June 2014, <http://www.rfc-editor.org/info/rfc7235>.
[RFC7235]Fielding，R.，Ed.，和J.Reschke，Ed.，“超文本传输协议（HTTP/1.1）：认证”，RFC 7235，DOI 10.17487/RFC7235，2014年6月<http://www.rfc-editor.org/info/rfc7235>.
[RFC7320] Nottingham, M., "URI Design and Ownership", BCP 190, RFC 7320, DOI 10.17487/RFC7320, July 2014, <http://www.rfc-editor.org/info/rfc7320>.
[RFC7320]诺丁汉，M.，“URI设计和所有权”，BCP 190，RFC 7320，DOI 10.17487/RFC7320，2014年7月<http://www.rfc-editor.org/info/rfc7320>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, <http://www.rfc-editor.org/info/rfc7525>.
[RFC7525]Sheffer，Y.，Holz，R.，和P.Saint Andre，“安全使用传输层安全性（TLS）和数据报传输层安全性（DTLS）的建议”，BCP 195，RFC 7525，DOI 10.17487/RFC7525，2015年5月<http://www.rfc-editor.org/info/rfc7525>.
[RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the NETCONF Protocol over Transport Layer Security (TLS) with Mutual X.509 Authentication", RFC 7589, DOI 10.17487/RFC7589, June 2015, <http://www.rfc-editor.org/info/rfc7589>.
[RFC7589]Badra，M.，Luchuk，A.，和J.Schoenwaeld，“在传输层安全（TLS）上使用NETCONF协议，并进行相互X.509身份验证”，RFC 7589，DOI 10.17487/RFC7589，2015年6月<http://www.rfc-editor.org/info/rfc7589>.
[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, <http://www.rfc-editor.org/info/rfc7895>.
[RFC7895]Bierman，A.，Bjorklund，M.，和K.Watsen，“阳模块库”，RFC 7895，DOI 10.17487/RFC78952016年6月<http://www.rfc-editor.org/info/rfc7895>.
[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>.
[W3C.REC-eventsource-20150203] Hickson, I., "Server-Sent Events", World Wide Web Consortium Recommendation REC-eventsource-20150203, February 2015, <http://www.w3.org/TR/2015/REC-eventsource-20150203>.
[W3C.REC-eventsource-20150203]希克森，I.，“服务器发送的事件”，万维网联盟建议REC-eventsource-20150203，2015年2月<http://www.w3.org/TR/2015/REC-eventsource-20150203>.
[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>.
[XPath] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>.
[XPath]Clark，J.和S.DeRose，“XML路径语言（XPath）1.0版”，万维网联盟建议REC-XPath-19991116，1999年11月<http://www.w3.org/TR/1999/REC-xpath-19991116>.
[REST-Dissertation] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", 2000.
[REST论文]菲尔丁，R.，“体系结构风格和基于网络的软件体系结构的设计”，2000年。
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/RFC2818, May 2000, <http://www.rfc-editor.org/info/rfc2818>.
[RFC2818]Rescorla，E.，“TLS上的HTTP”，RFC 2818，DOI 10.17487/RFC2818，2000年5月<http://www.rfc-editor.org/info/rfc2818>.
[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>.
[TLS1.3] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", Work in Progress, draft-ietf-tls-tls13-18, October 2016.
[TLS1.3]Rescorla，E.，“传输层安全（TLS）协议版本1.3”，正在进行的工作，草案-ietf-TLS-tls13-18，2016年10月。
[YANG-Patch] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch Media Type", Work in Progress, draft-ietf-netconf-yang-patch-14, November 2016.
[YANG Patch]Bierman，A.，Bjorklund，M.，和K.Watsen，“YANG Patch媒体类型”，正在进行的工作，草稿-ietf-netconf-YANG-Patch-142016年11月。
The example YANG module used in this document represents a simple media jukebox interface.
本文档中使用的示例模块表示一个简单的媒体自动存储塔接口。
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
module example-jukebox {
模块示例自动存储塔{
namespace "http://example.com/ns/example-jukebox";
prefix "jbox";
namespace "http://example.com/ns/example-jukebox";
prefix "jbox";
organization "Example, Inc.";
contact "support at example.com";
description "Example Jukebox Data Model Module.";
revision "2016-08-15" {
description "Initial version.";
reference "example.com document 1-4673.";
}
organization "Example, Inc.";
contact "support at example.com";
description "Example Jukebox Data Model Module.";
revision "2016-08-15" {
description "Initial version.";
reference "example.com document 1-4673.";
}
identity genre {
description
"Base for all genre types.";
}
identity genre {
description
"Base for all genre types.";
}
// abbreviated list of genre classifications
identity alternative {
base genre;
description
"Alternative music.";
}
identity blues {
base genre;
description
"Blues music.";
}
identity country {
base genre;
description
"Country music.";
}
identity jazz {
base genre;
description
"Jazz music.";
}
identity pop {
base genre;
description
"Pop music.";
}
// abbreviated list of genre classifications
identity alternative {
base genre;
description
"Alternative music.";
}
identity blues {
base genre;
description
"Blues music.";
}
identity country {
base genre;
description
"Country music.";
}
identity jazz {
base genre;
description
"Jazz music.";
}
identity pop {
base genre;
description
"Pop music.";
}
identity rock {
base genre;
description
"Rock music.";
}
identity rock {
base genre;
description
"Rock music.";
}
container jukebox {
presence
"An empty container indicates that the jukebox
service is available.";
container jukebox {
presence
"An empty container indicates that the jukebox
service is available.";
description "Represents a 'jukebox' resource, with a library, playlists, and a 'play' operation.";
description“表示具有库、播放列表和“播放”操作的“自动存储塔”资源。”；
container library {
容器库{
description "Represents the 'jukebox' library resource.";
description“表示“自动存储塔”库资源。”；
list artist {
key name;
description
"Represents one 'artist' resource within the
'jukebox' library resource.";
list artist {
key name;
description
"Represents one 'artist' resource within the
'jukebox' library resource.";
leaf name {
type string {
length "1 .. max";
}
description
"The name of the artist.";
}
leaf name {
type string {
length "1 .. max";
}
description
"The name of the artist.";
}
list album {
key name;
description
"Represents one 'album' resource within one
'artist' resource, within the jukebox library.";
list album {
key name;
description
"Represents one 'album' resource within one
'artist' resource, within the jukebox library.";
leaf name {
type string {
length "1 .. max";
}
description
"The name of the album.";
}
leaf name {
type string {
length "1 .. max";
}
description
"The name of the album.";
}
leaf genre {
type identityref { base genre; }
description
"The genre identifying the type of music on
the album.";
}
leaf genre {
type identityref { base genre; }
description
"The genre identifying the type of music on
the album.";
}
leaf year {
type uint16 {
range "1900 .. max";
}
description
"The year the album was released.";
}
leaf year {
type uint16 {
range "1900 .. max";
}
description
"The year the album was released.";
}
container admin {
description
"Administrative information for the album.";
container admin {
description
"Administrative information for the album.";
leaf label {
type string;
description
"The label that released the album.";
}
leaf catalogue-number {
type string;
description
"The album's catalogue number.";
}
}
leaf label {
type string;
description
"The label that released the album.";
}
leaf catalogue-number {
type string;
description
"The album's catalogue number.";
}
}
list song {
key name;
description
"Represents one 'song' resource within one
'album' resource, within the jukebox library.";
list song {
key name;
description
"Represents one 'song' resource within one
'album' resource, within the jukebox library.";
leaf name {
type string {
length "1 .. max";
}
description
"The name of the song.";
}
leaf name {
type string {
length "1 .. max";
}
description
"The name of the song.";
}
leaf location {
type string;
mandatory true;
description
"The file location string of the
media file for the song.";
}
leaf format {
type string;
description
"An identifier string for the media type
for the file associated with the
'location' leaf for this entry.";
}
leaf length {
type uint32;
units "seconds";
description
"The duration of this song in seconds.";
}
} // end list 'song'
} // end list 'album'
} // end list 'artist'
leaf location {
type string;
mandatory true;
description
"The file location string of the
media file for the song.";
}
leaf format {
type string;
description
"An identifier string for the media type
for the file associated with the
'location' leaf for this entry.";
}
leaf length {
type uint32;
units "seconds";
description
"The duration of this song in seconds.";
}
} // end list 'song'
} // end list 'album'
} // end list 'artist'
leaf artist-count {
type uint32;
units "artists";
config false;
description
"Number of artists in the library.";
}
leaf album-count {
type uint32;
units "albums";
config false;
description
"Number of albums in the library.";
}
leaf song-count {
type uint32;
units "songs";
config false;
description
"Number of songs in the library.";
}
} // end library
leaf artist-count {
type uint32;
units "artists";
config false;
description
"Number of artists in the library.";
}
leaf album-count {
type uint32;
units "albums";
config false;
description
"Number of albums in the library.";
}
leaf song-count {
type uint32;
units "songs";
config false;
description
"Number of songs in the library.";
}
} // end library
list playlist {
key name;
description
"Example configuration data resource.";
list playlist {
key name;
description
"Example configuration data resource.";
leaf name {
type string;
description
"The name of the playlist.";
}
leaf description {
type string;
description
"A comment describing the playlist.";
}
list song {
key index;
ordered-by user;
leaf name {
type string;
description
"The name of the playlist.";
}
leaf description {
type string;
description
"A comment describing the playlist.";
}
list song {
key index;
ordered-by user;
description "Example nested configuration data resource.";
说明“示例嵌套配置数据资源。”；
leaf index { // not really needed
type uint32;
description
"An arbitrary integer index for this playlist song.";
}
leaf id {
type instance-identifier;
mandatory true;
description
"Song identifier. Must identify an instance of
/jukebox/library/artist/album/song/name.";
}
}
}
leaf index { // not really needed
type uint32;
description
"An arbitrary integer index for this playlist song.";
}
leaf id {
type instance-identifier;
mandatory true;
description
"Song identifier. Must identify an instance of
/jukebox/library/artist/album/song/name.";
}
}
}
container player {
description
"Represents the jukebox player resource.";
container player {
description
"Represents the jukebox player resource.";
leaf gap {
type decimal64 {
fraction-digits 1;
range "0.0 .. 2.0";
}
units "tenths of seconds";
description
"Time gap between each song.";
}
}
}
leaf gap {
type decimal64 {
fraction-digits 1;
range "0.0 .. 2.0";
}
units "tenths of seconds";
description
"Time gap between each song.";
}
}
}
rpc play {
description
"Control function for the jukebox player.";
input {
leaf playlist {
type string;
mandatory true;
description
"The playlist name.";
}
leaf song-number {
type uint32;
mandatory true;
description
"Song number in playlist to play.";
}
}
}
}
rpc play {
description
"Control function for the jukebox player.";
input {
leaf playlist {
type string;
mandatory true;
description
"The playlist name.";
}
leaf song-number {
type uint32;
mandatory true;
description
"Song number in playlist to play.";
}
}
}
}
The examples within this document use the normative YANG module "ietf-restconf" as defined in Section 8 and the non-normative example YANG module "example-jukebox" as defined in Appendix A.1.
本文件中的示例使用第8节中定义的规范性YANG模块“ietf restconf”，以及附录A.1中定义的非规范性示例性YANG模块“示例光盘机”。
This section shows some typical RESTCONF message exchanges.
本节显示一些典型的RESTCONF消息交换。
The client starts by retrieving the RESTCONF root resource:
客户端首先检索RESTCONF根资源：
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>
The client may then retrieve the top-level API resource, using the root resource "/restconf".
然后，客户机可以使用根资源“/restconf”检索顶级API资源。
GET /restconf HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"ietf-restconf:restconf" : {
"data" : {},
"operations" : {},
"yang-library-version" : "2016-06-21"
}
}
{
"ietf-restconf:restconf" : {
"data" : {},
"operations" : {},
"yang-library-version" : "2016-06-21"
}
}
To request that the response content be encoded in XML, the "Accept" header can be used, as in this example request:
要请求将响应内容编码为XML，可以使用“Accept”头，如本请求示例中所示：
GET /restconf HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server will return the same conceptual data either way, which might be as follows:
服务器将以任何方式返回相同的概念数据，可能如下所示：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+xml
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<data/>
<operations/>
<yang-library-version>2016-06-21</yang-library-version>
</restconf>
<restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<data/>
<operations/>
<yang-library-version>2016-06-21</yang-library-version>
</restconf>
It is possible that the YANG library module will change over time. The client can retrieve the revision date of the "ietf-yang-library" module supported by the server from the API resource, as described in the previous section.
YANG library模块可能会随时间变化。客户端可以从API资源中检索服务器支持的“ietf yang library”模块的修订日期，如前一节所述。
In this example, the client is retrieving the module information from the server in JSON format:
在本例中，客户端以JSON格式从服务器检索模块信息：
GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 14:00:14 GMT
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 14:00:14 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-library:modules-state" : {
"module-set-id" : "5479120c17a619545ea6aff7aa19838b036ebbd7",
"module" : [
{
"name" : "foo",
"revision" : "2012-01-02",
"schema" : "https://example.com/modules/foo/2012-01-02",
"namespace" : "http://example.com/ns/foo",
"feature" : [ "feature1", "feature2" ],
"deviation" : [
{
"name" : "foo-dev",
"revision" : "2012-02-16"
}
],
"conformance-type" : "implement"
},
{
"name" : "ietf-yang-library",
"revision" : "2016-06-21",
"schema" : "https://example.com/modules/\
ietf-yang-library/2016-06-21",
"namespace" :
"urn:ietf:params:xml:ns:yang:ietf-yang-library",
"conformance-type" : "implement"
},
{
"name" : "foo-types",
"revision" : "2012-01-05",
"schema" :
"https://example.com/modules/foo-types/2012-01-05",
"namespace" : "http://example.com/ns/foo-types",
"conformance-type" : "import"
},
{
"ietf-yang-library:modules-state" : {
"module-set-id" : "5479120c17a619545ea6aff7aa19838b036ebbd7",
"module" : [
{
"name" : "foo",
"revision" : "2012-01-02",
"schema" : "https://example.com/modules/foo/2012-01-02",
"namespace" : "http://example.com/ns/foo",
"feature" : [ "feature1", "feature2" ],
"deviation" : [
{
"name" : "foo-dev",
"revision" : "2012-02-16"
}
],
"conformance-type" : "implement"
},
{
"name" : "ietf-yang-library",
"revision" : "2016-06-21",
"schema" : "https://example.com/modules/\
ietf-yang-library/2016-06-21",
"namespace" :
"urn:ietf:params:xml:ns:yang:ietf-yang-library",
"conformance-type" : "implement"
},
{
"name" : "foo-types",
"revision" : "2012-01-05",
"schema" :
"https://example.com/modules/foo-types/2012-01-05",
"namespace" : "http://example.com/ns/foo-types",
"conformance-type" : "import"
},
{
"name" : "bar",
"revision" : "2012-11-05",
"schema" : "https://example.com/modules/bar/2012-11-05",
"namespace" : "http://example.com/ns/bar",
"feature" : [ "bar-ext" ],
"conformance-type" : "implement",
"submodule" : [
{
"name" : "bar-submod1",
"revision" : "2012-11-05",
"schema" :
"https://example.com/modules/bar-submod1/2012-11-05"
},
{
"name" : "bar-submod2",
"revision" : "2012-11-05",
"schema" :
"https://example.com/modules/bar-submod2/2012-11-05"
}
]
}
]
}
}
{
"name" : "bar",
"revision" : "2012-11-05",
"schema" : "https://example.com/modules/bar/2012-11-05",
"namespace" : "http://example.com/ns/bar",
"feature" : [ "bar-ext" ],
"conformance-type" : "implement",
"submodule" : [
{
"name" : "bar-submod1",
"revision" : "2012-11-05",
"schema" :
"https://example.com/modules/bar-submod1/2012-11-05"
},
{
"name" : "bar-submod2",
"revision" : "2012-11-05",
"schema" :
"https://example.com/modules/bar-submod2/2012-11-05"
}
]
}
]
}
}
In this example, the client is retrieving the capability information from the server in XML format, and the server supports all of the RESTCONF query parameters, plus one vendor parameter:
在本例中，客户端以XML格式从服务器检索功能信息，服务器支持所有RESTCONF查询参数，外加一个供应商参数：
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
capabilities HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
GET /restconf/data/ietf-restconf-monitoring:restconf-state/\
capabilities HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
Content-Type: application/yang-data+xml
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
Content-Type: application/yang-data+xml
<capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capability>\
urn:ietf:params:restconf:capability:defaults:1.0?\
basic-mode=explicit\
</capability>
<capability>\
urn:ietf:params:restconf:capability:with-defaults:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:depth:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:fields:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:filter:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:start-time:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:stop-time:1.0\
</capability>
<capability>\
http://example.com/capabilities/myparam\
</capability>
</capabilities>
<capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capability>\
urn:ietf:params:restconf:capability:defaults:1.0?\
basic-mode=explicit\
</capability>
<capability>\
urn:ietf:params:restconf:capability:with-defaults:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:depth:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:fields:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:filter:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:start-time:1.0\
</capability>
<capability>\
urn:ietf:params:restconf:capability:stop-time:1.0\
</capability>
<capability>\
http://example.com/capabilities/myparam\
</capability>
</capabilities>
To create a new "artist" resource within the "library" resource, the client might send the following request:
要在“库”资源中创建新的“艺术家”资源，客户端可能会发送以下请求：
POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:artist" : [
{
"name" : "Foo Fighters"
}
]
}
{
"example-jukebox:artist" : [
{
"name" : "Foo Fighters"
}
]
}
If the resource is created, the server might respond as follows:
如果创建了资源，服务器可能会做出如下响应：
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/library/artist=Foo%20Fighters
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b3830f23a4c"
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/library/artist=Foo%20Fighters
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b3830f23a4c"
To create a new "album" resource for this artist within the "jukebox" resource, the client might send the following request:
要在“自动存储塔”资源中为此艺术家创建新的“相册”资源，客户端可能会发送以下请求：
POST /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
POST /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<album xmlns="http://example.com/ns/example-jukebox">
<name>Wasting Light</name>
<year>2011</year>
</album>
<album xmlns="http://example.com/ns/example-jukebox">
<name>Wasting Light</name>
<year>2011</year>
</album>
If the resource is created, the server might respond as follows:
如果创建了资源，服务器可能会做出如下响应：
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/library/artist=Foo%20Fighters/\
album=Wasting%20Light
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b8389233a4c"
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/library/artist=Foo%20Fighters/\
album=Wasting%20Light
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
ETag: "b8389233a4c"
In this example, the server just supports the datastore last-changed timestamp. Assume that the client has cached the "Last-Modified" header from the response to the previous request. This value is used as in the "If-Unmodified-Since" header in the following request to patch an "album" list entry with a key value of "Wasting Light". Only the "genre" field is being updated.
在本例中，服务器仅支持数据存储上次更改的时间戳。假设客户端缓存了来自对上一个请求的响应的“Last Modified”头。此值与以下请求中的“If Unmodified Since”头中的值相同，以将“album”列表条目修补为键值“wasing Light”。只有“流派”字段正在更新。
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light/\
genre HTTP/1.1
Host: example.com
If-Unmodified-Since: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light/\
genre HTTP/1.1
Host: example.com
If-Unmodified-Since: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{ "example-jukebox:genre" : "example-jukebox:alternative" }
{ "example-jukebox:genre" : "example-jukebox:alternative" }
In this example, the datastore resource has changed since the time specified in the "If-Unmodified-Since" header. The server might respond as follows:
在本例中，数据存储资源自“If Unmodified since”标头中指定的时间起已更改。服务器可能会做出如下响应：
HTTP/1.1 412 Precondition Failed
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 19:41:00 GMT
ETag: "b34aed893a4c"
HTTP/1.1 412 Precondition Failed
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 19:41:00 GMT
ETag: "b34aed893a4c"
In this example, assume that there is a top-level data resource named "system" from the example-system module, and this container has a child leaf called "enable-jukebox-streaming":
在此示例中，假设示例系统模块中有一个名为“system”的顶级数据资源，并且此容器有一个子叶，名为“enable jukebox streaming”：
container system {
leaf enable-jukebox-streaming {
type boolean;
}
}
container system {
leaf enable-jukebox-streaming {
type boolean;
}
}
In this example, PATCH is used by the client to modify two top-level resources at once, in order to enable jukebox streaming and add an "album" sub-resource to each of two "artist" resources:
在本例中，客户端使用补丁一次修改两个顶级资源，以便启用自动存储塔流，并向两个“艺术家”资源中的每一个添加“唱片集”子资源：
PATCH /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
PATCH /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<system xmlns="http://example.com/ns/example-system">
<enable-jukebox-streaming>true</enable-jukebox-streaming>
</system>
<jukebox xmlns="http://example.com/ns/example-jukebox">
<library>
<artist>
<name>Foo Fighters</name>
<album>
<name>One by One</name>
<year>2012</year>
</album>
</artist>
<artist>
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>Tender Prey</name>
<year>1988</year>
</album>
</artist>
</library>
</jukebox>
</data>
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<system xmlns="http://example.com/ns/example-system">
<enable-jukebox-streaming>true</enable-jukebox-streaming>
</system>
<jukebox xmlns="http://example.com/ns/example-jukebox">
<library>
<artist>
<name>Foo Fighters</name>
<album>
<name>One by One</name>
<year>2012</year>
</album>
</artist>
<artist>
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>Tender Prey</name>
<year>1988</year>
</album>
</artist>
</library>
</jukebox>
</data>
In this example, the entire configuration datastore contents are being replaced. Any child nodes not present in the <data> element but present in the server will be deleted.
在本例中，将替换整个配置数据存储内容。将删除<data>元素中不存在但服务器中存在的所有子节点。
PUT /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
PUT /restconf/data HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<jukebox xmlns="http://example.com/ns/example-jukebox">
<library>
<artist>
<name>Foo Fighters</name>
<album>
<name>One by One</name>
<year>2012</year>
</album>
</artist>
<artist>
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>Tender Prey</name>
<year>1988</year>
</album>
</artist>
</library>
</jukebox>
</data>
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<jukebox xmlns="http://example.com/ns/example-jukebox">
<library>
<artist>
<name>Foo Fighters</name>
<album>
<name>One by One</name>
<year>2012</year>
</album>
</artist>
<artist>
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>Tender Prey</name>
<year>1988</year>
</album>
</artist>
</library>
</jukebox>
</data>
In this example, the client modifies one data node by adding an "album" sub-resource by sending a PATCH for the data resource:
在此示例中，客户端通过发送数据资源的修补程序添加“相册”子资源来修改一个数据节点：
PATCH /restconf/data/example-jukebox:jukebox/library/\
artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
PATCH /restconf/data/example-jukebox:jukebox/library/\
artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1
Host: example.com
Content-Type: application/yang-data+xml
<artist xmlns="http://example.com/ns/example-jukebox">
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>The Good Son</name>
<year>1990</year>
</album>
</artist>
<artist xmlns="http://example.com/ns/example-jukebox">
<name>Nick Cave and the Bad Seeds</name>
<album>
<name>The Good Son</name>
<year>1990</year>
</album>
</artist>
The "content" parameter is used to select the types of data child resources (configuration and/or non-configuration) that are returned by the server for a GET method request.
“content”参数用于选择服务器为GET方法请求返回的数据子资源类型（配置和/或非配置）。
In this example, a simple YANG list is used that has configuration and non-configuration child resources.
在本例中，使用了一个简单的YANG列表，其中包含配置和非配置子资源。
container events {
list event {
key name;
leaf name { type string; }
leaf description { type string; }
leaf event-count {
type uint32;
config false;
}
}
}
container events {
list event {
key name;
leaf name { type string; }
leaf description { type string; }
leaf event-count {
type uint32;
config false;
}
}
}
Example 1: content=all
示例1：内容=全部
To retrieve all of the child resources, the "content" parameter is set to "all", or omitted, since this is the default value. The client might send the following:
要检索所有子资源，“content”参数设置为“all”，或省略，因为这是默认值。客户端可能会发送以下内容：
GET /restconf/data/example-events:events?\
content=all HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example-events:events?\
content=all HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"description" : "Interface up notification count",
"event-count" : 42
},
{
"name" : "interface-down",
"description" : "Interface down notification count",
"event-count" : 4
}
]
}
}
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"description" : "Interface up notification count",
"event-count" : 42
},
{
"name" : "interface-down",
"description" : "Interface down notification count",
"event-count" : 4
}
]
}
}
Example 2: content=config
示例2:content=config
To retrieve only the configuration child resources, the "content" parameter is set to "config". Note that the "ETag" and "Last-Modified" headers are only returned if the "content" parameter value is "config".
要仅检索配置子资源，“content”参数设置为“config”。请注意，“ETag”和“Last Modified”标题仅在“content”参数值为“config”时返回。
GET /restconf/data/example-events:events?\
content=config HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example-events:events?\
content=config HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 16:45:20 GMT
ETag: "eeeada438af"
Cache-Control: no-cache
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 16:45:20 GMT
ETag: "eeeada438af"
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"description" : "Interface up notification count"
},
{
"name" : "interface-down",
"description" : "Interface down notification count"
}
]
}
}
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"description" : "Interface up notification count"
},
{
"name" : "interface-down",
"description" : "Interface down notification count"
}
]
}
}
Example 3: content=nonconfig
例3:content=unconfig
To retrieve only the non-configuration child resources, the "content" parameter is set to "nonconfig". Note that configuration ancestors (if any) and list key leafs (if any) are also returned. The client might send the following:
要仅检索非配置子资源，“content”参数设置为“nonconfig”。请注意，还会返回配置祖先（如果有）和列表键叶（如果有）。客户端可能会发送以下内容：
GET /restconf/data/example-events:events?\
content=nonconfig HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example-events:events?\
content=nonconfig HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"event-count" : 42
},
{
"name" : "interface-down",
"event-count" : 4
}
]
}
}
{
"example-events:events" : {
"event" : [
{
"name" : "interface-up",
"event-count" : 42
},
{
"name" : "interface-down",
"event-count" : 4
}
]
}
}
The "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request.
“depth”参数用于限制服务器为GET方法请求返回的子资源的级别数。
The "depth" parameter starts counting levels at the level of the target resource that is specified, so that a depth level of "1" includes just the target resource level itself. A depth level of "2" includes the target resource level and its child nodes.
“depth”参数开始计算指定的目标资源级别的级别，因此“1”的深度级别仅包括目标资源级别本身。深度级别“2”包括目标资源级别及其子节点。
This example shows how different values of the "depth" parameter would affect the reply content for the retrieval of the top-level "jukebox" data resource.
此示例显示“depth”参数的不同值如何影响顶级“jukebox”数据资源检索的回复内容。
Example 1: depth=unbounded
示例1：深度=无界
To retrieve all of the child resources, the "depth" parameter is not present or is set to the default value "unbounded".
要检索所有子资源，“depth”参数不存在或设置为默认值“unbounded”。
GET /restconf/data/example-jukebox:jukebox?\
depth=unbounded HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example-jukebox:jukebox?\
depth=unbounded HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-jukebox:jukebox" : {
"library" : {
"artist" : [
{
"name" : "Foo Fighters",
"album" : [
{
"name" : "Wasting Light",
"genre" : "example-jukebox:alternative",
"year" : 2011,
"song" : [
{
"name" : "Wasting Light",
"location" :
"/media/foo/a7/wasting-light.mp3",
"format" : "MP3",
"length" : 286
},
{
"example-jukebox:jukebox" : {
"library" : {
"artist" : [
{
"name" : "Foo Fighters",
"album" : [
{
"name" : "Wasting Light",
"genre" : "example-jukebox:alternative",
"year" : 2011,
"song" : [
{
"name" : "Wasting Light",
"location" :
"/media/foo/a7/wasting-light.mp3",
"format" : "MP3",
"length" : 286
},
{
"name" : "Rope",
"location" : "/media/foo/a7/rope.mp3",
"format" : "MP3",
"length" : 259
}
]
}
]
}
]
},
"playlist" : [
{
"name" : "Foo-One",
"description" : "example playlist 1",
"song" : [
{
"index" : 1,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Rope']"
},
{
"index" : 2,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
],
"player" : {
"gap" : 0.5
}
}
}
{
"name" : "Rope",
"location" : "/media/foo/a7/rope.mp3",
"format" : "MP3",
"length" : 259
}
]
}
]
}
]
},
"playlist" : [
{
"name" : "Foo-One",
"description" : "example playlist 1",
"song" : [
{
"index" : 1,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Rope']"
},
{
"index" : 2,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
],
"player" : {
"gap" : 0.5
}
}
}
Example 2: depth=1
示例2：深度=1
To determine if one or more resource instances exist for a given target resource, the value "1" is used.
要确定给定目标资源是否存在一个或多个资源实例，请使用值“1”。
GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example-jukebox:jukebox?depth=1 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-jukebox:jukebox" : {}
}
{
"example-jukebox:jukebox" : {}
}
Example 3: depth=3
例3：深度=3
To limit the depth level to the target resource plus two child resource layers, the value "3" is used.
要将深度级别限制为目标资源加上两个子资源层，请使用值“3”。
GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example-jukebox:jukebox?depth=3 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Content-Type: application/yang-data+json
{
"example-jukebox:jukebox" : {
"library" : {
"artist" : {}
},
"playlist" : [
{
"name" : "Foo-One",
"description" : "example playlist 1",
"song" : {}
}
],
"player" : {
"gap" : 0.5
}
}
}
{
"example-jukebox:jukebox" : {
"library" : {
"artist" : {}
},
"playlist" : [
{
"name" : "Foo-One",
"description" : "example playlist 1",
"song" : {}
}
],
"player" : {
"gap" : 0.5
}
}
}
In this example, the client is retrieving the datastore resource in JSON format, but retrieving only the "modules-state/module" list, and only the "name" and "revision" nodes from each list entry. Note that the top node returned by the server matches the target resource node (which is "data" in this example). The "module-set-id" leaf is not returned because it is not selected in the fields expression.
在本例中，客户端正在检索JSON格式的数据存储资源，但仅检索“模块状态/模块”列表，并且仅从每个列表条目中检索“名称”和“修订”节点。请注意，服务器返回的顶部节点与目标资源节点（在本例中为“数据”）匹配。“模块集id”叶不会返回，因为未在字段表达式中选择它。
GET /restconf/data?fields=ietf-yang-library:modules-state/\
module(name;revision) HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data?fields=ietf-yang-library:modules-state/\
module(name;revision) HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"ietf-restconf:data" : {
"ietf-yang-library:modules-state" : {
"module" : [
{
"name" : "example-jukebox",
"revision" : "2016-08-15"
},
{
"name" : "ietf-inet-types",
"revision" : "2013-07-15"
},
{
"name" : "ietf-restconf-monitoring",
"revision" : "2017-01-26"
},
{
"name" : "ietf-yang-library",
"revision" : "2016-06-21"
},
{
"name" : "ietf-yang-types",
"revision" : "2013-07-15"
}
]
}
}
}
{
"ietf-restconf:data" : {
"ietf-yang-library:modules-state" : {
"module" : [
{
"name" : "example-jukebox",
"revision" : "2016-08-15"
},
{
"name" : "ietf-inet-types",
"revision" : "2013-07-15"
},
{
"name" : "ietf-restconf-monitoring",
"revision" : "2017-01-26"
},
{
"name" : "ietf-yang-library",
"revision" : "2016-06-21"
},
{
"name" : "ietf-yang-types",
"revision" : "2013-07-15"
}
]
}
}
}
In this example, a new first song entry in the "Foo-One" playlist is being created.
在此示例中，正在创建“Foo One”播放列表中的新首歌曲条目。
Request from client:
客户要求：
POST /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One?insert=first HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
POST /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One?insert=first HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:song" : [
{
"index" : 1,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Rope']"
}
]
}
{
"example-jukebox:song" : [
{
"index" : 1,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Rope']"
}
]
}
Response from server:
来自服务器的响应：
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=1
ETag: "eeeada438af"
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=1
ETag: "eeeada438af"
In this example, the client is inserting a new song entry in the "Foo-One" playlist after the first song.
在此示例中，客户端在第一首歌曲之后的“Foo One”播放列表中插入新歌曲条目。
Request from client:
客户要求：
POST /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One?insert=after&point=\
%2Fexample-jukebox%3Ajukebox\
%2Fplaylist%3DFoo-One%2Fsong%3D1 HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
POST /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One?insert=after&point=\
%2Fexample-jukebox%3Ajukebox\
%2Fplaylist%3DFoo-One%2Fsong%3D1 HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json
{
"example-jukebox:song" : [
{
"index" : 2,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
{
"example-jukebox:song" : [
{
"index" : 2,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
Response from server:
来自服务器的响应：
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=2
ETag: "abcada438af"
HTTP/1.1 201 Created
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Location: https://example.com/restconf/data/\
example-jukebox:jukebox/playlist=Foo-One/song=2
ETag: "abcada438af"
The following URIs show some examples of notification filter specifications:
以下URI显示了通知筛选器规范的一些示例：
// filter = /event/event-class='fault'
GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'
// filter = /event/event-class='fault'
GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'
// filter = /event/severity<=4
GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4
// filter = /event/severity<=4
GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4
// filter = /linkUp|/linkDown
GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown
// filter = /linkUp|/linkDown
GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown
// filter = /*/reporting-entity/card!='Ethernet0'
GET /streams/NETCONF?\
filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'
// filter = /*/reporting-entity/card!='Ethernet0'
GET /streams/NETCONF?\
filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'
// filter = /*/email-addr[contains(.,'company.com')]
GET /streams/critical-syslog?\
filter=%2F*%2Femail-addr[contains(.%2C'company.com')]
// filter = /*/email-addr[contains(.,'company.com')]
GET /streams/critical-syslog?\
filter=%2F*%2Femail-addr[contains(.%2C'company.com')]
// Note: The module name is used as the prefix.
// filter = (/example-mod:event1/name='joe' and
// /example-mod:event1/status='online')
GET /streams/NETCONF?\
filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and\
%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')
// Note: The module name is used as the prefix.
// filter = (/example-mod:event1/name='joe' and
// /example-mod:event1/status='online')
GET /streams/NETCONF?\
filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and\
%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')
// To get notifications from just two modules (e.g., m1 + m2)
// filter=(/m1:* or /m2:*)
GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*)
// To get notifications from just two modules (e.g., m1 + m2)
// filter=(/m1:* or /m2:*)
GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*)
The following URI shows an example of the "start-time" query parameter:
以下URI显示了“开始时间”查询参数的示例：
// start-time = 2014-10-25T10:02:00Z
GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z
// start-time = 2014-10-25T10:02:00Z
GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z
The following URI shows an example of the "stop-time" query parameter:
以下URI显示了“停止时间”查询参数的示例：
// start-time = 2014-10-25T10:02:00Z
// stop-time = 2014-10-25T12:31:00Z
GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z\
&stop-time=2014-10-25T12%3A31%3A00Z
// start-time = 2014-10-25T10:02:00Z
// stop-time = 2014-10-25T12:31:00Z
GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z\
&stop-time=2014-10-25T12%3A31%3A00Z
Assume that the server implements the module "example" defined in Appendix A.1 of [RFC6243], and assume that the server's datastore is as defined in Appendix A.2 of [RFC6243].
假设服务器实现了[RFC6243]附录A.1中定义的模块“示例”，并假设服务器的数据存储如[RFC6243]附录A.2中定义。
If the server's "basic-mode" parameter in the "defaults" protocol capability URI (Section 9.1.2) is "trim", the following request for interface "eth1" might be as follows:
如果“默认”协议功能URI（第9.1.2节）中服务器的“基本模式”参数为“trim”，则对接口“eth1”的以下请求可能如下所示：
Without query parameter:
不带查询参数：
GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example:interfaces/interface=eth1 HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"example:interface" : [
{
"name" : "eth1",
"status" : "up"
}
]
}
{
"example:interface" : [
{
"name" : "eth1",
"status" : "up"
}
]
}
Note that the "mtu" leaf is missing because it is set to the default "1500", and the server's default-handling "basic-mode" parameter is "trim".
请注意，缺少“mtu”叶，因为它被设置为默认的“1500”，并且服务器的默认处理“基本模式”参数为“trim”。
With query parameter:
带查询参数：
GET /restconf/data/example:interfaces/interface=eth1\
?with-defaults=report-all HTTP/1.1
Host: example.com
Accept: application/yang-data+json
GET /restconf/data/example:interfaces/interface=eth1\
?with-defaults=report-all HTTP/1.1
Host: example.com
Accept: application/yang-data+json
The server might respond as follows:
服务器可能会做出如下响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Content-Type: application/yang-data+json
{
"example:interface" : [
{
"name" : "eth1",
"mtu" : 1500,
"status" : "up"
}
]
}
{
"example:interface" : [
{
"name" : "eth1",
"mtu" : 1500,
"status" : "up"
}
]
}
Note that the server returns the "mtu" leaf because the "report-all" mode was requested with the "with-defaults" query parameter.
请注意，服务器返回“mtu”叶，因为“report all”模式是使用“with defaults”查询参数请求的。
Acknowledgements
致谢
The authors would like to thank the following people for their contributions to this document: Ladislav Lhotka, Juergen Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford.
作者感谢以下人士对本文件的贡献：拉迪斯拉夫·洛特卡、尤尔根·舍恩瓦埃尔德、雷克斯·费尔南多、罗伯特·威尔顿和乔纳森·汉斯福德。
The authors would like to thank the following people for their excellent technical reviews of this document: Mehmet Ersue, Mahesh Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka, Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, Dale Worley, and Lionel Morand.
作者要感谢以下人士对本文件的优秀技术评论：Mehmet Ersue、Mahesh Jethanandani、秦武、Joe Clarke、Bert Wijnen、Ladislav Lhotka、Rodney Cummings、Frank Xialiang、Tom Petch、Robert Sparks、Balint Uveges、Randy Presohn、Sue Hares、Mark Nottingham、Benoit Claise、Dale Worley、，还有莱昂内尔·莫兰德。
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