3.5.3. 在请求URI中编码数据资源标识符

YANG中,可以用[XPath]中定义的绝对XPath表达式来识别数据节点,从文档根开始到目标资源。在RESTCONF中,使用URI编码的路径表达式代替。

数据资源的可预测位置很重要,因为应用程序将编码到YANG数据模型模块,该模块使用静态命名并为所有数据节点定义绝对路径位置。

根据3.5.3.1节中的“api-path”规则,RESTCONF数据资源标识符从左到右编码,从顶层数据节点开始。目标资源节点的每个祖先的节点名称按照顺序编码,结束于目标资源的节点名称。如果路径中的节点在其父节点以外的模块中定义,或者其父节点是数据存储区,则必须在资源标识符中将模块名称后跟一个冒号(“:”)作为节点名称的前缀。细节见3.5.3.1节

如果路径表达式中的数据节点是一个YANG叶子节点,那么叶子列表值必须按照以下规则进行编码:

  • 叶子列表的标识符必须使用一个路径段[RFC3986]进行编码。

  • 路径段通过具有叶名单名称,后跟“=”字符,后跟叶名单值(例如,/restconf/data/top-leaflist=fred)来构建。

  • 使用YANG数据类型的规范表示形式将叶子列表值指定为字符串。根据[RFC3986]的第2.1节第2.5节的规定,任何保留字符都必须进行百分比编码。

  • YANG 1.1允许非配置数据的叶子列表值重复。在这种情况下,没有机制来指定完全匹配的叶子列表实例。

  • 逗号(“,”)字符是百分比编码[RFC3986],尽管多个键值对于叶子列表是不可能的。这是更一致的,避免了特殊的处理规则。

如果路径表达式中的数据节点是一个YANG列表节点,那么列表的键值(如果有的话)必须按照以下规则进行编码:

  • 代表一个YANG列表的数据资源的关键叶子值必须使用一个路径段来编码[RFC3986]。

  • 如果只有一个关键叶值,则路径段通过列表名称,后跟一个“=”字符,后跟单个关键叶值构建。

  • 如果有多个键叶值,路径段通过列表名称构造,其后跟随在“key”语句中标识的每个叶的值,按照在“key”语句中指定的顺序编码。除最后一个关键字以外的每个关键字值都会跟随一个逗号字符。

  • 使用YANG数据类型的规范表示形式将键值指定为字符串。根据[RFC3986]第2.1节第2.5节的规定,任何保留字符都必须进行百分比编码。如果逗号(“,”)字符存在于键值中,则必须进行百分比编码。

  • key”语句中的所有组件必须被编码。部分实例标识符不受支持。

  • 缺少键值是不允许的,所以连续的两个逗号被解释为一个逗号,后跟一个零长度的字符串,后跟一个逗号。例如,“list1=foo,,baz”将被解释为具有三个键值的名为“list1”的列表,并且第二键值是零长度字符串。

  • 请注意,非配置列表不需要定义密钥。在这种情况下,不能访问单个列表实例。

  • 3.5.3.1节中定义“list-instance”的 Augmented Backus-Naur FormABNF)[RFC5234]规则表示列表实例标识符的语法。

示例:

  1. container top {
  2. list list1 {
  3. key "key1 key2 key3";
  4. ...
  5. list list2 {
  6. key "key4 key5";
  7. ...
  8. leaf X { type string; }
  9. }
  10. }
  11. leaf-list Y {
  12. type uint32;
  13. }
  14. }

对于上面的定义,在“example-top”的YANG模块中定义容器“top”,叶子“X”的目标资源URI编码如下:

  1. /restconf/data/example-top:top/list1=key1,key2,key3/list2=key4,key5/X

对于上面的YANG定义,叶列表“Y”的目标资源URI将被编码如下:

  1. /restconf/data/example-top:top/Y=instance-value

以下示例显示保留字符在键值中的百分比编码方式。 “key1”的值包含逗号,单引号,双引号,冒号,双引号,空格和正斜杠(,'":" /)。 请注意,双引号不是保留字符,也不需要百分比编码。 “key2”的值是空字符串,“key3”的值是字符串“foo”。

示例URL

  1. /restconf/data/example-top:top/list1=%2C%27"%3A"%20%2F,,foo