📝 docs(1.0): 完成第三章第六节翻译

refs #7 Signed-off-by: Tony Deng <wolf.deng@gmail.com>
tonydeng · Feb 5, 2018 · be3b77d · be3b77d
1 parent fdd1e55
commit be3b77d
Show file tree

Hide file tree

Showing 4 changed files with 360 additions and 3 deletions.
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -37,9 +37,9 @@
 ](section-3/3.5.3.1.md)
         - [3.5.4. 默认处理](section-3/3.5.4.md)
    - [3.6. 操作资源](section-3/3.6.md)
-        - [3.6.1. Encoding Operation Resource Input Parameters]()
-        - [3.6.2. Encoding Operation Resource Output Parameters]()
-        - [3.6.3. Encoding Operation Resource Errors]()
+        - [3.6.1. 编码操作资源输入参数](section-3/3.6.1.md)
+        - [3.6.2. 编码操作资源输出参数](section-3/3.6.2.md)
+        - [3.6.3. Encoding Operation Resource Errors](section-3/3.6.3.md)
    - [3.7. Schema Resource]()
    - [3.8. Event Stream Resource]()
    - [3.9. "errors" YANG Data Template]()

diff --git a/section-3/3.6.1.md b/section-3/3.6.1.md
@@ -0,0 +1,214 @@
+# 3.6.1. 编码操作资源输入参数
+
+如果“`rpc`”或“`action`”语句具有“`input`”部分，那么这些输入参数的实例将在定义了“`rpc`”或“`action`”语句的模块名称空间中，在名为`XML`的元素或`JSON`对象中对“`input`”进行编码，它位于定义“`rpc`”或“`action`”语句的模块名称空间中。
+
+如果“`rpc`”或“`action`”语句有一个“`input`”部分，并且“`input`”对象树包含任何被认为是强制节点的子数据节点，则消息体必须由客户端在请求中发送。
+
+如果“`rpc`”或“`action`”语句具有“`input`”部分并且“`input`”对象树不包含任何被认为是强制节点的子节点，则客户端可以在请求中发送消息体。
+
+如果“`rpc`”或“`action`”语句没有“`input`”部分，请求消息必须不包含消息体。
+
+例子：
+
+下面的YANG模块用于本节中的RPC操作示例。
+
+```YANG
+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.";
+  }
+
+  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.";
+      }
+    }
+  }
+}
+```
+
+以下的`YANG`模块用于本节的`YANG`动作示例。
+
+```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.";
+  }
+
+  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 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输入示例：
+
+客户端可能会发送以下`POST`请求消息来调用“`reboot`”这个`RPC`操作：
+
+```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>
+```
+
+服务器可能会如下回应：
+
+```
+HTTP/1.1 204 No Content
+Date: Thu, 26 Jan 2017 20:56:30 GMT
+Server: example-server
+```
+
+这里使用`JSON`编码显示了相同的示例请求消息：
+
+```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"
+  }
+}
+```
+
+操作输入示例：
+
+客户端可能会发送以下`POST`请求消息来调用“`reset`”操作：
+
+```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>
+```
+
+服务器可能会如下回应：
+
+```
+HTTP/1.1 204 No Content
+Date: Thu, 26 Jan 2017 20:56:30 GMT
+Server: example-server
+```
+
+这里使用`JSON`编码显示了相同的示例请求消息：
+
+```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
+  }
+}
+```
diff --git a/section-3/3.6.2.md b/section-3/3.6.2.md
@@ -0,0 +1,83 @@
+# 3.6.2. 编码操作资源输出参数
+
+如果“`rpc`”或“`action`”语句具有“`output`”部分，那么这些输出参数的实例将在定义了“`rpc`”或“`action`”语句的模块名称空间中编码到一个`XML`元素或名为`JSON`的对象中的“`output`”，它位于定义了“`rpc`”或“`action`”语句的模块名称空间中。
+
+如果调用`RPC`操作没有错误，并且如果“`rpc`”或“`action`”语句具有“`output`”部分并且“`output`”对象树包含被认为是强制性节点的任何子数据节点，则响应消息体务必在响应中由服务器发送。
+
+如果调用`RPC`操作没有错误，并且“`rpc`”或“`action`”语句具有“`output`”部分，并且“`output`”对象树不包含被视为强制节点的任何子节点，则响应消息体可以由服务器在响应中发送。
+
+请求`URI`不会在响应中返回。可能需要了解请求`URI`，以将输出与请求中使用的特定“`rpc`”或“`action`”语句相关联。
+
+
+例子：
+
+RPC输出示例：
+
+本例使用[3.6.1节](3.6.1.md)定义的“`example-ops`”的`YANG`模块。
+
+客户端可能会发送以下`POST`请求消息来调用“`get-reboot-info`”操作：
+
+```
+POST /restconf/operations/example-ops:get-reboot-info HTTP/1.1
+Host: example.com
+Accept: application/yang-data+json
+```
+
+服务器可能会如下回应：
+
+```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"
+  }
+}
+```
+
+这里使用XML编码显示相同的响应：
+
+```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>
+```
+
+操作输出示例：
+
+本例使用[3.6.1节](3.6.1.md)定义的“`example-actions`”的`YANG`模块。
+
+客户端可能会发送以下`POST`请求消息来调用“`get-last-reset-time`”操作：
+
+```
+POST /restconf/data/example-actions:interfaces/interface=eth0/get-last-reset-time HTTP/1.1
+Host: example.com
+Accept: application/yang-data+json
+```
+
+服务器可能会如下回应：
+
+```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"
+  }
+}
+```
diff --git a/section-3/3.6.3.md b/section-3/3.6.3.md
@@ -0,0 +1,60 @@
+# 3.6.3. 编码操作资源错误
+
+如果在尝试调用操作或操作时发生任何错误，则会返回“`errors`”媒体类型和相应的错误状态。
+
+如果（1）`RPC`操作输入无效或（2）`RPC`操作被调用，但发生错误，那么服务器必须发送一个包含“`errors`”资源的消息体，正如[3.9节](3.9.md)定义的那样。
+
+使用[第3.6.1节](3.6.1.md)中示例中的“`reboot`”的`RPC`操作，客户端可能会发送以下`POST`请求消息：
+
+```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>
+```
+
+服务器可能会回应一个“`invalid-value`”错误：
+
+```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>
+```
+
+这里使用`JSON`编码显示相同的响应：
+
+```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"
+      }
+    ]
+  }
+}
+```