[要約] RFC 8072は、YANG Patch Media Typeの仕様を定義しており、YANGデータモデルの変更をパッチ形式で適用するためのメディアタイプを提供しています。このRFCの目的は、YANGデータモデルの変更を効率的かつ安全に適用するための標準化された手法を提供することです。
Internet Engineering Task Force (IETF) A. Bierman
Request for Comments: 8072 YumaWorks
Category: Standards Track M. Bjorklund
ISSN: 2070-1721 Tail-f Systems
K. Watsen
Juniper Networks
February 2017
YANG Patch Media Type
YANGパッチメディアタイプ
Abstract
概要
This document describes a method for applying patches to configuration datastores using data defined with the YANG data modeling language.
このドキュメントでは、YANGデータモデリング言語で定義されたデータを使用して、構成データストアにパッチを適用する方法について説明します。
Status of This Memo
本文書の状態
This is an Internet Standards Track document.
これはInternet Standards Trackドキュメントです。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
このドキュメントは、IETF（Internet Engineering Task Force）の製品です。これは、IETFコミュニティのコンセンサスを表しています。公開レビューを受け、インターネットエンジニアリングステアリンググループ（IESG）による公開が承認されました。インターネット標準の詳細については、RFC 7841のセクション2をご覧ください。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc8072.
このドキュメントの現在のステータス、エラッタ、およびフィードバックの提供方法に関する情報は、http：//www.rfc-editor.org/info/rfc8072で入手できます。
Copyright Notice
著作権表示
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
Copyright（c）2017 IETF Trustおよびドキュメントの作成者として識別された人物。全著作権所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
この文書は、BCP 78およびこの文書の発行日に有効なIETF文書に関するIETFトラストの法的規定（http://trustee.ietf.org/license-info）の対象となります。これらのドキュメントは、このドキュメントに関するあなたの権利と制限を説明しているため、注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、Trust Legal Provisionsのセクション4.eに記載されているSimplified BSD Licenseのテキストが含まれている必要があり、Simplified BSD Licenseに記載されているように保証なしで提供されます。
Table of Contents
目次
1. Introduction ....................................................3
1.1. Terminology ................................................3
1.1.1. NETCONF .............................................3
1.1.2. HTTP ................................................4
1.1.3. YANG ................................................4
1.1.4. RESTCONF ............................................4
1.1.5. YANG Patch ..........................................5
1.1.6. Examples ............................................5
1.1.7. Tree Diagram Notations ..............................6
2. YANG Patch ......................................................6
2.1. Target Resource ............................................7
2.2. yang-patch Request .........................................8
2.3. yang-patch-status Response .................................9
2.4. Target Data Node ..........................................10
2.5. Edit Operations ...........................................11
2.6. Successful Edit Response Handling .........................11
2.7. Error Handling ............................................12
2.8. ":yang-patch" RESTCONF Capability .........................12
3. YANG Module ....................................................13
4. IANA Considerations ............................................22
4.1. Registrations for New URI and YANG Module .................22
4.2. Media Types ...............................................23
4.2.1. Media Type "application/yang-patch+xml" ............23
4.2.2. Media Type "application/yang-patch+json" ...........24
4.3. RESTCONF Capability URNs ..................................25
5. Security Considerations ........................................25
6. References .....................................................26
6.1. Normative References ......................................26
6.2. Informative References ....................................27
Appendix A. Example YANG Module ...................................28
A.1. YANG Patch Examples ........................................29
A.1.1. Add Resources: Error ...................................29
A.1.2. Add Resources: Success .................................33
A.1.3. Insert List Entry ......................................35
A.1.4. Move List Entry ........................................36
A.1.5. Edit Datastore Resource ................................37
Acknowledgements ..................................................39
Authors' Addresses ................................................39
There is a need for standard mechanisms to patch datastores defined in [RFC6241], which contain conceptual data that conforms to schema specified with YANG [RFC7950]. An "ordered 'edit' list" approach is needed to provide RESTCONF client developers with more precise RESTCONF client control of the edit procedure than the "plain patch" mechanism found in [RFC8040].
YANG [RFC7950]で指定されたスキーマに準拠する概念データを含む、[RFC6241]で定義されたデータストアにパッチを適用する標準的なメカニズムが必要です。 [RFC8040]にある「単純なパッチ」メカニズムよりも正確なRESTCONFクライアント制御をRESTCONFクライアント開発者に提供するには、「順序付き「編集」リスト」アプローチが必要です。
This document defines a media type for a YANG-based editing mechanism that can be used with the HTTP PATCH method [RFC5789]. YANG Patch is designed to support the RESTCONF protocol, defined in [RFC8040]. This document only specifies the use of the YANG Patch media type with the RESTCONF protocol.
このドキュメントは、HTTP PATCHメソッド[RFC5789]で使用できるYANGベースの編集メカニズムのメディアタイプを定義しています。 YANGパッチは、[RFC8040]で定義されているRESTCONFプロトコルをサポートするように設計されています。このドキュメントでは、RESTCONFプロトコルでのYANGパッチメディアタイプの使用のみを指定しています。
It may be possible to use YANG Patch with other protocols besides RESTCONF. This is outside the scope of this document. For any protocol that supports the YANG Patch media type, if the entire patch document cannot be successfully applied, then the server MUST NOT apply any of the changes. It may be possible to use YANG Patch with datastore types other than a configuration datastore. This is outside the scope of this document.
RESTCONF以外のプロトコルでYANGパッチを使用できる場合があります。これはこのドキュメントの範囲外です。 YANGパッチメディアタイプをサポートするプロトコルでは、パッチドキュメント全体を正常に適用できない場合、サーバーは変更を適用してはなりません（MUST NOT）。構成データストア以外のデータストアタイプでYANGパッチを使用できる場合があります。これはこのドキュメントの範囲外です。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
このドキュメントのキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、および「OPTIONAL」は、 [RFC2119]で説明されているように解釈されます。
The following terms are defined in [RFC6241]:
以下の用語は[RFC6241]で定義されています：
o configuration data
o 設定データ
o datastore
o データストア
o configuration datastore
o 構成データストア
o protocol operation
o プロトコル操作
o running configuration datastore
o 実行構成データストア
o state data
o 状態データ
o user
o ユーザー
The following terms are defined in [RFC7230]:
以下の用語は[RFC7230]で定義されています：
o header field
o ヘッダーフィールド
o message-body
o メッセージ本文
o query
o クエリ
o request URI
o リクエストURI
The following terms are defined in [RFC7231]:
以下の用語は[RFC7231]で定義されています：
o method
o 方法
o request
o リクエスト
o resource
o 資源
The following terms are defined in [RFC7950]:
以下の用語は[RFC7950]で定義されています：
o container
o コンテナ
o data node
o だた ので
o leaf
o 葉
o leaf-list
o リーフリスト
o list
o リスト
The following terms are defined in [RFC8040]:
以下の用語は[RFC8040]で定義されています：
o application/yang-data+xml
o application / yang-data + xml
o application/yang-data+json
o application / yang-data + json
o data resource
o データリソース
o datastore resource
o データストアリソース
o patch o RESTCONF capability
oパッチo RESTCONF機能
o target resource
o ターゲットリソース
o YANG data template
o THATテンプレートデータ
The following terms are used within this document:
このドキュメントでは、次の用語が使用されています。
o RESTCONF client: a client that implements the RESTCONF protocol.
o RESTCONFクライアント：RESTCONFプロトコルを実装するクライアント。
o RESTCONF server: a server that implements the RESTCONF protocol.
o RESTCONFサーバー：RESTCONFプロトコルを実装するサーバー。
o YANG Patch: a conceptual edit request using the "yang-patch" YANG Patch template, defined in Section 3. In HTTP, refers to a PATCH method where a representation uses either the media type "application/yang-patch+xml" or "application/yang-patch+json".
o YANGパッチ：セクション3で定義された「yang-patch」YANGパッチテンプレートを使用した概念的な編集要求。HTTPでは、表現がメディアタイプ「application / yang-patch + xml」または「 application / yang-patch + json」。
o YANG Patch Status: a conceptual edit status response using the YANG "yang-patch-status" YANG data template, defined in Section 3. In HTTP, refers to a response message for a PATCH method, where it has a representation with either the media type "application/yang-data+xml" or "application/yang-data+json".
o YANGパッチステータス：セクション3で定義されている、YANG "yang-patch-status" YANGデータテンプレートを使用した概念的な編集ステータス応答。HTTPでは、PATCHメソッドの応答メッセージを指し、メディアまたは「application / yang-data + xml」または「application / yang-data + json」と入力します。
o YANG Patch template: similar to a YANG data template, except that it has a representation with the media type "application/yang-patch+xml" or "application/yang-patch+json".
o YANGパッチテンプレート：メディアタイプ「application / yang-patch + xml」または「application / yang-patch + json」で表現されることを除いて、YANGデータテンプレートと同様です。
Some protocol message lines within examples throughout this document are split into multiple lines for display purposes only. When a line ends with a backslash ("\") as the last character, the line is wrapped for display purposes. It is to be considered to be joined to the next line by deleting the backslash, the following line break, and the leading whitespace of the next line.
このドキュメントの例に含まれる一部のプロトコルメッセージ行は、表示のみを目的として複数の行に分割されています。行が最後の文字としてバックスラッシュ（ "\"）で終わる場合、その行は表示のために折り返されます。バックスラッシュ、次の改行、および次の行の先頭の空白を削除することにより、次の行に結合されていると見なされます。
A simplified graphical representation of the data model is used in this document. The meanings of the symbols in these diagrams are as follows:
このドキュメントでは、データモデルの簡略化されたグラフィカル表現を使用しています。これらの図の記号の意味は次のとおりです。
o Brackets "[" and "]" enclose list keys.
o 大括弧 "["と "]"はリストキーを囲みます。
o Abbreviations before data node names: "rw" means configuration data (read-write), "ro" means state data (read-only), and "x" means operation resource (executable).
o データノード名の前の略語：「rw」は構成データ（読み取り/書き込み）を意味し、「ro」は状態データ（読み取り専用）を意味し、「x」は操作リソース（実行可能）を意味します。
o Symbols after data node names: "?" means an optional node, and "*" denotes a "list" and "leaf-list".
o データノード名の後の記号： "？"オプションのノードを意味し、「*」は「リスト」と「リーフリスト」を示します。
o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":").
o 括弧は選択ノードとケースノードを囲み、ケースノードもコロン（ "："）でマークされます。
o Ellipsis ("...") stands for contents of subtrees that are not shown.
o 省略記号（ "..."）は、表示されていないサブツリーのコンテンツを表します。
A "YANG Patch" is an ordered list of edits that are applied to the target datastore by the RESTCONF server. The specific fields are defined in the YANG module in Section 3.
「YANGパッチ」は、RESTCONFサーバーによってターゲットデータストアに適用される編集の順序付きリストです。特定のフィールドは、セクション3のYANGモジュールで定義されています。
The YANG Patch operation is invoked by the RESTCONF client by sending a PATCH method request with a representation using either the media type "application/yang-patch+xml" or "application/yang-patch+json". This message-body representing the YANG Patch input parameters MUST be present.
YANGパッチ操作は、メディアタイプ「application / yang-patch + xml」または「application / yang-patch + json」のいずれかを使用した表現でPATCHメソッド要求を送信することにより、RESTCONFクライアントによって呼び出されます。 YANGパッチの入力パラメーターを表すこのメッセージ本文が存在する必要があります。
YANG Patch has some features that are not possible with the "plain-patch" mechanism defined in RESTCONF [RFC8040]:
YANGパッチには、RESTCONF [RFC8040]で定義されている「プレーンパッチ」メカニズムでは不可能ないくつかの機能があります。
o YANG Patch allows multiple sub-resources to be edited within the same PATCH method.
o YANGパッチを使用すると、同じPATCHメソッド内で複数のサブリソースを編集できます。
o YANG Patch allows a more precise edit operation than the "plain patch" mechanism found in [RFC8040]. There are seven operations supported ("create", "delete", "insert", "merge", "move", "replace", and "remove").
o YANGパッチは、[RFC8040]にある "プレーンパッチ"メカニズムよりも正確な編集操作を可能にします。 7つの操作がサポートされています（「作成」、「削除」、「挿入」、「マージ」、「移動」、「置換」、および「削除」）。
o YANG Patch uses an "edit" list with an explicit processing order. The edits are processed in client-specified order, and error processing can be precise even when multiple errors occur in the same YANG Patch request.
o YANGパッチは、明示的な処理順序で「編集」リストを使用します。編集はクライアント指定の順序で処理され、同じYANGパッチ要求で複数のエラーが発生した場合でも、エラー処理を正確にすることができます。
The YANG Patch "patch-id" may be useful for debugging and SHOULD be present in any audit logging records generated by the RESTCONF server for a patch.
YANGパッチ「patch-id」はデバッグに役立つ場合があり、パッチのRESTCONFサーバーによって生成される監査ログレコードに存在する必要があります。
The RESTCONF server MUST return the "Accept-Patch" header field in an OPTIONS response, as specified in [RFC5789], which includes the media type for YANG Patch. This is needed by a client to determine the message-encoding formats supported by the server (e.g., XML, JSON, or both). The following is an example of an "Accept-Patch" header:
RESTCONFサーバーは、[RFC5789]で指定されているように、YANGパッチのメディアタイプを含むOPTIONS応答で「Accept-Patch」ヘッダーフィールドを返す必要があります。これは、サーバーでサポートされているメッセージエンコード形式（XML、JSON、またはその両方など）を判別するためにクライアントで必要です。以下は、「Accept-Patch」ヘッダーの例です。
Accept-Patch: application/yang-patch+xml,application/yang-patch+json
Note that YANG Patch can only edit data resources. The PATCH method cannot be used to replace the datastore resource. Although the "ietf-yang-patch" YANG module is written using YANG version 1.1 [RFC7950], an implementation of YANG Patch can be used with content defined in YANG version 1 [RFC6020] as well.
YANGパッチはデータリソースのみを編集できることに注意してください。 PATCHメソッドを使用してデータストアリソースを置き換えることはできません。 「ietf-yang-patch」YANGモジュールは、YANGバージョン1.1 [RFC7950]を使用して記述されていますが、YANGパッチの実装は、YANGバージョン1 [RFC6020]で定義されたコンテンツでも使用できます。
A YANG Patch can be encoded in XML format according to [W3C.REC-xml-20081126]. It can also be encoded in JSON according to "JSON Encoding of Data Modeled with YANG" [RFC7951]. If any metadata needs to be sent in a JSON message, it is encoded according to "Defining and Using Metadata with YANG" [RFC7952].
YANGパッチは、[W3C.REC-xml-20081126]に従ってXML形式でエンコードできます。 「YANGでモデル化されたデータのJSONエンコーディング」[RFC7951]に従ってJSONでエンコードすることもできます。 JSONメッセージでメタデータを送信する必要がある場合は、「YANGを使用したメタデータの定義と使用」[RFC7952]に従ってエンコードされます。
The YANG Patch operation uses the RESTCONF target resource URI to identify the resource that will be patched. This can be the datastore resource itself, i.e., "{+restconf}/data", to edit top-level configuration data resources, or it can be a configuration data resource within the datastore resource, e.g., "{+restconf}/data/ietf-interfaces:interfaces", to edit sub-resources within a top-level configuration data resource.
YANGパッチ操作では、RESTCONFターゲットリソースURIを使用して、パッチが適用されるリソースを識別します。これは、最上位の構成データリソースを編集するためのデータストアリソース自体、つまり「{+ restconf} / data」、またはデータストアリソース内の構成データリソース、たとえば「{+ restconf} / data」にすることができます。 / ietf-interfaces：interfaces "、トップレベルの構成データリソース内のサブリソースを編集します。
The target resource MUST identify exactly one resource instance. If more than one resource instance is identified, then the request MUST NOT be processed and a "400 Bad Request" error response MUST be sent by the server. If the target resource does not identify any existing resource instance, then the request MUST NOT be processed and a "404 Not Found" error response MUST be sent by the server.
ターゲットリソースは、正確に1つのリソースインスタンスを識別する必要があります。複数のリソースインスタンスが識別された場合、リクエストは処理されてはならず（MUST NOT）、 "400 Bad Request"エラー応答がサーバーから送信されなければなりません（MUST）。ターゲットリソースが既存のリソースインスタンスを識別しない場合、要求は処理されてはならず（MUST NOT）、 "404 Not Found"エラー応答がサーバーから送信されなければなりません（MUST）。
Each edit with a YANG Patch identifies a target data node for the associated edit. This is described in Section 2.4.
YANGパッチを使用した各編集は、関連する編集のターゲットデータノードを識別します。これについてはセクション2.4で説明します。
A YANG Patch is identified by a unique "patch-id", and it may have an optional comment. A patch is an ordered collection of edits. Each edit is identified by an "edit-id", and it has an edit operation ("create", "delete", "insert", "merge", "move", "replace", or "remove") that is applied to the target resource. Each edit can be applied to a sub-resource "target" within the target resource. If the operation is "insert" or "move", then the "where" parameter indicates how the node is inserted or moved. For values "before" and "after", the "point" parameter specifies the data node insertion point.
YANGパッチは一意の「パッチID」で識別され、オプションでコメントを付けることができます。パッチは、編集の順序付けられたコレクションです。各編集は「edit-id」で識別され、編集操作（「作成」、「削除」、「挿入」、「マージ」、「移動」、「置換」、または「削除」）があります。ターゲットリソースに適用されます。各編集は、ターゲットリソース内のサブリソース「ターゲット」に適用できます。操作が「挿入」または「移動」の場合、「場所」パラメーターはノードの挿入または移動方法を示します。 「before」と「after」の値の場合、「point」パラメーターはデータノードの挿入ポイントを指定します。
The "merge", "replace", "create", "delete", and "remove" edit operations have exactly the same meanings as those defined for the "operation" attribute described in Section 7.2 of [RFC6241].
「マージ」、「置換」、「作成」、「削除」、および「削除」の編集操作は、[RFC6241]のセクション7.2で説明されている「操作」属性に定義されたものとまったく同じ意味です。
Each edit within a YANG Patch MUST identify exactly one data resource instance. If an edit represents more than one resource instance, then the request MUST NOT be processed and a "400 Bad Request" error response MUST be sent by the server. If the edit does not identify any existing resource instance and the operation for the edit is not "create", then the request MUST NOT be processed and a "404 Not Found" error response MUST be sent by the server. A "yang-patch-status" response MUST be sent by the server identifying the edit or edits that are not valid.
YANGパッチ内の各編集は、正確に1つのデータリソースインスタンスを識別する必要があります。編集が複数のリソースインスタンスを表す場合は、リクエストを処理してはならず（MUST NOT）、「400 Bad Request」エラーレスポンスをサーバーから送信する必要があります。編集が既存のリソースインスタンスを識別せず、編集の操作が「作成」でない場合は、リクエストを処理してはならず（MUST NOT）、「404 Not Found」エラー応答をサーバーから送信する必要があります。 「yang-patch-status」応答は、無効な編集を特定するサーバーから送信されなければなりません（MUST）。
YANG Patch does not provide any access to specific datastores. How a server processes an edit if it is co-located with a Network Configuration Protocol (NETCONF) server that does provide access to individual datastores is left up to the implementation. A complete datastore cannot be replaced in the same manner as that provided by the <copy-config> operation defined in Section 7.3 of [RFC6241]. Only the specified nodes in a YANG Patch are affected.
YANGパッチは特定のデータストアへのアクセスを提供しません。個々のデータストアへのアクセスを提供するネットワーク構成プロトコル（NETCONF）サーバーと同じ場所に配置されている場合、サーバーが編集を処理する方法は実装に任されています。 [RFC6241]のセクション7.3で定義されている<copy-config>操作で提供される方法と同じ方法で、完全なデータストアを置き換えることはできません。 YANGパッチで指定されたノードのみが影響を受けます。
A message-body representing the YANG Patch is sent by the RESTCONF client to specify the edit operation request. When used with the HTTP PATCH method, this data is identified by the YANG Patch media type.
YANGパッチを表すメッセージ本文は、編集操作要求を指定するためにRESTCONFクライアントによって送信されます。 HTTP PATCHメソッドで使用する場合、このデータはYANGパッチメディアタイプで識別されます。
YANG tree diagram for "yang-patch" container:
「yang-patch」コンテナのYANGツリー図：
+---- yang-patch
+---- patch-id string
+---- comment? string
+---- edit* [edit-id]
+---- edit-id string
+---- operation enumeration
+---- target target-resource-offset
+---- point? target-resource-offset
+---- where? enumeration
+---- value?
A message-body representing the YANG Patch Status is returned to the RESTCONF client to report the detailed status of the edit operation. When used with the HTTP PATCH method, this data is identified by the YANG Patch Status media type; the syntax specification is defined in Section 3.
YANGパッチステータスを表すメッセージ本文がRESTCONFクライアントに返され、編集操作の詳細なステータスが報告されます。 HTTP PATCHメソッドで使用する場合、このデータはYANGパッチステータスメディアタイプで識別されます。構文の仕様はセクション3で定義されています。
YANG tree diagram for "yang-patch-status" container:
「yang-patch-status」コンテナのYANGツリー図：
+---- yang-patch-status
+---- patch-id string
+---- (global-status)?
| +--:(global-errors)
| | +---- errors
| | +---- error*
| | +---- error-type enumeration
| | +---- error-tag string
| | +---- error-app-tag? string
| | +---- error-path? instance-identifier
| | +---- error-message? string
| | +---- error-info?
| +--:(ok)
| +---- ok? empty
+---- edit-status
+---- edit* [edit-id]
+---- edit-id string
+---- (edit-status-choice)?
+--:(ok)
| +---- ok? empty
+--:(errors)
+---- errors
+---- error*
+---- error-type enumeration
+---- error-tag string
+---- error-app-tag? string
+---- error-path? instance-identifier
+---- error-message? string
+---- error-info?
The target data node for each edit operation is determined by the value of the target resource in the request and the "target" leaf within each "edit" entry.
各編集操作のターゲットデータノードは、リクエスト内のターゲットリソースの値と、各「編集」エントリ内の「ターゲット」リーフによって決定されます。
If the target resource specified in the request URI identifies a datastore resource, then the path string in the "target" leaf is treated as an absolute path expression identifying the target data node for the corresponding edit. The first node specified in the "target" leaf is a top-level data node defined within a YANG module. The "target" leaf MUST NOT contain a single forward slash ("/"), since this would identify the datastore resource, not a data resource.
リクエストURIで指定されたターゲットリソースがデータストアリソースを識別する場合、「ターゲット」リーフのパス文字列は、対応する編集のターゲットデータノードを識別する絶対パス式として扱われます。 「ターゲット」リーフで指定された最初のノードは、YANGモジュール内で定義された最上位のデータノードです。 「ターゲット」リーフには、単一のスラッシュ（「/」）を含めてはなりません。これは、データリソースではなく、データストアリソースを識別するためです。
If the target resource specified in the request URI identifies a configuration data resource, then the path string in the "target" leaf is treated as a relative path expression. The first node specified in the "target" leaf is a child configuration data node of the data node associated with the target resource. If the "target" leaf contains a single forward slash ("/"), then the target data node is the target resource data node.
リクエストURIで指定されたターゲットリソースが構成データリソースを識別する場合、「ターゲット」リーフのパス文字列は相対パス式として扱われます。 「ターゲット」リーフで指定された最初のノードは、ターゲットリソースに関連付けられたデータノードの子構成データノードです。 「ターゲット」リーフに単一のスラッシュ（「/」）が含まれている場合、ターゲットデータノードはターゲットリソースデータノードです。
Each YANG Patch edit specifies one edit operation on the target data node. The set of operations is aligned with the NETCONF edit operations but also includes some new operations.
YANGパッチの編集ごとに、ターゲットデータノードで1つの編集操作を指定します。一連の操作はNETCONF編集操作と整合していますが、いくつかの新しい操作も含まれています。
+-----------+-------------------------------------------------------+
| Operation | Description |
+-----------+-------------------------------------------------------+
| create | create a new data resource if it does not already |
| | exist; if it already exists, return an error |
| | |
| delete | delete a data resource if it already exists; if it |
| | does not exist, return an error |
| | |
| insert | insert a new user-ordered data resource |
| | |
| merge | merge the edit value with the target data resource; |
| | create if it does not already exist |
| | |
| move | reorder the target data resource |
| | |
| replace | replace the target data resource with the edit value |
| | |
| remove | remove a data resource if it already exists |
+-----------+-------------------------------------------------------+
YANG Patch Edit Operations
YANGパッチ編集操作
If a YANG Patch is completed without errors, the RESTCONF server MUST return a "yang-patch-status" message with a "global-status" choice set to "ok".
YANGパッチがエラーなしで完了した場合、RESTCONFサーバーは、「global-status」の選択肢が「ok」に設定された「yang-patch-status」メッセージを返す必要があります。
Refer to Appendix A.1.2 for an example of a successful YANG Patch response.
正常なYANGパッチ応答の例については、付録A.1.2を参照してください。
If a well-formed, schema-valid YANG Patch message is received, then the RESTCONF server will process the supplied edits in ascending order. The following error modes apply to the processing of this "edit" list:
整形式のスキーマ有効なYANGパッチメッセージを受信した場合、RESTCONFサーバーは提供された編集を昇順で処理します。この「編集」リストの処理には、次のエラーモードが適用されます。
If a YANG Patch is completed with errors, the RESTCONF server SHOULD return a "yang-patch-status" message. It is possible (e.g., within a distributed implementation) that an invalid request will be rejected before the YANG Patch edits are processed. In this case, the server MUST send the appropriate HTTP error response instead.
YANGパッチがエラーで完了した場合、RESTCONFサーバーは「yang-patch-status」メッセージを返す必要があります（SHOULD）。 YANGパッチの編集が処理される前に、無効なリクエストが拒否される可能性があります（たとえば、分散実装内）。この場合、サーバーは適切なHTTPエラー応答を送信する必要があります。
Refer to Appendix A.1.1 for an example of an error YANG Patch response.
エラーYANGパッチ応答の例については、付録A.1.1を参照してください。
A URI is defined to identify the YANG Patch extension to the base RESTCONF protocol. If the RESTCONF server supports the YANG Patch media type, then the ":yang-patch" RESTCONF capability defined in Section 4.3 MUST be present in the "capability" leaf-list in the "ietf-restconf-monitoring" module defined in [RFC8040].
URIは、基本RESTCONFプロトコルに対するYANGパッチ拡張を識別するために定義されています。 RESTCONFサーバーがYANGパッチメディアタイプをサポートする場合、セクション4.3で定義された「：yang-patch」RESTCONF機能は、[RFC8040で定義された「ietf-restconf-monitoring」モジュールの「機能」リーフリストに存在する必要があります。 ]。
The "ietf-yang-patch" module defines conceptual definitions with the "yang-data" extension statements, which are not meant to be implemented as datastore contents by a RESTCONF server.
「ietf-yang-patch」モジュールは、「yang-data」拡張ステートメントを使用して概念的な定義を定義します。これは、RESTCONFサーバーによってデータストアコンテンツとして実装されることを意図していません。
The "ietf-restconf" module from [RFC8040] is used by this module for the "yang-data" extension definition.
[RFC8040]の「ietf-restconf」モジュールは、「yang-data」拡張定義のためにこのモジュールによって使用されます。
<CODE BEGINS>
<コード開始>
file "ietf-yang-patch@2017-02-22.yang"
ファイル「ietf-yang-patch@2017-02-22.yang」
module ietf-yang-patch {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-patch";
prefix "ypatch";
import ietf-restconf { prefix rc; }
organization "IETF NETCONF (Network Configuration) Working Group";
組織「IETF NETCONF（ネットワーク構成）ワーキンググループ」;
contact
"WG Web: <https://datatracker.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Author: Andy Bierman
<mailto:andy@yumaworks.com>
Author: Martin Bjorklund
<mailto:mbj@tail-f.com>
Author: Kent Watsen
<mailto:kwatsen@juniper.net>";
description "This module contains conceptual YANG specifications for the YANG Patch and YANG Patch Status data structures.
説明「このモジュールには、YANGパッチおよびYANGパッチステータスデータ構造の概念的なYANG仕様が含まれています。
Note that the YANG definitions within this module do not represent configuration data of any kind. The YANG grouping statements provide a normative syntax for XML and JSON message-encoding purposes.
このモジュール内のYANG定義は、いかなる種類の構成データも表していません。 YANGグループ化ステートメントは、XMLおよびJSONメッセージのエンコードを目的とした規範的な構文を提供します。
Copyright (c) 2017 IETF Trust and the persons identified as authors of the code. All rights reserved.
Copyright（c）2017 IETF Trustおよびコードの作成者として識別された人物。全著作権所有。
Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info).
ソースおよびバイナリ形式での再配布および使用は、変更の有無にかかわらず、IETFドキュメントに関連するIETFトラストの法的規定のセクション4.cに記載されているSimplified BSD Licenseに準拠し、それに含まれるライセンス条項に従って許可されます（ http://trustee.ietf.org/license-info）。
This version of this YANG module is part of RFC 8072; see the RFC itself for full legal notices.";
このYANGモジュールのこのバージョンはRFC 8072の一部です。完全な法的通知については、RFC自体を参照してください。 ";
revision 2017-02-22 {
description
"Initial revision.";
reference
"RFC 8072: YANG Patch Media Type.";
}
typedef target-resource-offset {
type string;
description
"Contains a data resource identifier string representing
a sub-resource within the target resource.
The document root for this expression is the
target resource that is specified in the
protocol operation (e.g., the URI for the PATCH request).
This string is encoded according to the same rules as those
for a data resource identifier in a RESTCONF request URI.";
reference
"RFC 8040, Section 3.5.3.";
}
rc:yang-data "yang-patch" {
uses yang-patch;
}
rc:yang-data "yang-patch-status" {
uses yang-patch-status;
}
grouping yang-patch {
description "A grouping that contains a YANG container representing the syntax and semantics of a YANG Patch edit request message.";
説明 "YANGパッチ編集リクエストメッセージの構文とセマンティクスを表すYANGコンテナを含むグループ。";
container yang-patch { description "Represents a conceptual sequence of datastore edits, called a patch. Each patch is given a client-assigned patch identifier. Each edit MUST be applied in ascending order, and all edits MUST be applied. If any errors occur, then the target datastore MUST NOT be changed by the YANG Patch operation.
container yang-patch {description "パッチと呼ばれるデータストア編集の概念的なシーケンスを表します。各パッチにはクライアントが割り当てたパッチ識別子が与えられます。各編集は昇順で適用しなければならず、すべての編集を適用しなければなりません。エラーが発生した場合、ターゲットデータストアは、YANGパッチ操作によって変更してはなりません。
It is possible for a datastore constraint violation to occur due to any node in the datastore, including nodes not included in the 'edit' list. Any validation errors MUST be reported in the reply message.";
「編集」リストに含まれていないノードを含む、データストア内のノードが原因で、データストア制約違反が発生する可能性があります。検証エラーはすべて返信メッセージで報告する必要があります。 ";
reference "RFC 7950, Section 8.3.";
「RFC 7950、セクション8.3」を参照してください。
leaf patch-id {
type string;
mandatory true;
description
"An arbitrary string provided by the client to identify
the entire patch. Error messages returned by the server
that pertain to this patch will be identified by this
'patch-id' value. A client SHOULD attempt to generate
unique 'patch-id' values to distinguish between
transactions from multiple clients in any audit logs
maintained by the server.";
}
leaf comment {
type string;
description
"An arbitrary string provided by the client to describe
the entire patch. This value SHOULD be present in any
audit logging records generated by the server for the
patch.";
}
list edit {
key edit-id;
ordered-by user;
description "Represents one edit within the YANG Patch request message. The 'edit' list is applied in the following manner:
description "YANGパッチリクエストメッセージ内の1つの編集を表します。「編集」リストは次のように適用されます：
- The first edit is conceptually applied to a copy of the existing target datastore, e.g., the running configuration datastore. - Each ascending edit is conceptually applied to the result of the previous edit(s). - After all edits have been successfully processed, the result is validated according to YANG constraints. - If successful, the server will attempt to apply the result to the target datastore.";
- 最初の編集は、既存のターゲットデータストア（実行中の構成データストアなど）のコピーに概念的に適用されます。 -それぞれの昇順の編集は、前の編集の結果に概念的に適用されます。 -すべての編集が正常に処理された後、結果はYANG制約に従って検証されます。 -成功した場合、サーバーは結果をターゲットデータストアに適用しようとします。 ";
leaf edit-id {
type string;
description
"Arbitrary string index for the edit.
Error messages returned by the server that pertain
to a specific edit will be identified by this value.";
}
leaf operation {
type enumeration {
enum create {
description
"The target data node is created using the supplied
value, only if it does not already exist. The
'target' leaf identifies the data node to be
created, not the parent data node.";
}
enum delete {
description
"Delete the target node, only if the data resource
currently exists; otherwise, return an error.";
}
enum insert {
description
"Insert the supplied value into a user-ordered
list or leaf-list entry. The target node must
represent a new data resource. If the 'where'
parameter is set to 'before' or 'after', then
the 'point' parameter identifies the insertion
point for the target node.";
}
enum merge {
description
"The supplied value is merged with the target data
node.";
}
enum move {
description
"Move the target node. Reorder a user-ordered
list or leaf-list. The target node must represent
an existing data resource. If the 'where' parameter
is set to 'before' or 'after', then the 'point'
parameter identifies the insertion point to move
the target node.";
}
enum replace {
description
"The supplied value is used to replace the target
data node.";
}
enum remove {
description
"Delete the target node if it currently exists.";
}
}
mandatory true;
description
"The datastore operation requested for the associated
'edit' entry.";
}
leaf target {
type target-resource-offset;
mandatory true;
description
"Identifies the target data node for the edit
operation. If the target has the value '/', then
the target data node is the target resource.
The target node MUST identify a data resource,
not the datastore resource.";
}
leaf point {
when "(../operation = 'insert' or ../operation = 'move')"
+ "and (../where = 'before' or ../where = 'after')" {
description
"This leaf only applies for 'insert' or 'move'
operations, before or after an existing entry.";
}
type target-resource-offset;
description
"The absolute URL path for the data node that is being
used as the insertion point or move point for the
target of this 'edit' entry.";
}
leaf where {
when "../operation = 'insert' or ../operation = 'move'" {
description
"This leaf only applies for 'insert' or 'move'
operations.";
}
type enumeration {
enum before {
description
"Insert or move a data node before the data resource
identified by the 'point' parameter.";
}
enum after {
description
"Insert or move a data node after the data resource
identified by the 'point' parameter.";
}
enum first {
description
"Insert or move a data node so it becomes ordered
as the first entry.";
}
enum last {
description
"Insert or move a data node so it becomes ordered
as the last entry.";
}
}
default last;
description
"Identifies where a data resource will be inserted
or moved. YANG only allows these operations for
list and leaf-list data nodes that are
'ordered-by user'.";
}
anydata value {
when "../operation = 'create' "
+ "or ../operation = 'merge' "
+ "or ../operation = 'replace' "
+ "or ../operation = 'insert'" {
description
"The anydata 'value' is only used for 'create',
'merge', 'replace', and 'insert' operations.";
}
description
"Value used for this edit operation. The anydata 'value'
contains the target resource associated with the
'target' leaf.
For example, suppose the target node is a YANG container named foo:
たとえば、ターゲットノードがfooという名前のYANGコンテナであるとします。
container foo {
leaf a { type string; }
leaf b { type int32; }
}
The 'value' node contains one instance of foo:
「値」ノードには、fooのインスタンスが1つ含まれています。
<value>
<foo xmlns='example-foo-namespace'>
<a>some value</a>
<b>42</b>
</foo>
</value>
";
}
}
}
} // grouping yang-patch
grouping yang-patch-status {
ヤンパッチステータスのグループ化{
description "A grouping that contains a YANG container representing the syntax and semantics of a YANG Patch Status response message.";
説明 "YANGパッチステータス応答メッセージの構文とセマンティクスを表すYANGコンテナを含むグループ。";
container yang-patch-status {
description
"A container representing the response message sent by the
server after a YANG Patch edit request message has been
processed.";
leaf patch-id {
type string;
mandatory true;
description
"The 'patch-id' value used in the request.";
}
choice global-status {
description
"Report global errors or complete success.
If there is no case selected, then errors
are reported in the 'edit-status' container.";
case global-errors {
uses rc:errors;
description
"This container will be present if global errors that
are unrelated to a specific edit occurred.";
}
leaf ok {
type empty;
description
"This leaf will be present if the request succeeded
and there are no errors reported in the 'edit-status'
container.";
}
}
container edit-status {
description
"This container will be present if there are
edit-specific status responses to report.
If all edits succeeded and the 'global-status'
returned is 'ok', then a server MAY omit this
container.";
list edit {
key edit-id;
description "Represents a list of status responses, corresponding to edits in the YANG Patch request message. If an 'edit' entry was skipped or not reached by the server, then this list will not contain a corresponding entry for that edit.";
説明 "YANGパッチリクエストメッセージの編集に対応するステータスレスポンスのリストを表します。「編集」エントリがスキップされたか、サーバーに到達しなかった場合、このリストにはその編集に対応するエントリが含まれません。";
leaf edit-id {
type string;
description
"Response status is for the 'edit' list entry
with this 'edit-id' value.";
}
choice edit-status-choice {
description
"A choice between different types of status
responses for each 'edit' entry.";
leaf ok {
type empty;
description
"This 'edit' entry was invoked without any
errors detected by the server associated
with this edit.";
}
case errors {
uses rc:errors;
description
"The server detected errors associated with the
edit identified by the same 'edit-id' value.";
}
}
}
}
}
} // grouping yang-patch-status
}
｝
<CODE ENDS>
<コード終了>
This document registers one URI as a namespace in the "IETF XML Registry" [RFC3688]. It follows the format in RFC 3688.
このドキュメントでは、「IETF XMLレジストリ」[RFC3688]に名前空間として1つのURIを登録しています。 RFC 3688の形式に従います。
URI: urn:ietf:params:xml:ns:yang:ietf-yang-patch Registrant Contact: The IESG. XML: N/A; the requested URI is an XML namespace.
URI：urn：ietf：params：xml：ns：yang：ietf-yang-patch登録者の連絡先：IESG。 XML：なし。要求されたURIはXML名前空間です。
This document registers one YANG module in the "YANG Module Names" registry [RFC6020].
このドキュメントでは、「YANGモジュール名」レジストリ[RFC6020]に1つのYANGモジュールを登録しています。
name: ietf-yang-patch
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch
prefix: ypatch
reference: RFC 8072
Type name: application
タイプ名：アプリケーション
Subtype name: yang-patch+xml
サブタイプ名：yang-patch + xml
Required parameters: None
必須パラメーター：なし
Optional parameters: None
オプションのパラメーター：なし
Encoding considerations: 8-bit The "utf-8" charset is always used for this type. Each conceptual YANG data node is encoded according to the XML Encoding Rules and Canonical Format for the specific YANG data node type defined in [RFC7950]. In addition, the "yang-patch" YANG Patch template found in RFC 8072 defines the structure of a YANG Patch request.
エンコーディングに関する考慮事項：8ビットこのタイプには常に「utf-8」文字セットが使用されます。各概念的なYANGデータノードは、[RFC7950]で定義されている特定のYANGデータノードタイプのXMLエンコーディングルールと正規フォーマットに従ってエンコードされます。さらに、RFC 8072にある「yang-patch」YANGパッチテンプレートは、YANGパッチリクエストの構造を定義します。
Security considerations: Security considerations related to the generation and consumption of RESTCONF messages are discussed in Section 5 of RFC 8072. Additional security considerations are specific to the semantics of particular YANG data models. Each YANG module is expected to specify security considerations for the YANG data defined in that module.
セキュリティの考慮事項：RESTCONFメッセージの生成と消費に関連するセキュリティの考慮事項は、RFC 8072のセクション5で説明されています。追加のセキュリティの考慮事項は、特定のYANGデータモデルのセマンティクスに固有です。各YANGモジュールは、そのモジュールで定義されているYANGデータのセキュリティに関する考慮事項を指定することが期待されています。
Interoperability considerations: RFC 8072 specifies the format of conforming messages and the interpretation thereof.
相互運用性に関する考慮事項：RFC 8072は、適合メッセージの形式とその解釈を指定しています。
Published specification: RFC 8072
公開された仕様：RFC 8072
Applications that use this media type: Instance document data parsers used within a protocol or automation tool that utilize the YANG Patch data structure.
このメディアタイプを使用するアプリケーション：YANGパッチデータ構造を利用するプロトコルまたは自動化ツール内で使用されるインスタンスドキュメントデータパーサー。
Fragment identifier considerations: The syntax and semantics of fragment identifiers are the same as the syntax and semantics specified for the "application/xml" media type.
フラグメント識別子の考慮事項：フラグメント識別子の構文とセマンティクスは、「application / xml」メディアタイプに指定された構文とセマンティクスと同じです。
Additional information:
追加情報：
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information: See the Authors' Addresses section of RFC 8072.
詳細については、連絡先の個人と電子メールアドレス：RFC 8072の「作成者のアドレス」セクションを参照してください。
Intended usage: COMMON
使用目的：COMMON
Restrictions on usage: N/A
使用上の制限：N / A
Author: See the Authors' Addresses section of RFC 8072.
作成者：RFC 8072の「作成者のアドレス」セクションを参照してください。
Change controller: Internet Engineering Task Force (mailto:iesg@ietf.org).
変更管理者：Internet Engineering Task Force（mailto：iesg@ietf.org）。
Provisional registration? (standards tree only): no
仮登録？ （標準ツリーのみ）：いいえ
Type name: application
タイプ名：アプリケーション
Subtype name: yang-patch+json
サブタイプ名：yang-patch + json
Required parameters: None
必須パラメーター：なし
Optional parameters: None
オプションのパラメーター：なし
Encoding considerations: 8-bit The "utf-8" charset is always used for this type. Each conceptual YANG data node is encoded according to RFC 7951. A metadata annotation is encoded according to RFC 7952. In addition, the "yang-patch" YANG Patch template found in RFC 8072 defines the structure of a YANG Patch request.
エンコーディングに関する考慮事項：8ビットこのタイプには常に「utf-8」文字セットが使用されます。各概念的なYANGデータノードはRFC 7951に従ってエンコードされます。メタデータアノテーションはRFC 7952に従ってエンコードされます。さらに、RFC 8072にある「yang-patch」YANGパッチテンプレートは、YANGパッチリクエストの構造を定義します。
Security considerations: Security considerations related to the generation and consumption of RESTCONF messages are discussed in Section 5 of RFC 8072. Additional security considerations are specific to the semantics of particular YANG data models. Each YANG module is expected to specify security considerations for the YANG data defined in that module.
セキュリティの考慮事項：RESTCONFメッセージの生成と消費に関連するセキュリティの考慮事項は、RFC 8072のセクション5で説明されています。追加のセキュリティの考慮事項は、特定のYANGデータモデルのセマンティクスに固有です。各YANGモジュールは、そのモジュールで定義されているYANGデータのセキュリティに関する考慮事項を指定することが期待されています。
Interoperability considerations: RFC 8072 specifies the format of conforming messages and the interpretation thereof.
相互運用性に関する考慮事項：RFC 8072は、適合メッセージの形式とその解釈を指定しています。
Published specification: RFC 8072
公開された仕様：RFC 8072
Applications that use this media type: Instance document data parsers used within a protocol or automation tool that utilize the YANG Patch data structure.
このメディアタイプを使用するアプリケーション：YANGパッチデータ構造を利用するプロトコルまたは自動化ツール内で使用されるインスタンスドキュメントデータパーサー。
Fragment identifier considerations: The syntax and semantics of fragment identifiers are the same as the syntax and semantics specified for the "application/json" media type.
フラグメント識別子の考慮事項：フラグメント識別子の構文とセマンティクスは、「application / json」メディアタイプに指定された構文とセマンティクスと同じです。
Additional information:
追加情報：
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information: See the Authors' Addresses section of RFC 8072.
詳細については、連絡先の個人と電子メールアドレス：RFC 8072の「作成者のアドレス」セクションを参照してください。
Intended usage: COMMON
使用目的：COMMON
Restrictions on usage: N/A
使用上の制限：N / A
Author: See the Authors' Addresses section of RFC 8072.
作成者：RFC 8072の「作成者のアドレス」セクションを参照してください。
Change controller: Internet Engineering Task Force (mailto:iesg@ietf.org).
変更管理者：Internet Engineering Task Force（mailto：iesg@ietf.org）。
Provisional registration? (standards tree only): no
仮登録？ （標準ツリーのみ）：いいえ
This document registers one capability identifier in the "RESTCONF Capability URNs" registry [RFC8040]. The review policy for this registry is "IETF Review" [RFC5226].
このドキュメントでは、「RESTCONF Capability URNs」レジストリ[RFC8040]に1つの機能識別子を登録しています。このレジストリのレビューポリシーは「IETFレビュー」[RFC5226]です。
Index Capability Identifier
------------------------------------------------------------------
:yang-patch urn:ietf:params:restconf:capability:yang-patch:1.0
The YANG Patch media type does not introduce any significant new security threats, beyond what is described in [RFC8040]. This document defines edit processing instructions for a variant of the PATCH method, as used within the RESTCONF protocol. Message integrity is provided by the RESTCONF protocol. There is no additional capability to validate that a patch has not been altered.
YANGパッチメディアタイプは、[RFC8040]で説明されているものを超えて、重大な新しいセキュリティ脅威をもたらしません。このドキュメントでは、RESTCONFプロトコル内で使用される、PATCHメソッドのバリアントの編集処理命令を定義します。メッセージの整合性はRESTCONFプロトコルによって提供されます。パッチが変更されていないことを検証する追加機能はありません。
It may be possible to use YANG Patch with other protocols besides RESTCONF; this topic is outside the scope of this document.
RESTCONF以外のプロトコルでYANGパッチを使用できる場合があります。このトピックはこのドキュメントの範囲外です。
For RESTCONF, both the client and server MUST be authenticated according to Section 2 of [RFC8040]. It is important for RESTCONF server implementations to carefully validate all the edit request parameters in some manner. If the entire YANG Patch request cannot be completed, then no configuration changes to the system are done. A PATCH request MUST be applied atomically, as specified in Section 2 of [RFC5789].
RESTCONFの場合、[RFC8040]のセクション2に従って、クライアントとサーバーの両方を認証する必要があります。 RESTCONFサーバーの実装では、すべての編集リクエストパラメータを何らかの方法で慎重に検証することが重要です。 YANGパッチ要求全体を完了できない場合、システムの構成変更は行われません。 [RFC5789]のセクション2で指定されているように、PATCHリクエストはアトミックに適用する必要があります。
A RESTCONF server implementation SHOULD attempt to prevent system disruption due to incremental processing of the YANG Patch "edit" list. It may be possible to construct an attack on such a RESTCONF server, which relies on the edit processing order mandated by YANG Patch. A server SHOULD apply only the fully validated configuration to the underlying system. For example, an "edit" list that deleted an interface and then recreated it could cause system disruption if the "edit" list was incrementally applied.
RESTCONFサーバー実装は、YANGパッチの「編集」リストのインクリメンタル処理によるシステムの混乱を防止する必要があります（SHOULD）。このようなRESTCONFサーバーへの攻撃は、YANGパッチで指定された編集処理順序に依存する可能性があります。サーバーは、完全に検証された構成のみを基盤となるシステムに適用する必要があります（SHOULD）。たとえば、インターフェイスを削除してから再作成した「編集」リストは、「編集」リストが段階的に適用された場合にシステムの中断を引き起こす可能性があります。
A RESTCONF server implementation SHOULD attempt to prevent system disruption due to excessive resource consumption required to fulfill YANG Patch edit requests. On such an implementation, it may be possible to construct an attack that attempts to consume all available memory or other resource types.
RESTCONFサーバーの実装は、YANGパッチの編集要求を満たすために必要な過剰なリソース消費によるシステムの中断を防止するよう試みるべきです（SHOULD）。このような実装では、利用可能なすべてのメモリまたは他のリソースタイプを消費しようとする攻撃を構築することが可能になる場合があります。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC2119] Bradner、S。、「要件レベルを示すためにRFCで使用するキーワード」、BCP 14、RFC 2119、DOI 10.17487 / RFC2119、1997年3月、<http://www.rfc-editor.org/info/ rfc2119>。
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <http://www.rfc-editor.org/info/rfc3688>.
[RFC3688] Mealling、M。、「The IETF XML Registry」、BCP 81、RFC 3688、DOI 10.17487 / RFC3688、2004年1月、<http://www.rfc-editor.org/info/rfc3688>。
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, March 2010, <http://www.rfc-editor.org/info/rfc5789>.
[RFC5789] Dusseault、L.およびJ. Snell、「PATCH Method for HTTP」、RFC 5789、DOI 10.17487 / RFC5789、2010年3月、<http://www.rfc-editor.org/info/rfc5789>。
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <http://www.rfc-editor.org/info/rfc6020>.
[RFC6020] Bjorklund、M。、編、「YANG-ネットワーク構成プロトコル（NETCONF）のデータモデリング言語」、RFC 6020、DOI 10.17487 / RFC6020、2010年10月、<http：//www.rfc-editor。 org / info / rfc6020>。
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <http://www.rfc-editor.org/info/rfc6241>.
[RFC6241] Enns、R。、編、Bjorklund、M。、編、Schoenwaelder、J。、編、およびA. Bierman、編、「Network Configuration Protocol（NETCONF）」、RFC 6241、DOI 10.17487 / RFC6241、2011年6月、<http://www.rfc-editor.org/info/rfc6241>。
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7159]ブレイ、T。、編、「JavaScript Object Notation（JSON）データ交換フォーマット」、RFC 7159、DOI 10.17487 / RFC7159、2014年3月、<http://www.rfc-editor.org/info/ rfc7159>。
[RFC7230] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.
[RFC7230] Fielding、R.、Ed。、and J. Reschke、Ed。、 "Hypertext Transfer Protocol（HTTP / 1.1）：Message Syntax and Routing"、RFC 7230、DOI 10.17487 / RFC7230、June 2014、<http：/ /www.rfc-editor.org/info/rfc7230>。
[RFC7231] Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <http://www.rfc-editor.org/info/rfc7231>.
[RFC7231] Fielding、R.、Ed。、and J. Reschke、Ed。、 "Hypertext Transfer Protocol（HTTP / 1.1）：Semantics and Content"、RFC 7231、DOI 10.17487 / RFC7231、June 2014、<http：// www.rfc-editor.org/info/rfc7231>。
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <http://www.rfc-editor.org/info/rfc7950>.
[RFC7950] Bjorklund、M。、編、「The YANG 1.1 Data Modeling Language」、RFC 7950、DOI 10.17487 / RFC7950、2016年8月、<http://www.rfc-editor.org/info/rfc7950>。
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <http://www.rfc-editor.org/info/rfc7951>.
[RFC7951] Lhotka、L。、「YANGでモデル化されたデータのJSONエンコーディング」、RFC 7951、DOI 10.17487 / RFC7951、2016年8月、<http://www.rfc-editor.org/info/rfc7951>。
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", RFC 7952, DOI 10.17487/RFC7952, August 2016, <http://www.rfc-editor.org/info/rfc7952>.
[RFC7952] Lhotka、L。、「YANGを使用したメタデータの定義と使用」、RFC 7952、DOI 10.17487 / RFC7952、2016年8月、<http://www.rfc-editor.org/info/rfc7952>。
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <http://www.rfc-editor.org/info/rfc8040>.
[RFC8040] Bierman、A.、Bjorklund、M。、およびK. Watsen、「RESTCONFプロトコル」、RFC 8040、DOI 10.17487 / RFC8040、2017年1月、<http://www.rfc-editor.org/info/rfc8040 >。
[W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[W3C.REC-xml-20081126]ブレイ、T。、パオリ、J.、Sperberg-McQueen、M。、マラー、E。、およびF.イェルガウ、「Extensible Markup Language（XML）1.0（Fifth Edition）」、 World Wide Web Consortium Recommendation REC-xml-20081126、2008年11月、<http://www.w3.org/TR/2008/REC-xml-20081126>。
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008, <http://www.rfc-editor.org/info/rfc5226>.
[RFC5226] Narten、T。およびH. Alvestrand、「RFCでIANAの考慮事項セクションを作成するためのガイドライン」、BCP 26、RFC 5226、DOI 10.17487 / RFC5226、2008年5月、<http://www.rfc-editor.org / info / rfc5226>。
The example YANG module used in this document represents a simple media jukebox interface. The "example-jukebox" YANG module is defined in [RFC8040].
このドキュメントで使用されているYANGモジュールの例は、シンプルなメディアジュークボックスインターフェースを表しています。 "example-jukebox" YANGモジュールは[RFC8040]で定義されています。
YANG tree diagram for the "example-jukebox" module:
「example-jukebox」モジュールのYANGツリー図：
+--rw jukebox!
+--rw library
| +--rw artist* [name]
| | +--rw name string
| | +--rw album* [name]
| | +--rw name string
| | +--rw genre? identityref
| | +--rw year? uint16
| | +--rw admin
| | | +--rw label? string
| | | +--rw catalogue-number? string
| | +--rw song* [name]
| | +--rw name string
| | +--rw location string
| | +--rw format? string
| | +--rw length? uint32
| +--ro artist-count? uint32
| +--ro album-count? uint32
| +--ro song-count? uint32
+--rw playlist* [name]
| +--rw name string
| +--rw description? string
| +--rw song* [index]
| +--rw index uint32
| +--rw id instance-identifier
+--rw player
+--rw gap? decimal64
rpcs:
rpcs：
+---x play
+--ro input
+--ro playlist string
+--ro song-number uint32
This section includes RESTCONF examples. Most examples are shown in JSON encoding [RFC7159], and some are shown in XML encoding [W3C.REC-xml-20081126].
このセクションにはRESTCONFの例が含まれています。ほとんどの例はJSONエンコーディング[RFC7159]で示され、一部の例はXMLエンコーディング[W3C.REC-xml-20081126]で示されています。
The following example shows several songs being added to an existing album. Each edit contains one song. The first song already exists, so an error will be reported for that edit. The rest of the edits were not attempted, since the first edit failed. XML encoding is used in this example.
次の例は、既存のアルバムに追加されるいくつかの曲を示しています。各編集には1曲が含まれます。最初の曲はすでに存在するため、その編集についてエラーが報告されます。最初の編集が失敗したため、残りの編集は試行されませんでした。この例では、XMLエンコーディングが使用されています。
Request from the RESTCONF client:
RESTCONFクライアントからのリクエスト：
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
Host: example.com
Accept: application/yang-data+xml
Content-Type: application/yang-patch+xml
<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-songs-patch</patch-id>
<edit>
<edit-id>edit1</edit-id>
<operation>create</operation>
<target>/song=Bridge%20Burning</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Bridge Burning</name>
<location>/media/bridge_burning.mp3</location>
<format>MP3</format>
<length>288</length>
</song>
</value>
</edit>
<edit>
<edit-id>edit2</edit-id>
<operation>create</operation>
<target>/song=Rope</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Rope</name>
<location>/media/rope.mp3</location>
<format>MP3</format>
<length>259</length>
</song>
</value>
</edit>
<edit>
<edit-id>edit3</edit-id>
<operation>create</operation>
<target>/song=Dear%20Rosemary</target>
<value>
<song xmlns="http://example.com/ns/example-jukebox">
<name>Dear Rosemary</name>
<location>/media/dear_rosemary.mp3</location>
<format>MP3</format>
<length>269</length>
</song>
</value>
</edit>
</yang-patch>
XML response from the RESTCONF server:
RESTCONFサーバーからのXML応答：
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+xml
<yang-patch-status
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
<patch-id>add-songs-patch</patch-id>
<edit-status>
<edit>
<edit-id>edit1</edit-id>
<errors>
<error>
<error-type>application</error-type>
<error-tag>data-exists</error-tag>
<error-path
xmlns:jb="http://example.com/ns/example-jukebox">
/jb:jukebox/jb:library
/jb:artist[jb:name='Foo Fighters']
/jb:album[jb:name='Wasting Light']
/jb:song[jb:name='Bridge Burning']
</error-path>
<error-message>
Data already exists; cannot be created
</error-message>
</error>
</errors>
</edit>
</edit-status>
</yang-patch-status>
JSON response from the RESTCONF server:
RESTCONFサーバーからのJSON応答：
The following response is shown in JSON format to highlight the difference in the "error-path" object encoding. For JSON, the instance-identifier encoding specified in [RFC7951] is used.
次のレスポンスは、「error-path」オブジェクトエンコーディングの違いを強調するために、JSON形式で示されています。 JSONの場合、[RFC7951]で指定されているインスタンス識別子エンコーディングが使用されます。
HTTP/1.1 409 Conflict
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch",
"edit-status" : {
"edit" : [
{
"edit-id" : "edit1",
"errors" : {
"error" : [
{
"error-type": "application",
"error-tag": "data-exists",
"error-path": "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']",
"error-message":
"Data already exists; cannot be created"
}
]
}
}
]
}
}
}
The following example shows several songs being added to an existing album.
次の例は、既存のアルバムに追加されるいくつかの曲を示しています。
o Each of two edits contains one song.
o 2つの編集にはそれぞれ1つの曲が含まれます。
o Both edits succeed, and new sub-resources are created.
o 両方の編集が成功し、新しいサブリソースが作成されます。
Request from the RESTCONF client:
RESTCONFクライアントからのリクエスト：
PATCH /restconf/data/example-jukebox:jukebox/\
library/artist=Foo%20Fighters/album=Wasting%20Light \
HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "add-songs-patch-2",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "create",
"target" : "/song=Rope",
"value" : {
"song" : [
{
"name" : "Rope",
"location" : "/media/rope.mp3",
"format" : "MP3",
"length" : 259
}
]
}
},
{
"edit-id" : "edit2",
"operation" : "create",
"target" : "/song=Dear%20Rosemary",
"value" : {
"song" : [
{
"name" : "Dear Rosemary",
"location" : "/media/dear_rosemary.mp3",
"format" : "MP3",
"length" : 269
}
]
}
}
]
}
}
Response from the RESTCONF server:
RESTCONFサーバーからの応答：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "add-songs-patch-2",
"ok" : [null]
}
}
The following example shows a song being inserted within an existing playlist. Song "6" in playlist "Foo-One" is being inserted after song "5" in the playlist. The operation succeeds, so a non-error reply can be provided.
次の例は、既存のプレイリストに挿入される曲を示しています。プレイリスト「5」の後にプレイリスト「Foo-One」の「6」が挿入されています。操作は成功したため、エラー以外の応答を提供できます。
Request from the RESTCONF client:
RESTCONFクライアントからのリクエスト：
PATCH /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "insert-song-patch",
"comment" : "Insert song 6 after song 5",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "insert",
"target" : "/song=6",
"point" : "/song=5",
"where" : "after",
"value" : {
"example-jukebox:song" : [
{
"index" : 6,
"id" : "/example-jukebox:jukebox/library\
/artist[name='Foo Fighters']\
/album[name='Wasting Light']\
/song[name='Bridge Burning']"
}
]
}
}
]
}
Response from the RESTCONF server:
RESTCONFサーバーからの応答：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "insert-song-patch",
"ok" : [null]
}
}
The following example shows a song being moved within an existing playlist. Song "1" in playlist "Foo-One" is being moved after song "3" in the playlist. Note that no "value" parameter is needed for a "move" operation. The operation succeeds, so a non-error reply can be provided.
次の例は、既存のプレイリスト内で移動される曲を示しています。プレイリスト「Foo-One」の曲「1」がプレイリストの曲「3」の後に移動しています。 「移動」操作には「値」パラメーターは必要ないことに注意してください。操作は成功したため、エラー以外の応答を提供できます。
Request from the RESTCONF client:
RESTCONFクライアントからのリクエスト：
PATCH /restconf/data/example-jukebox:jukebox/\
playlist=Foo-One HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "move-song-patch",
"comment" : "Move song 1 after song 3",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "move",
"target" : "/song=1",
"point" : "/song=3",
"where" : "after"
}
]
}
}
Response from the RESTCONF server:
RESTCONFサーバーからの応答：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
Content-Type: application/yang-data+json
{
"ietf-restconf:yang-patch-status" : {
"patch-id" : "move-song-patch",
"ok" : [null]
}
}
The following example shows how three top-level data nodes from different modules can be edited at the same time.
次の例は、異なるモジュールの3つの最上位データノードを同時に編集する方法を示しています。
Example module "foo" defines leaf X. Example module "bar" defines container Y, with child leafs A and B. Example module "baz" defines list Z, with key C and child leafs D and E.
サンプルモジュール「foo」はリーフXを定義します。サンプルモジュール「bar」はコンテナYを定義し、子リーフAおよびBを使用します。サンプルモジュール「baz」はリストZを定義し、キーCおよび子リーフDおよびEを使用します。
Request from the RESTCONF client:
RESTCONFクライアントからのリクエスト：
PATCH /restconf/data HTTP/1.1
Host: example.com
Accept: application/yang-data+json
Content-Type: application/yang-patch+json
{
"ietf-yang-patch:yang-patch" : {
"patch-id" : "datastore-patch-1",
"comment" : "Edit 3 top-level data nodes at once",
"edit" : [
{
"edit-id" : "edit1",
"operation" : "create",
"target" : "/foo:X",
"value" : {
"foo:X" : 42
}
},
{
"edit-id" : "edit2",
"operation" : "merge",
"target" : "/bar:Y",
"value" : {
"bar:Y" : {
"A" : "test1",
"B" : 99
}
}
},
{
"edit-id" : "edit3",
"operation" : "replace",
"target" : "/baz:Z=2",
"value" : {
"baz:Z" : [
{
"C" : 2,
"D" : 100,
"E" : false
}
]
}
}
]
}
}
Response from the RESTCONF server:
Response from the RESTCONF server:
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Last-Modified: Thu, 26 Jan 2017 20:55:30 GMT
Content-Type: application/yang-data+json
{
"ietf-yang-patch:yang-patch-status" : {
"patch-id" : "datastore-patch-1",
"ok" : [null]
}
}
Acknowledgements
謝辞
The authors would like to thank Rex Fernando for his contributions to this document.
The authors would like to thank Rex Fernando for his contributions to this document.
Contributions to this material by Andy Bierman are based upon work supported by the United States Army, Space & Terrestrial Communications Directorate (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the S&TCD.
Andy Biermanによるこの資料への貢献は、契約番号W15P7T-13-C-A616に基づいて米国陸海宇宙通信総局（S＆TCD）がサポートする作業に基づいています。この資料に記載されている意見、調査結果、結論または推奨事項は著者のものであり、必ずしもS＆TCDの見解を反映しているわけではありません。
Authors' Addresses
著者のアドレス
Andy Bierman YumaWorks
アンディ・ビアマンYumaWorks
Email: andy@yumaworks.com
Martin Bjorklund Tail-f Systems
Martin Bjorklund Tail-fシステム
Email: mbj@tail-f.com
Kent Watsen Juniper Networks
ケントワトセンジュニパーネットワークス
Email: kwatsen@juniper.net