4.5. PUT

RESTCONF服务器必须支持PUT方法。 PUT方法由客户端发送以创建或替换目标数据资源。一个请求消息体必须存在，代表新的数据资源，否则服务器必须返回一个“400 Bad Request”状态行。在这种情况下使用错误标签值“invalid-value”。

POST和PUT方法都可以用来创建数据资源。不同的是，对于POST，客户端不提供将被创建的资源的资源标识符。 POST方法创建资源的目标资源是新资源的父资源。创建资源的PUT方法的目标资源是新资源。

数据和数据存储资源必须支持PUT方法。数据存储资源上的PUT用于替换数据存储的全部内容。数据资源上的PUT仅替换数据存储内的数据资源。

数据资源的PUT方法必须支持“insert”（见第4.8.5节）和“point”（见第4.8.6节）查询参数。只有当列表或叶子列表是“ordered-by user”时，才允许使用这些参数。

与[RFC7231]一致，如果PUT请求创建新资源，则返回“201 Created”状态行。如果现有资源被修改，则返回“204 No Content”状态行。

如果用户无权创建或替换目标资源，则应返回包含“403 Forbidden”状态行的错误响应。在这种情况下使用错误标签值“access-denied”。

服务器可以返回“404 Not Found”状态行，如[RFC7231]的第6.5.4节所述。在这种情况下使用错误标签值“invalid-value”。所有其他错误响应按照第7节中定义的过程进行处理。

如果目标资源表示一个YANG叶子列表，那么PUT方法不能改变叶子列表实例的值。

如果目标资源表示一个YANG列表实例，那么消息体表示中的关键叶子值必须与请求URI中的关键叶子值相同。 PUT方法不能用来改变数据资源实例的关键字叶值。

例：

在“example-jukebox”YANG模块中定义的“album”子资源被替换，或者如果它尚不存在，则被创建。

要替换“album”资源内容，客户端可能会发送以下内容：

  1. PUT /restconf/data/example-jukebox:jukebox/\
  2.     library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
  3. Host: example.com
  4. Content-Type: application/yang-data+json
  6. {
  7.   "example-jukebox:album" : [
  8.     {
  9.       "name" : "Wasting Light",
  10.       "genre" : "example-jukebox:alternative",
  11.       "year" : 2011
  12.     }
  13.   ]
  14. }

如果资源更新，服务器可能会作出如下响应：

  1. HTTP/1.1 204 No Content
  2. Date: Thu, 26 Jan 2017 20:56:30 GMT
  3. Server: example-server
  4. Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
  5. ETag: "b27480aeda4c"

这里使用XML编码显示了相同的请求：

  1. PUT /restconf/data/example-jukebox:jukebox/\
  2.     library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
  3. Host: example.com
  4. Content-Type: application/yang-data+xml
  6. <album xmlns="http://example.com/ns/example-jukebox"
  7.        xmlns:jbox="http://example.com/ns/example-jukebox">
  8.   <name>Wasting Light</name>
  9.   <genre>jbox:alternative</genre>
  10.   <year>2011</year>
  11. </album>

有关使用PUT方法替换数据存储区资源内容的示例，请参阅附录B.2.4。