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 Form（ABNF）[RFC5234]规则表示列表实例标识符的语法。

示例：

container top {
    list list1 {
        key "key1 key2 key3";
         ...
         list list2 {
             key "key4 key5";
             ...
             leaf X { type string; }
         }
     }
     leaf-list Y {
       type uint32;
     }
 }

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

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

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

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

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

示例URL：

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