当前位置：首页 > 资讯 > 计算机/互联网 > 互联网

RESTCONF 协议 (2016.4.23)

时间：2019-01-23 18:28 编辑：2KB 来源：2KB.COM 阅读：315
扫一扫，手机访问

分享
扫描二维码，分享到微信打开微信
使用"扫一扫"
再点击微信界面右上角三个点标志
分享到微信朋友和朋友圈。

摘要： 英文原文：dra

英文原文：draft-ietf-netconf-restconf-08

摘要

这份文档描述了一种 RESTful 协议，此协议提供 HTTP 上的编程接口，用于访问 YANG 定义的数据，使用 NETCONF 定义的数据存储。

此备忘的状态

此互联网草案与 BCP 78 和 BCP 79 条款保持完全一致。

互联网草案是指 Internet Engineering Task Force (IETF)的工作文档，需要注意的是，其它组织可能也会分发工作文档为互联网草案。当前的互联网草案列表可以在http://datatracker.ietf.org/drafts/current/找到。

互联网草案是草稿文档，其最长有效期为 6 个月，期间随时可能会更新，替换或废弃。不建议使用互联网草案作为参考材料，也不要在除了“进行中”的主体中引用。

此互联网草案将在 2016 年 4 月 23 日过期。

版权公告

此文档从发布开始，遵从于BCP 78 和IETF Trust 的关于 IETF 文档(http://trustee.ietf.org/license-info)的相关法律条款。请仔细阅读这些文档，它们描述了你对于此文档的权利和限制。文档中的代码必须包含简易BSD协议，见Trust法律条款之章节4.e。如简易BSD协议所述，不对文档中的代码提供担保。

2.4.1 内容模型
2.4.2 编辑模型
2.4.3 锁定模型
2.4.4 持久模型
2.4.5 预设值模型
2.3.1 RESTCONF资源类型
2.3.2 资源发现
2.1 消息模型
2.2 通知模型
2.3 资源模型
2.4 数据存储模型
2.5 事务模型
2.6 扩展性模型
2.7 版本模型
2.8 检索过滤模型
2.9 访问控制模型

3. 操作

3.8.1 "配置"参数
3.8.2 "深度"参数
3.8.3 "格式"参数
3.8.4 "插入"参数
3.8.5 "点"参数
3.8.6 "选择"参数
3.4.1 创建资源模式
3.4.2 调用操作模式
3.1 选项
3.2 HEAD
3.3 GET
3.4 POST
3.5 PUT
3.6 PATCH
3.7 DELETE
3.8 查询参数
3.9 协议操作

4. 消息

4.4.1 RESTCONF元数据JSON编码
4.1 URI请求结构
4.2 消息头
4.3 消息编码
4.4 RESTCONF元数据
4.5 返回状态
4.6 消息缓存

5. 资源

5.4.1 操作输入参数编码
5.4.2 操作输出参数编码
5.3.1 URI请求中的YANG实例标识符编码
5.3.2 数据资源检索
5.1.1 /.well-known/restconf/datastore
5.1.2 /.well-known/restconf/modules
5.1.3 /.well-known/restconf/operations
5.1 API资源 (/.well-known/restconf)
5.2 数据存储资源
5.3 数据资源
5.4 操作资源
5.5 事件资源

6. 错误报告

6.1 错误响应消息

7. YANG补丁

7.6.1 发生错误时继续示例
7.6.2 移动列表条目示例
7.1 为什么不用JSON补丁?
7.2 YANG补丁目标数据节点
7.3 YANG补丁编辑操作
7.4 YANG补丁错误处理
7.5 YANG补丁响应
7.6 YANG补丁示例

8. RESTCONF模块
9. IANA注意事项

9.1 容易知晓的URI
9.2 YANG模块注册

10. 安全注意事项
11. 修改日志

11.1 从YANG-API-01到RESTCONF-00

12. 关闭的议题
13. 开放的议题
14. 示例YANG模块
15. 参考

15.1 标准化参考
15.2 非标准化参考

作者地址

其它翻译版本 (1) 加载中

1. 介绍

有这样一种标准机制的需求，它允许 WEB 应用以一种模块化和可扩展的方式访问网络设备中的配置数据，操作数据，数据模型特定的协议操作，及通知事件。

此文档描述了一种叫做 RESTCONF 的 RESTful 协议，其运行于 HTTP[RFC2616] 上，可用于访问 YANG[RFC6020] 中定义的数据，及使用 NETCONF[RFC6241] 中定义的数据存储。

NETCONF 协议定义了配置数据存储和一系列的创建，获取，更新，删除(CRUD)操作，可用于访问数据存储。YANG 语言定义了数据存储内容，操作数据，自定义协议操作，通知事件的语法和语义。RESFful 操作用于访问数据存储中的分层的数据。

RESTful API 可以被用来创建对 NETCONF 数据存储的 CRUD 操作，包含 YANG 定义的数据。这可以通过一个简化的方式来完成 HTTP 的 RESTful 的设计原则。由于 NETCONF 协议操作不相关，用户不需要为了使用 RESTful API 而需要任何 NETCONF 储备知识。

配置数据和状态数据被公开做为可检索的资源并使用 GET 方法。资源代表配置数据可以通过 DELETE， PATCH，POST 和 PUT 方法被修改。数据模型的特定的协议操作被定义为 YANG 的“rpc”通过 POST 方法调用。数据模型指定通知事件，并被 YANG 定义为“通知”，并可以被访问（TBD 推送方式）。

1.1 NETCONF 功能的简单子集

RESTful API 使用的框架和元模型不需要从那些使用 NETCONF 协议的的框架和元模型来镜像。它只需要和 NETCONF 兼容就足够了。我们只需要一个简化的框架和协议来驱动 NETCONF 的 3 个数据存储(候选，运行中，启动)就行了，同时还能隐藏从客户端得到的各种数据存储的复杂性。

我们需要一个简化的交易模型，该模型允许在复杂的语境资源中进行简单的增删改查操作。这代表了 NETCONF 协议的事物能力的受限子集。

应用程序如果需要更复杂的事物能力也许应该考虑 NETCONF 而不是 RESTCONF。下列事物特性不直接被 RESTCONF 支持：

数据存储锁定 (全局或者部分)
候选数据存储
启动数据存储
验证操作
确认-提交的过程

一台服务器可以将 NETCONF 操作暴露为基于数据模型的操作资源，但那不在本文档的讨论范围中。

RESTful API 没有要取代 NETCONF 的意思，而是提供一种额外的简易接口，遵循 RESTful 原则并且与面向资源的设备抽象兼容。它希望那些需要 NETCONF 完整功能集（比如通知功能）的应用能继续使用 NETCONF。

下图展示了系统组件：

      +-----------+           +-----------------+
      |  WEB app  | <-------> |                 |
      +-----------+   HTTP    |     网络设备     |
                              |                 |
      +-----------+           |   +-----------+ |
      |  NMS app  | <-------> |   |  数据存储  | |
      +-----------+  NETCONF  |   +-----------+ |
                              +-----------------+

1.2 数据模型驱动的 API

RESTCONF 整合了 HTTP 上的 RESTful API 的简单性和结构驱动的可预测性与自动化潜力。

一个使用 HATEOAS 原则的 RESTful 客户端不会使用任何数据建模语言来定义 API 的应用指定内容。客户端可以通过遍历作为 Location ID 返回的 URI 来发现每一个子资源，以此发掘服务器的功用。

此方法关于控制复杂网络设备有 3 大弱点：

低效的性能：配置的 API 会很复杂，且需要数不清的协议消息来发现所有的结构信息。一般数据类型信息也要放进协议消息里进行传递，这也是一大浪费。
无数据模型丰富性：缺少数据模型，结构级别的语义及有效性约束对应用不可用。
无工具自动化：API 自动化工具需要一些内容结构。这些工具能根据特定的数据模型自动变更编程和文档任务。

诸如 YANG 模块的数据模型模块，将把 "API contract"作为很荣幸的服务器。应用程序设计人员可以编码成数据模型，在重要的细节中预先知道确切地协议操作和一致性服务器实施将支持的数据存贮内容。

一旦客户想使用它，RESTCONF 将提供 YANG 模块支持的服务器性能信息。对于基于 YANG 模块基础之上的定义，客户协议操作和数据存储内容的 URIs 是可以预测的。需要注意的是：对于客户使用来说 YANG 模块和可预测的 URIs 是可以选择的。在功能上，他们完全地不能忽视任何协议的损失。

有使用 CLI 和 SNMP 的运营经验的，表明该操作者了解特定服务或者相关数据的“设置”以及不期待此信息是任意的，并且发现每次客户会打开一个服务器的一个管理会话。

1.3 术语

本文档中的关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL"的解释如BCP 14[RFC2119]描述。

1.3.1 NETCONF

以下术语定义在[RFC6241]:

候选配置数据存储
客户端
配置数据
数据存储
配置数据存储
协议操作
运行时配置数据存储
服务器
启动配置数据存储
状态数据
用户

1.3.2 HTTP

以下术语定义在[RFC2616]:

实体标签
分段
标题行
消息体
方法
路径
查询
请求URI
应答体

1.3.3 YANG

以下术语定义在[RFC6020]:

容器
数据节点
关键叶子节点
叶子节点
叶子节点集合
集合
presence容器(或P-容器)
RPC操作(现称为协议操作)
non-presence容器 (或NP-容器)
系统排序
用户排序

[译注：YANG不了解，翻译可能不准确。]

1.3.4 术语

本文档会使用以下术语:

API资源（API resource）：媒体类型为"application/vnd.yang.api+xml"或"application/vnd.yang.api+json"的一种资源。API资源只能被服务器编辑。
数据资源（data resource）：媒体类型为"application/vnd.yang.data+xml"或"application/vnd.yang.data+json"的一种资源。数据资源可以被客户和服务器编辑。只有YANG 容器和集合可以是数据资源。顶层YANG终点被当作数据资源的域。
数据存储资源（datastore resource）：媒体类型为"application/vnd.yang.datastore+xml"或"application/vnd.yang.datastore+json"的一种资源。数据存储资源只能被服务器编辑。
编辑操作（edit operation）：使用POST、PUT、PATCH或DELETE方法作用于数据资源上的一种RESTCONF操作。
事件资源（event resource）：媒体类型为"application/vnd.yang.event+xml"或"application/vnd.yang.event+json"的一种资源。它描述了一种由通知消息中递交的概念体系或数据模型特定的事件。
域（field）：资源中的一个YANG终端节点。
操作（operation）：消息的RESTCONF概念操作，源自HTTP方法、请求URL、报头、和消息体。
操作资源（operation resource）：媒体类型为"application/vnd.yang.operation+xml"或"application/vnd.yang.operation+json"的一种资源。
补丁（patch）：作用于目标数据存储的一般PATCH操作。消息体内容里的媒体类型指出了使用的补丁类型。
简单补丁（plain patch）：媒体类型为"application/vnd.yang.data+xml"或"application/vnd.yang.data+json"的PATCH操作。
请求参数（query parameter）：请求URI中编码在查询部分的参数（和其值）。
资源（resource）：表示一个设备中可管理组件的概念对象。包括资源本身和它的所有的域。
检索请求（retrieval request）: 使用GET或HEAD的操作。
目标资源（target resource）：和特定消息关联的一种资源，由请求URI中的“path”组件定义。
统一数据存储（unified datastore）：运行配置的设备的概念表示。服务器将隐藏NETCONF数据存储的所有编辑操作，比如：":candidate"和":startup"能力。
YANG补丁（YANG Patch）：媒体类型为"application/vnd.yang.patch+xml"或"application/vnd.yang.patch+json"的PATCH操作。
YANG终端节点（YANG terminal node）：YANG节点表示叶子节点、叶子节点集合或任何xml定义。