[要約] RFC 8650は、RESTCONFを介してYANGイベントとデータストアに動的にサブスクライブするための仕様です。その目的は、ネットワークデバイスの状態変更やデータの変更をリアルタイムで監視し、効率的なネットワーク管理を可能にすることです。
Internet Engineering Task Force (IETF) E. Voit
Request for Comments: 8650 R. Rahman
Category: Standards Track E. Nilsen-Nygaard
ISSN: 2070-1721 Cisco Systems
A. Clemm
Futurewei
A. Bierman
YumaWorks
November 2019
Dynamic Subscription to YANG Events and Datastores over RESTCONF
RESTCONFを介したYANGイベントおよびデータストアへの動的サブスクリプション
Abstract
概要
This document provides a RESTCONF binding to the dynamic subscription capability of both subscribed notifications and YANG-Push.
このドキュメントは、サブスクライブされた通知とYANG-Pushの両方の動的サブスクリプション機能へのRESTCONFバインディングを提供します。
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 https://www.rfc-editor.org/info/rfc8650.
このドキュメントの現在のステータス、エラータ、およびフィードバックの提供方法に関する情報は、https：//www.rfc-editor.org/info/rfc8650で入手できます。
Copyright Notice
著作権表示
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
Copyright（c）2019 IETF Trustおよびドキュメントの作成者として識別された人物。全著作権所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://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トラストの法的規定（https://trustee.ietf.org/license-info）の対象であり、この文書の発行日に有効です。これらのドキュメントは、このドキュメントに関するあなたの権利と制限を説明しているため、注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、Trust Legal Provisionsのセクション4.eに記載されているSimplified BSD Licenseテキストが含まれている必要があり、Simplified BSD Licenseに記載されているように保証なしで提供されます。
Table of Contents
目次
1. Introduction
2. Terminology
3. Dynamic Subscriptions
3.1. Transport Connectivity
3.2. Discovery
3.3. RESTCONF RPCs and HTTP Status Codes
3.4. Call Flow for Server-Sent Events
4. QoS Treatment
5. Notification Messages
6. YANG Tree
7. YANG Module
8. IANA Considerations
9. Security Considerations
10. References
10.1. Normative References
10.2. Informative References
Appendix A. Examples
A.1. Dynamic Subscriptions
A.1.1. Establishing Dynamic Subscriptions
A.1.2. Modifying Dynamic Subscriptions
A.1.3. Deleting Dynamic Subscriptions
A.2. Subscription State Notifications
A.2.1. "subscription-modified"
A.2.2. "subscription-completed", "subscription-resumed", and
"replay-completed"
A.2.3. "subscription-terminated" and "subscription-suspended"
A.3. Filter Example
Acknowledgments
Authors' Addresses
Mechanisms to support event subscription and YANG-Push are defined in [RFC8639]. Enhancements to [RFC8639] that enable YANG datastore subscription and YANG-Push are defined in [RFC8641]. This document provides a transport specification for dynamic subscriptions over RESTCONF [RFC8040]. Requirements for these mechanisms are captured in [RFC7923].
イベントサブスクリプションとYANG-Pushをサポートするメカニズムは、[RFC8639]で定義されています。 YANGデータストアサブスクリプションとYANG-Pushを有効にする[RFC8639]の拡張機能は、[RFC8641]で定義されています。このドキュメントは、RESTCONF [RFC8040]を介した動的サブスクリプションのトランスポート仕様を提供します。これらのメカニズムの要件は、[RFC7923]に記載されています。
The streaming of notifications that encapsulate the resulting information push is done via the mechanism described in Section 6.3 of [RFC8040].
結果の情報プッシュをカプセル化する通知のストリーミングは、[RFC8040]のセクション6.3で説明されているメカニズムを介して行われます。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
キーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」、「OPTIONALこのドキュメントの「」は、BCP 14 [RFC2119] [RFC8174]で説明されているように解釈されます。
The following terms use the definitions from [RFC8639]: dynamic subscription, event stream, notification message, publisher, receiver, subscriber, and subscription.
次の用語は、[RFC8639]の定義を使用しています：動的サブスクリプション、イベントストリーム、通知メッセージ、パブリッシャー、レシーバー、サブスクライバー、サブスクリプション。
Other terms reused include datastore, which is defined in [RFC8342], and HTTP/2 stream, which maps to the definition of "stream" within [RFC7540], Section 2.
再利用されるその他の用語には、[RFC8342]で定義されているデータストアや、[RFC7540]の「ストリーム」の定義にマッピングされているHTTP / 2ストリーム、セクション2があります。
This section provides specifics on how to establish and maintain dynamic subscriptions over RESTCONF [RFC8040]. Subscribing to event streams is accomplished in this way via RPCs defined within [RFC8639], Section 2.4. The RPCs are done via RESTCONF POSTs. YANG datastore subscription is accomplished via augmentations to [RFC8639] as described within [RFC8641], Section 4.4.
このセクションでは、RESTCONF [RFC8040]を介した動的サブスクリプションを確立および維持する方法の詳細について説明します。イベントストリームのサブスクライブは、[RFC8639]のセクション2.4で定義されたRPCを介してこのように行われます。 RPCはRESTCONF POSTを介して行われます。 YANGデータストアのサブスクリプションは、[RFC8641]のセクション4.4で説明されているように、[RFC8639]の拡張によって実現されます。
As described in Section 6.3 of [RFC8040], a GET needs to be performed on a specific URI on the publisher. Subscribers cannot predetermine the URI against which a subscription might exist on a publisher, as the URI will only exist after the "establish-subscription" RPC has been accepted. Therefore, the POST for the "establish-subscription" RPC replaces the GET request for the "location" leaf that is used in [RFC8040] to obtain the URI. The subscription URI will be determined and sent as part of the response to the "establish-subscription" RPC, and a subsequent GET to this URI will be done in order to start the flow of notification messages back to the subscriber. As specified in Section 2.4.1 of [RFC8639], a subscription does not move to the active state until the GET is received.
[RFC8040]のセクション6.3で説明されているように、GETはパブリッシャーの特定のURIで実行する必要があります。 URIは「establish-subscription」RPCが受け入れられた後にのみ存在するため、サブスクライバーは、サブスクリプションがパブリッシャーに存在する可能性があるURIを事前に決定することはできません。したがって、「establish-subscription」RPCのPOSTは、[RFC8040]でURIを取得するために使用される「ロケーション」リーフのGETリクエストを置き換えます。サブスクリプションURIが決定されて、 "establish-subscription" RPCへの応答の一部として送信されます。その後、このURIへのGETが実行され、サブスクライバーへの通知メッセージのフローが開始されます。 [RFC8639]のセクション2.4.1で指定されているように、GETを受信するまでサブスクリプションはアクティブ状態に移行しません。
For a dynamic subscription, when a RESTCONF session doesn't already exist, a new RESTCONF session is initiated from the subscriber.
動的サブスクリプションの場合、RESTCONFセッションがまだ存在しないときは、サブスクライバーから新しいRESTCONFセッションが開始されます。
As stated in Section 2.1 of [RFC8040], a subscriber MUST establish the HTTP session over TLS [RFC8446] in order to secure the content in transit.
[RFC8040]のセクション2.1で述べたように、サブスクライバーは、転送中のコンテンツを保護するために、TLS [RFC8446]を介してHTTPセッションを確立する必要があります。
Without the involvement of additional protocols, HTTP sessions by themselves do not support quick recognition of the loss of the communication path to the publisher. Where quick recognition of the loss of a publisher is required, a subscriber SHOULD use a TLS heartbeat [RFC6520], just from subscriber to publisher, to track HTTP session continuity.
追加のプロトコルが関与しない場合、HTTPセッション自体は、パブリッシャーへの通信パスの喪失を迅速に認識することをサポートしません。パブリッシャーの喪失を迅速に認識する必要がある場合、サブスクライバーは、サブスクライバーからパブリッシャーまでのTLSハートビート[RFC6520]を使用して、HTTPセッションの継続性を追跡する必要があります。
Loss of the heartbeat MUST result in the teardown of any subscription-related TCP sessions between those endpoints. A subscriber can then attempt to re-establish the dynamic subscription by using the procedure described in Section 3.4.
ハートビートが失われると、それらのエンドポイント間のサブスクリプション関連のTCPセッションがティアダウンする必要があります。サブスクライバーは、3.4節で説明されている手順を使用して、動的サブスクリプションの再確立を試みることができます。
Subscribers can learn which event streams a RESTCONF server supports by querying the "streams" container of ietf-subscribed-notifications.yang in [RFC8639]. Support for the "streams" container of ietf-restconf-monitoring.yang in [RFC8040] is not required. In the case when the RESTCONF binding specified by this document is used to convey the "streams" container from ietf-restconf-monitoring.yang (i.e., that feature is supported), any event streams contained therein are also expected to be present in the "streams" container of ietf-restconf-monitoring.yang.
サブスクライバーは、[RFC8639]のietf-subscribed-notifications.yangの "streams"コンテナーにクエリを実行することにより、RESTCONFサーバーがサポートするイベントストリームを知ることができます。 [RFC8040]のietf-restconf-monitoring.yangの「ストリーム」コンテナのサポートは必要ありません。このドキュメントで指定されているRESTCONFバインディングがietf-restconf-monitoring.yangから「ストリーム」コンテナを伝達するために使用される場合（つまり、その機能がサポートされている場合）、そこに含まれるイベントストリームも、 ietf-restconf-monitoring.yangの「ストリーム」コンテナ。
Subscribers can learn which datastores a RESTCONF server supports by following Section 2 of [RFC8527].
加入者は、[RFC8527]のセクション2に従って、RESTCONFサーバーがサポートするデータストアを知ることができます。
Specific HTTP response codes as defined in Section 6 of [RFC7231] will indicate the result of RESTCONF RPC requests with the publisher. An HTTP status code of 200 is the proper response to any successful RPC defined within [RFC8639] or [RFC8641].
[RFC7231]のセクション6で定義されている特定のHTTP応答コードは、パブリッシャーとのRESTCONF RPCリクエストの結果を示します。 200のHTTPステータスコードは、[RFC8639]または[RFC8641]内で定義された成功したRPCに対する適切な応答です。
If a publisher fails to serve the RPC request for one of the reasons indicated in Section 2.4.6 of [RFC8639] or Appendix A of [RFC8641], this will be indicated by an appropriate error code, as shown below, transported in the HTTP response.
[RFC8639]のセクション2.4.6または[RFC8641]の付録Aに示されているいずれかの理由でパブリッシャーがRPCリクエストを処理できなかった場合、HTTPで転送される以下のように、適切なエラーコードで示されます。応答。
When an HTTP error code is returned, the RPC reply MUST include an <rpc-error> element per Section 7.1 of [RFC8040] with the following parameter values:
HTTPエラーコードが返された場合、RPC応答には、[RFC8040]のセクション7.1にある<rpc-error>要素と、次のパラメータ値を含める必要があります。
* an "error-type" node of "application".
* 「アプリケーション」の「エラータイプ」ノード。
* an "error-tag" node whose value is a string that corresponds to an identity associated with the error. This "error-tag" will come from one of two places and will correspond to the error identities either within Section 2.4.6 of [RFC8639] for general subscription errors (Table 1) or within Appendix A.1 of [RFC8641] for subscription errors specific to YANG datastores (Table 2).
* エラーに関連付けられたIDに対応する文字列を値とする「エラータグ」ノード。この「エラータグ」は2つの場所のいずれかから送信され、[RFC8639]のセクション2.4.6内の一般的なサブスクリプションエラー（表1）またはサブスクリプションの[RFC8641]の付録A.1内のエラーIDに対応します。 YANGデータストアに固有のエラー（表2）。
* an "error-app-tag" node whose value is a string that corresponds to an identity associated with the error, as defined in Section 2.4.6 of [RFC8639] for general subscriptions or Appendix A.1 of [RFC8641] for subscription errors specific to YANG datastores. The tag to use depends on the RPC for which the error occurred. Viable errors for different RPCs are found in Table 3.
* 一般的なサブスクリプションの場合は[RFC8639]のセクション2.4.6、またはサブスクリプションエラーの場合は[RFC8641]の付録A.1で定義されているように、値がエラーに関連付けられたIDに対応する文字列である「error-app-tag」ノードYANGデータストアに固有。使用するタグは、エラーが発生したRPCによって異なります。さまざまなRPCの実行可能なエラーを表3に示します。
+------------------------+-------------------------+-----------+
| Error identity | Uses "error-tag" | HTTP code |
+========================+=========================+===========+
| dscp-unavailable | invalid-value | 400 |
+------------------------+-------------------------+-----------+
| encoding-unsupported | invalid-value | 400 |
+------------------------+-------------------------+-----------+
| filter-unsupported | invalid-value | 400 |
+------------------------+-------------------------+-----------+
| insufficient-resources | resource-denied | 409 |
+------------------------+-------------------------+-----------+
| no-such-subscription | invalid-value | 404 |
+------------------------+-------------------------+-----------+
| replay-unsupported | operation-not-supported | 501 |
+------------------------+-------------------------+-----------+
Table 1: General Subscription Error Identities and Associated "error-tag" Use
表1：一般的なサブスクリプションエラーIDと関連する「エラータグ」の使用
+-----------------------------+-------------------------+-----------+
| Error identity | Uses "error-tag" | HTTP |
| | | code |
+=============================+=========================+===========+
| cant-include | operation-not-supported | 501 |
+-----------------------------+-------------------------+-----------+
| datastore-not-subscribable | invalid-value | 400 |
+-----------------------------+-------------------------+-----------+
| no-such-subscription-resync | invalid-value | 404 |
+-----------------------------+-------------------------+-----------+
| on-change-unsupported | operation-not-supported | 501 |
+-----------------------------+-------------------------+-----------+
| on-change-sync-unsupported | operation-not-supported | 501 |
+-----------------------------+-------------------------+-----------+
| period-unsupported | invalid-value | 400 |
+-----------------------------+-------------------------+-----------+
| update-too-big | too-big | 400 |
+-----------------------------+-------------------------+-----------+
| sync-too-big | too-big | 400 |
+-----------------------------+-------------------------+-----------+
| unchanging-selection | operation-failed | 500 |
+-----------------------------+-------------------------+-----------+
Table 2: Datastore-Specific Error Identities and Associated "error-tag" Use
表2：データストア固有のエラーIDと関連する「エラータグ」の使用
+------------------------+--------------------------------+
| RPC | Select an identity with a base |
+========================+================================+
| establish-subscription | establish-subscription-error |
+------------------------+--------------------------------+
| modify-subscription | modify-subscription-error |
+------------------------+--------------------------------+
| delete-subscription | delete-subscription-error |
+------------------------+--------------------------------+
| kill-subscription | delete-subscription-error |
+------------------------+--------------------------------+
| resync-subscription | resync-subscription-error |
+------------------------+--------------------------------+
Table 3: RPC Errors and Associated Error Identities
表3：RPCエラーと関連するエラーID
Each error identity will be inserted as the "error-app-tag" using JSON encoding following the form <modulename>:<identityname>. An example of such a valid encoding would be "ietf-subscribed-notifications:no-such-subscription".
各エラーIDは、<modulename>：<identityname>の形式に従って、JSONエンコーディングを使用して「error-app-tag」として挿入されます。このような有効なエンコードの例は、「ietf-subscribed-notifications：no-such-subscription」です。
In the case of error responses to an "establish-subscription" or "modify-subscription" request, there is the option to include an "error-info" node. This node may contain hints for parameter settings that might lead to successful RPC requests in the future. Tables 4 and 5 show the yang-data structures that may be returned.
「establish-subscription」または「modify-subscription」リクエストに対するエラー応答の場合、「error-info」ノードを含めるオプションがあります。このノードには、将来RPCリクエストが成功する可能性のあるパラメータ設定のヒントが含まれている場合があります。表4および5は、返される可能性のあるyang-data構造を示しています。
+--------------+---------------------------------------------+
| Target: | Return hints in yang-data structure |
+==============+=============================================+
| event stream | establish-subscription-stream-error-info |
+--------------+---------------------------------------------+
| datastore | establish-subscription-datastore-error-info |
+--------------+---------------------------------------------+
Table 4: Optional "error-info" Node Hints for an "establish-subscription" Request
表4：「establish-subscription」リクエストのオプションの「error-info」ノードヒント
+--------------+------------------------------------------+
| Target: | Returns hints in yang-data structure |
+==============+==========================================+
| event stream | modify-subscription-stream-error-info |
+--------------+------------------------------------------+
| datastore | modify-subscription-datastore-error-info |
+--------------+------------------------------------------+
Table 5: Optional "error-info" Node Hints for an "modify-subscription" Request
表5：「modify-subscription」リクエストのオプションの「error-info」ノードヒント
The yang-data included within "error-info" SHOULD NOT include the optional leaf "reason", as such a leaf would be redundant with information that is already placed within the "error-app-tag".
"error-info"内に含まれるyang-dataには、オプションのリーフ "reason"を含めないでください。そのようなリーフは、 "error-app-tag"内にすでに配置されている情報と重複するためです。
In case of an <rpc-error> as a result of a "delete-subscription", a "kill-subscription", or a "resync-subscription" request, no "error-info" needs to be included, as the "subscription-id" is the only RPC input parameter, and no hints regarding this RPC input parameters need to be provided.
「delete-subscription」、「kill-subscription」、または「resync-subscription」リクエストの結果として<rpc-error>が発生した場合、「error-info」を含める必要はありません。 subscription-id」は唯一のRPC入力パラメーターであり、このRPC入力パラメーターに関するヒントを提供する必要はありません。
Note that "error-path" [RFC8040] does not need to be included with the <rpc-error> element, as subscription errors are generally associated with the choice of RPC input parameters.
サブスクリプションエラーは一般にRPC入力パラメーターの選択に関連付けられているため、「error-path」[RFC8040]を<rpc-error>要素に含める必要はないことに注意してください。
The call flow for Server-Sent Events (SSE) is defined in Figure 1. The logical connections denoted by (a) and (b) can be a TCP connection or an HTTP/2 stream (if HTTP/2 is used, multiple HTTP/2 streams can be carried in one TCP connection). Requests to RPCs as defined in [RFC8639] or [RFC8641] are sent on a connection indicated by (a). A successful "establish-subscription" will result in an RPC response returned with both a subscription identifier that uniquely identifies a subscription, as well as a URI that uniquely identifies the location of subscription on the publisher (b). This URI is defined via the "uri" leaf in the data model in Section 7.
サーバー送信イベント（SSE）の呼び出しフローは、図1で定義されています。（a）および（b）で示される論理接続は、TCP接続またはHTTP / 2ストリーム（HTTP / 2が使用されている場合、複数のHTTP / 2ストリームは1つのTCP接続で伝送できます）。 [RFC8639]または[RFC8641]で定義されているRPCへの要求は、（a）で示される接続で送信されます。 「establish-subscription」が成功すると、サブスクリプションを一意に識別するサブスクリプション識別子と、パブリッシャーのサブスクリプションの場所を一意に識別するURI（b）の両方でRPC応答が返されます。このURIは、セクション7のデータモデルの「uri」リーフを介して定義されます。
An HTTP GET is then sent on a separate logical connection (b) to the URI on the publisher. This signals the publisher to initiate the flow of notification messages that are sent in SSE [W3C-20150203] as a response to the GET. There cannot be two or more simultaneous GET requests on a subscription URI: any GET request received while there is a current GET request on the same URI MUST be rejected with HTTP error code 409.
次に、HTTP GETが別の論理接続（b）でパブリッシャーのURIに送信されます。これは、GETへの応答としてSSE [W3C-20150203]で送信される通知メッセージのフローを開始するようにパブリッシャーに通知します。サブスクリプションURIで2つ以上の同時GETリクエストを行うことはできません。同じURIで現在のGETリクエストがあるときに受信したGETリクエストは、HTTPエラーコード409で拒否する必要があります。
As described in Section 6.4 of [RFC8040], RESTCONF servers SHOULD NOT send the "event" or "id" fields in the SSE event notifications.
[RFC8040]のセクション6.4で説明されているように、RESTCONFサーバーはSSEイベント通知の「イベント」または「ID」フィールドを送信しないでください。
+--------------+ +--------------+
| Subscriber | | Publisher |
| | | |
| Logical | | Logical |
| Connection | | Connection |
| (a) (b) | | (a) (b) |
+--------------+ +--------------+
| RESTCONF POST (RPC:establish-subscription) |
|--------------------------------------------->|
| HTTP 200 OK (ID,URI)|
|<---------------------------------------------|
| |HTTP GET (URI) |
| |--------------------------------------------->|
| | HTTP 200 OK|
| |<---------------------------------------------|
| | SSE (notif-message)|
| |<---------------------------------------------|
| RESTCONF POST (RPC:modify-subscription) | |
|--------------------------------------------->| |
| | HTTP 200 OK| |
|<---------------------------------------------| |
| | SSE (subscription-modified)|
| |<------------------------------------------(c)|
| | SSE (notif-message)|
| |<---------------------------------------------|
| RESTCONF POST (RPC:delete-subscription) | |
|--------------------------------------------->| |
| | HTTP 200 OK| |
|<---------------------------------------------| |
| | | |
| | | |
(a) (b) (a) (b)
Figure 1: Dynamic Subscriptions with Server-Sent Events
図1：サーバー送信イベントを使用した動的サブスクリプション
Additional requirements for dynamic subscriptions over SSE include:
SSEを介した動的サブスクリプションの追加要件は次のとおりです。
* A publisher MUST return all subscription state notifications in a separate SSE message used by the subscription to which the state change refers.
* パブリッシャーは、すべてのサブスクリプション状態通知を、状態変更が参照するサブスクリプションで使用される個別のSSEメッセージで返す必要があります。
* Subscription RPCs MUST NOT use the connection currently providing notification messages for that subscription.
* サブスクリプションRPCは、そのサブスクリプションの通知メッセージを現在提供している接続を使用してはなりません（MUST NOT）。
* In addition to an RPC response for a "modify-subscription" RPC traveling over (a), a "subscription-modified" state change notification MUST be sent within (b). This allows the receiver to know exactly when, within the stream of events, the new terms of the subscription have been applied to the notification messages. See arrow (c).
* （a）を移動する「modify-subscription」RPCに対するRPC応答に加えて、（b）内で「subscription-modified」状態変更通知を送信する必要があります。これにより、受信者は、イベントのストリーム内で、サブスクリプションの新しい条件が通知メッセージにいつ適用されたかを正確に知ることができます。矢印（c）を参照してください。
* In addition to any required access permissions (e.g., Network Configuration Access Control Model (NACM)), the RPCs "modify-subscription", "resync-subscription", and "delete-subscription" SHOULD only be allowed by the same RESTCONF username [RFC8040] that invoked "establish-subscription". Such a restriction generally serves to preserve users' privacy, but exceptions might be made for administrators that may need to modify or delete other users' subscriptions.
* 必要なアクセス許可（ネットワーク構成アクセス制御モデル（NACM）など）に加えて、RPCの「変更サブスクリプション」、「再同期サブスクリプション」、および「削除サブスクリプション」は、同じRESTCONFユーザー名でのみ許可する必要があります[ RFC8040]は、「確立サブスクリプション」を呼び出しました。通常、このような制限はユーザーのプライバシーを保護するのに役立ちますが、他のユーザーのサブスクリプションを変更または削除する必要がある管理者には例外が発生する場合があります。
* The "kill-subscription" RPC can be invoked by any RESTCONF username with the required administrative permissions.
* 「kill-subscription」RPCは、必要な管理権限を持つRESTCONFユーザー名によって呼び出すことができます。
A publisher MUST terminate a subscription in the following cases:
次の場合、パブリッシャーはサブスクリプションを終了する必要があります。
* Receipt of a "delete-subscription" or a "kill-subscription" RPC for that subscription
* そのサブスクリプションの「delete-subscription」または「kill-subscription」RPCの受信
* Loss of TLS heartbeat
* TLSハートビートの喪失
A publisher MAY terminate a subscription at any time as stated in Section 1.3 of [RFC8639].
[RFC8639]のセクション1.3に記載されているように、パブリッシャーはいつでもサブスクリプションを終了することができます。
Qos treatment for event streams is described in Section 2.3 of [RFC8639]. In addition, if HTTP/2 is used, the publisher MUST:
イベントストリームのQoS処理については、[RFC8639]のセクション2.3で説明されています。さらに、HTTP / 2が使用されている場合、パブリッシャーは以下を実行する必要があります。
* Take the "weighting" leaf node in [RFC8639] and copy it into the HTTP/2 stream weight, Section 5.3 of [RFC7540], and
* [RFC8639]の「重み付け」リーフノードを取得し、[RFC7540]のセクション5.3のHTTP / 2ストリームウェイトにコピーします。
* Take any existing subscription "dependency", as specified by the "dependency" leaf node in [RFC8639], and use the HTTP/2 stream for the parent subscription as the HTTP/2 stream dependency (as described in Section 5.3.1 of [RFC7540]) of the dependent subscription.
* [RFC8639]の「依存関係」リーフノードで指定されている既存のサブスクリプションの「依存関係」を取得し、親サブスクリプションのHTTP / 2ストリームをHTTP / 2ストリーム依存関係として使用します（[ RFC7540]）の従属サブスクリプション。
* Set the exclusive flag (Section 5.3.1 of [RFC7540]) to 0.
* 排他フラグ（[RFC7540]のセクション5.3.1）を0に設定します。
For dynamic subscriptions with the same Differentiated Services Code Point (DSCP) value to a specific publisher, it is recommended that the subscriber sends all URI GET requests on a common HTTP/2 session (if HTTP/2 is used). Conversely, a subscriber cannot use a common HTTP/2 session for subscriptions with different DSCP values.
特定のパブリッシャーに対して同じDiffServコードポイント（DSCP）値を持つ動的サブスクリプションの場合、サブスクライバーが共通のHTTP / 2セッションですべてのURI GET要求を送信することをお勧めします（HTTP / 2が使用されている場合）。逆に、サブスクライバーは、異なるDSCP値を持つサブスクリプションに共通のHTTP / 2セッションを使用できません。
Notification messages transported over RESTCONF will be encoded according to [RFC8040], Section 6.4.
RESTCONFを介して転送される通知メッセージは、[RFC8040]のセクション6.4に従ってエンコードされます。
The YANG module defined in Section 7 has one leaf that augments three nodes of [RFC8639].
セクション7で定義されているYANGモジュールには、[RFC8639]の3つのノードを補強する1つのリーフがあります。
module: ietf-restconf-subscribed-notifications
augment /sn:establish-subscription/sn:output:
+--ro uri? inet:uri
augment /sn:subscriptions/sn:subscription:
+--ro uri? inet:uri
augment /sn:subscription-modified:
+--ro uri? inet:uri
This module references [RFC8639].
このモジュールは[RFC8639]を参照します。
<CODE BEGINS>
file "ietf-restconf-subscribed-notifications@2019-11-17.yang"
module ietf-restconf-subscribed-notifications {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:"
+ "ietf-restconf-subscribed-notifications";
prefix rsn;
import ietf-subscribed-notifications {
prefix sn;
}
import ietf-inet-types {
prefix inet;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Editor: Eric Voit
<mailto:evoit@cisco.com>
Editor: Alexander Clemm
<mailto:ludwig@clemm.org>
Editor: Reshad Rahman <mailto:rrahman@cisco.com>"; description "Defines RESTCONF as a supported transport for subscribed event notifications.
エディター：Reshad Rahman <mailto：rrahman@cisco.com> ";説明" RESTCONFを、サブスクライブされたイベント通知でサポートされるトランスポートとして定義します。
Copyright (c) 2019 IETF Trust and the persons identified as authors of the code. All rights reserved.
Copyright（c）2019 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 (https://trustee.ietf.org/license-info).
ソースおよびバイナリ形式での再配布および使用は、変更の有無にかかわらず、IETF文書に関連するIETFトラストの法的規定のセクション4.cに記載されているSimplified BSD Licenseに従い、それに含まれるライセンス条項に従って許可されます（ https://trustee.ietf.org/license-info）。
This version of this YANG module is part of RFC 8650; see the RFC itself for full legal notices.";
このYANGモジュールのこのバージョンはRFC 8650の一部です。完全な法的通知については、RFC自体を参照してください。 ";
revision 2019-11-17 {
description
"Initial version";
reference
"RFC 8650: Dynamic Subscription to YANG Events and Datastores
over RESTCONF";
}
grouping uri {
description
"Provides a reusable description of a URI.";
leaf uri {
type inet:uri;
config false;
description
"Location of a subscription-specific URI on the publisher.";
}
}
augment "/sn:establish-subscription/sn:output" {
description
"This augmentation allows RESTCONF-specific parameters for a
response to a publisher's subscription request.";
uses uri;
}
augment "/sn:subscriptions/sn:subscription" {
description
"This augmentation allows RESTCONF-specific parameters to be
exposed for a subscription.";
uses uri;
}
augment "/sn:subscription-modified" {
description
"This augmentation allows RESTCONF-specific parameters to be
included as part of the notification that a subscription has
been modified.";
uses uri;
}
}
<CODE ENDS>
This document registers the following namespace URI in the "ns" subregistry of the "IETF XML Registry" [RFC3688]:
このドキュメントは、「IETF XMLレジストリ」[RFC3688]の「ns」サブレジストリに次の名前空間URIを登録します。
URI:
urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications
Registrant Contact: The IESG.
登録者の連絡先：IESG。
XML: N/A; the requested URI is an XML namespace.
XML：なし。要求されたURIはXML名前空間です。
This document registers the following YANG module in the "YANG Module Names" registry [RFC6020]:
このドキュメントでは、「YANGモジュール名」レジストリ[RFC6020]に次のYANGモジュールを登録しています。
Name: ietf-restconf-subscribed-notifications
名前：ietf-restconf-subscribed-notifications
Namespace:
urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications
Prefix: rsn
プレフィックス：rsn
Reference: RFC 8650
リファレンス：RFC 8650
The YANG module specified in this document defines a schema for data that is designed to be accessed via network management transports such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446].
このドキュメントで指定されているYANGモジュールは、NETCONF [RFC6241]やRESTCONF [RFC8040]などのネットワーク管理トランスポートを介してアクセスするように設計されたデータのスキーマを定義します。最下層のNETCONF層はセキュアなトランスポート層であり、実装に必須のセキュアなトランスポートはセキュアシェル（SSH）[RFC6242]です。最下位のRESTCONFレイヤーはHTTPSであり、実装に必須のセキュアなトランスポートはTLS [RFC8446]です。
The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.
ネットワーク構成アクセス制御モデル（NACM）[RFC8341]は、特定のNETCONFまたはRESTCONFユーザーのアクセスを、利用可能なすべてのNETCONFまたはRESTCONFプロトコル操作およびコンテンツの事前構成されたサブセットに制限する手段を提供します。
The one new data node introduced in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control read access (e.g., via get, get-config, or notification) to this data node. These are the subtrees and data nodes and their sensitivity/vulnerability:
このYANGモジュールで導入された1つの新しいデータノードは、一部のネットワーク環境では機密または脆弱であると見なされる場合があります。したがって、このデータノードへの読み取りアクセスを制御することが重要です（たとえば、get、get-config、または通知を介して）。これらは、サブツリーとデータノード、およびそれらの機密性/脆弱性です。
Container: "/subscriptions"
コンテナ：「/ subscriptions」
* "uri": leaf will show where subscribed resources might be located on a publisher. Access control must be set so that only someone with proper access permissions, i.e., the same RESTCONF [RFC8040] user credentials that invoked the corresponding "establish-subscription", has the ability to access this resource.
* 「uri」：リーフは、サブスクライブされたリソースがパブリッシャーのどこにあるかを示します。適切なアクセス許可を持つユーザー、つまり、対応する「establish-subscription」を呼び出した同じRESTCONF [RFC8040]ユーザー資格情報を持つユーザーのみがこのリソースにアクセスできるように、アクセス制御を設定する必要があります。
The subscription URI is implementation specific and is encrypted via the use of TLS. Therefore, even if an attacker succeeds in guessing the subscription URI, a RESTCONF username [RFC8040] with the required administrative permissions must be used to be able to access or modify that subscription. It is recommended that the subscription URI values not be easily predictable.
サブスクリプションURIは実装固有であり、TLSを使用して暗号化されます。したがって、攻撃者がサブスクリプションURIの推測に成功した場合でも、そのサブスクリプションにアクセスまたは変更するには、必要な管理権限を持つRESTCONFユーザー名[RFC8040]を使用する必要があります。サブスクリプションURI値を簡単に予測できないようにすることをお勧めします。
The access permission considerations for the RPCs "modify-subscription", "resync-subscription", "delete-subscription", and "kill-subscription" are described in Section 3.4.
RPC「modify-subscription」、「resync-subscription」、「delete-subscription」、および「kill-subscription」のアクセス許可に関する考慮事項については、3.4節で説明します。
If a buggy or compromised RESTCONF subscriber sends a number of "establish-subscription" requests, then these subscriptions accumulate and may use up system resources. In such a situation, the publisher MAY also suspend or terminate a subset of the active subscriptions from that RESTCONF subscriber in order to reclaim resources and preserve normal operation for the other subscriptions.
バギーまたは侵害されたRESTCONFサブスクライバーがいくつかの「確立サブスクリプション」要求を送信すると、これらのサブスクリプションが蓄積し、システムリソースを使い果たす可能性があります。このような状況では、パブリッシャーは、リソースを再利用して他のサブスクリプションの通常の操作を維持するために、そのRESTCONFサブスクライバーからのアクティブなサブスクリプションのサブセットを一時停止または終了する場合があります。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC2119] Bradner、S。、「要件レベルを示すためにRFCで使用するキーワード」、BCP 14、RFC 2119、DOI 10.17487 / RFC2119、1997年3月、<https://www.rfc-editor.org/info/ rfc2119>。
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.
[RFC3688] Mealling、M。、「The IETF XML Registry」、BCP 81、RFC 3688、DOI 10.17487 / RFC3688、2004年1月、<https://www.rfc-editor.org/info/rfc3688>。
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.
[RFC6020] Bjorklund、M。、編、「YANG-ネットワーク構成プロトコル（NETCONF）のデータモデリング言語」、RFC 6020、DOI 10.17487 / RFC6020、2010年10月、<https：//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, <https://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月、<https://www.rfc-editor.org/info/rfc6241>。
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.
[RFC6242] Wasserman、M。、「Using the NETCONF Protocol over Secure Shell（SSH）」、RFC 6242、DOI 10.17487 / RFC6242、2011年6月、<https://www.rfc-editor.org/info/rfc6242>。
[RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) Heartbeat Extension", RFC 6520, DOI 10.17487/RFC6520, February 2012, <https://www.rfc-editor.org/info/rfc6520>.
[RFC6520] Seggelmann、R.、Tuexen、M。、およびM. Williams、「Transport Layer Security（TLS）and Datagram Transport Layer Security（DTLS）Heartbeat Extension」、RFC 6520、DOI 10.17487 / RFC6520、2012年2月、<https ：//www.rfc-editor.org/info/rfc6520>。
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, May 2015, <https://www.rfc-editor.org/info/rfc7540>.
[RFC7540] Belshe、M.、Peon、R。、およびM. Thomson、編、「Hypertext Transfer Protocol Version 2（HTTP / 2）」、RFC 7540、DOI 10.17487 / RFC7540、2015年5月、<https：// www.rfc-editor.org/info/rfc7540>。
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
[RFC8040] Bierman、A.、Bjorklund、M。、およびK. Watsen、「RESTCONFプロトコル」、RFC 8040、DOI 10.17487 / RFC8040、2017年1月、<https://www.rfc-editor.org/info/rfc8040 >。
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8174] Leiba、B。、「RFC 2119キーワードの大文字と小文字のあいまいさ」、BCP 14、RFC 8174、DOI 10.17487 / RFC8174、2017年5月、<https://www.rfc-editor.org/info/ rfc8174>。
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.
[RFC8341] Bierman、A。およびM. Bjorklund、「Network Configuration Access Control Model」、STD 91、RFC 8341、DOI 10.17487 / RFC8341、2018年3月、<https://www.rfc-editor.org/info/rfc8341 >。
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.
[RFC8342] Bjorklund、M.、Schoenwaelder、J.、Shafer、P.、Watsen、K。、およびR. Wilton、「Network Management Datastore Architecture（NMDA）」、RFC 8342、DOI 10.17487 / RFC8342、2018年3月、< https://www.rfc-editor.org/info/rfc8342>。
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8446] Rescorla、E。、「The Transport Layer Security（TLS）Protocol Version 1.3」、RFC 8446、DOI 10.17487 / RFC8446、2018年8月、<https://www.rfc-editor.org/info/rfc8446>。
[RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, "Subscription to YANG Notifications", RFC 8639, DOI 10.17487/RFC8639, September 2019, <https://www.rfc-editor.org/info/rfc8639>.
[RFC8639] Voit、E.、Clemm、A.、Gonzalez Prieto、A.、Nilsen-Nygaard、E。、およびA. Tripathy、「Subscription to YANG Notifications」、RFC 8639、DOI 10.17487 / RFC8639、2019年9月、< https://www.rfc-editor.org/info/rfc8639>。
[RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, September 2019, <https://www.rfc-editor.org/info/rfc8641>.
[RFC8641] Clemm、A。およびE. Voit、「データストア更新のためのYANG通知のサブスクリプション」、RFC 8641、DOI 10.17487 / RFC8641、2019年9月、<https://www.rfc-editor.org/info/rfc8641> 。
[W3C-20150203] Hickson, I., "Server-Sent Events", W3C Recommendation, 3 February 2015, <https://www.w3.org/TR/2015/REC-eventsource-20150203/>. Latest version available at <https://www.w3.org/TR/ eventsource/>.
[W3C-20150203] Hickson、I。、「Server-Sent Events」、W3C勧告、2015年2月3日、<https://www.w3.org/TR/2015/REC-eventsource-20150203/>。 <https://www.w3.org/TR/eventsource/>で入手可能な最新バージョン。
[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, <https://www.rfc-editor.org/info/rfc7231>.
[RFC7231]フィールディング、R。、エド。およびJ. Reschke編、「Hypertext Transfer Protocol（HTTP / 1.1）：Semantics and Content」、RFC 7231、DOI 10.17487 / RFC7231、2014年6月、<https://www.rfc-editor.org/info/rfc7231 >。
[RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements for Subscription to YANG Datastores", RFC 7923, DOI 10.17487/RFC7923, June 2016, <https://www.rfc-editor.org/info/rfc7923>.
[RFC7923] Voit、E.、Clemm、A。、およびA. Gonzalez Prieto、「YANG Datastoresへのサブスクリプションの要件」、RFC 7923、DOI 10.17487 / RFC7923、2016年6月、<https：//www.rfc-editor。 org / info / rfc7923>。
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>.
[RFC7951] Lhotka、L。、「YANGでモデル化されたデータのJSONエンコーディング」、RFC 7951、DOI 10.17487 / RFC7951、2016年8月、<https://www.rfc-editor.org/info/rfc7951>。
[RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. Zhang, "A YANG Data Model for the Virtual Router Redundancy Protocol (VRRP)", RFC 8347, DOI 10.17487/RFC8347, March 2018, <https://www.rfc-editor.org/info/rfc8347>.
[RFC8347] Liu、X.、Ed。、Kyparlis、A.、Parikh、R.、Lindem、A.、and M. Zhang、 "A YANG Data Model for the Virtual Router Redundancy Protocol（VRRP）"、RFC 8347、 DOI 10.17487 / RFC8347、2018年3月、<https://www.rfc-editor.org/info/rfc8347>。
[RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "RESTCONF Extensions to Support the Network Management Datastore Architecture", RFC 8527, DOI 10.17487/RFC8527, March 2019, <https://www.rfc-editor.org/info/rfc8527>.
[RFC8527] Bjorklund、M.、Schoenwaelder、J.、Shafer、P.、Watsen、K。、およびR. Wilton、「RESTCONF Extensions to Support the Network Management Datastore Architecture」、RFC 8527、DOI 10.17487 / RFC8527、2019年3月、<https://www.rfc-editor.org/info/rfc8527>。
[RFC8640] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, "Dynamic Subscription to YANG Events and Datastores over NETCONF", RFC 8640, DOI 10.17487/RFC8640, September 2019, <https://www.rfc-editor.org/info/rfc8640>.
[RFC8640] Voit、E.、Clemm、A.、Gonzalez Prieto、A.、Nilsen-Nygaard、E.、A。Tripathy、「NETCONFを介したYANGイベントとデータストアへの動的サブスクリプション」、RFC 8640、DOI 10.17487 / RFC8640 、2019年9月、<https://www.rfc-editor.org/info/rfc8640>。
[XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", W3C Recommendation, 16 November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>. Latest version available at <https://www.w3.org/TR/ xpath/>.
[XPATH]クラーク、J。およびS.デローズ、「XMLパス言語（XPath）バージョン1.0」、W3C勧告、1999年11月16日、<http://www.w3.org/TR/1999/REC-xpath-19991116 >。 <https://www.w3.org/TR/xpath/>で入手可能な最新バージョン。
This section is non-normative. To allow easy comparison, this section mirrors the functional examples shown with NETCONF over XML within [RFC8640]. In addition, HTTP/2 vs HTTP/1.1 headers are not shown as the contents of the JSON encoded objects are identical within.
このセクションは非規範的です。簡単に比較できるように、このセクションでは、[RFC8640]内のNETCONF over XMLで示された機能例を反映しています。さらに、JSONエンコードされたオブジェクトのコンテンツは内部で同一であるため、HTTP / 2とHTTP / 1.1のヘッダーは表示されません。
The subscription URI values used in the examples in this section are purely illustrative, and are not indicative of the expected usage that is described in Section 9.
このセクションの例で使用されているサブスクリプションURI値は純粋に例示であり、セクション9で説明されている予想される使用法を示すものではありません。
The DSCP values are only for example purposes and are all indicated in decimal since the encoding is JSON [RFC7951].
エンコーディングはJSON [RFC7951]であるため、DSCP値は単なる例であり、すべて10進数で示されています。
The following figure shows two successful "establish-subscription" RPC requests as per [RFC8639]. The first request is given a subscription identifier of 22, and the second, an identifier of 23.
次の図は、[RFC8639]による2つの成功した「確立サブスクリプション」RPC要求を示しています。最初のリクエストにはサブスクリプション識別子22が与えられ、2番目のリクエストには識別子23が与えられます。
+------------+ +-----------+
| Subscriber | | Publisher |
+------------+ +-----------+
| |
|establish-subscription |
|------------------------------>| (a)
| HTTP 200 OK, id#22, URI#1 |
|<------------------------------| (b)
|GET (URI#1) |
|------------------------------>| (c)
| HTTP 200 OK,notif-mesg (id#22)|
|<------------------------------|
| |
| |
|establish-subscription |
|------------------------------>|
| HTTP 200 OK, id#23, URI#2|
|<------------------------------|
|GET (URI#2) |
|------------------------------>|
| |
| |
| notif-mesg (id#22)|
|<------------------------------|
| HTTP 200 OK,notif-mesg (id#23)|
|<------------------------------|
| |
Figure 2: Multiple Subscriptions over RESTCONF/HTTP
図2：RESTCONF / HTTPを介した複数のサブスクリプション
To provide examples of the information being transported, example messages for interactions in Figure 2 are detailed below:
転送される情報の例を提供するために、図2の相互作用のメッセージ例を以下に示します。
POST /restconf/operations
/ietf-subscribed-notifications:establish-subscription
{
"ietf-subscribed-notifications:input": {
"stream-xpath-filter": "/example-module:foo/",
"stream": "NETCONF",
"dscp": 10
}
}
Figure 3: "establish-subscription" Request (a)
図3：「サブスクリプションの確立」リクエスト（a）
As the publisher was able to fully satisfy the request, the publisher sends the subscription identifier of the accepted subscription and the URI:
パブリッシャーはリクエストを完全に満たすことができたので、パブリッシャーは受け入れられたサブスクリプションのサブスクリプション識別子とURIを送信します。
HTTP status code - 200
HTTPステータスコード-200
{
"id": 22,
"uri": "https://example.com/restconf/subscriptions/22"
}
Figure 4: "establish-subscription" Success (b)
図4：「サブスクリプションのサブスクリプション」の成功（b）
Upon receipt of the successful response, the subscriber does a GET to the provided URI to start the flow of notification messages. When the publisher receives this, the subscription is moved to the active state (c).
成功した応答を受信すると、サブスクライバーは提供されたURIに対してGETを実行して、通知メッセージのフローを開始します。パブリッシャーがこれを受け取ると、サブスクリプションはアクティブ状態（c）に移行します。
GET /restconf/subscriptions/22
Figure 5: "establish-subscription" Subsequent POST
図5：「establish-subscription」の後続のPOST
While not shown in Figure 2, if the publisher had not been able to fully satisfy the request, or the subscriber has no authorization to establish the subscription, the publisher would have sent an RPC error response. For instance, if the "dscp" value of 10 asserted by the subscriber in Figure 3 proved unacceptable, the publisher may have returned:
図2には示されていませんが、パブリッシャーが要求を完全に満たせなかった場合、またはサブスクライバーにサブスクリプションを確立する権限がない場合、パブリッシャーはRPCエラー応答を送信します。たとえば、図3のサブスクライバーによってアサートされた「dscp」値10が受け入れられない場合、パブリッシャーは次のように返した可能性があります。
HTTP status code - 400
HTTPステータスコード-400
{ "ietf-restconf:errors" : {
"error" : [
{
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag":
"ietf-subscribed-notifications:dscp-unavailable"
}
]
}
}
Figure 6: An Unsuccessful "establish-subscription"
図6：失敗した「確立サブスクリプション」
The subscriber can use this information in future attempts to establish a subscription.
サブスクライバーは、サブスクリプションを確立するための将来の試みでこの情報を使用できます。
An existing subscription may be modified. The following exchange shows a negotiation of such a modification via several exchanges between a subscriber and a publisher. This negotiation consists of a failed RPC modification request/response followed by a successful one.
既存のサブスクリプションは変更される場合があります。次のエクスチェンジは、サブスクライバーとパブリッシャー間のいくつかのエクスチェンジを介したこのような変更のネゴシエーションを示しています。このネゴシエーションは、RPC変更要求/応答が失敗した後に成功したもので構成されます。
+------------+ +-----------+
| Subscriber | | Publisher |
+------------+ +-----------+
| |
| notification message (id#23)|
|<-----------------------------|
| |
|modify-subscription (id#23) |
|----------------------------->| (d)
| HTTP 400 error (with hint)|
|<-----------------------------| (e)
| |
|modify-subscription (id#23) |
|----------------------------->|
| HTTP 200 OK |
|<-----------------------------|
| |
| notif-mesg (id#23)|
|<-----------------------------|
| |
Figure 7: Interaction Model for Successful Subscription Modification
図7：サブスクリプションを正常に変更するための相互作用モデル
If the subscription being modified in Figure 7 is a datastore subscription as per [RFC8641], the modification request made in (d) may look like that shown in Figure 8. As can be seen, the modifications being attempted are the application of a new XML Path Language (XPath) filter as well as the setting of a new periodic time interval.
図7で変更されているサブスクリプションが[RFC8641]のデータストアサブスクリプションである場合、（d）で行われた変更要求は、図8に示すようになる可能性があります。 XMLパス言語（XPath）フィルター、および新しい定期的な時間間隔の設定。
POST /restconf/operations
/ietf-subscribed-notifications:modify-subscription
{
"ietf-subscribed-notifications:input": {
"id": 23,
"ietf-yang-push:datastore-xpath-filter":
"/example-module:foo/example-module:bar",
"ietf-yang-push:periodic": {
"ietf-yang-push:period": 500
}
}
}
Figure 8: Subscription Modification Request (c)
図8：サブスクリプション変更リクエスト（c）
If the publisher can satisfy both changes, the publisher sends a positive result for the RPC. If the publisher cannot satisfy either of the proposed changes, the publisher sends an RPC error response (e). The following is an example RPC error response for (e) that includes a hint. This hint is an alternative time period value that might have resulted in a successful modification:
パブリッシャーが両方の変更を満たすことができる場合、パブリッシャーはRPCの肯定的な結果を送信します。パブリッシャーが提案された変更のいずれかを満たすことができない場合、パブリッシャーはRPCエラー応答を送信します（e）。ヒントを含む（e）のRPCエラー応答の例を次に示します。このヒントは、変更が成功した可能性のある別の期間値です。
HTTP status code - 400
HTTPステータスコード-400
{ "ietf-restconf:errors" : {
"error" : [
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag": "ietf-yang-push:period-unsupported",
"error-info": {
"ietf-yang-push":
"modify-subscription-datastore-error-info": {
"period-hint": 3000
}
}
]
}
}
Figure 9: "modify-subscription" Failure with Hint (e)
図9：ヒント付きの「変更サブスクリプション」の失敗（e）
The following demonstrates deleting a subscription. This subscription may have been to either a stream or a datastore.
以下は、サブスクリプションの削除を示しています。このサブスクリプションは、ストリームまたはデータストアのいずれかであった可能性があります。
POST /restconf/operations
/ietf-subscribed-notifications:delete-subscription
{
"delete-subscription": {
"id": "22"
}
}
Figure 10: "delete-subscription" Request
図10：「サブスクリプションの削除」リクエスト
If the publisher can satisfy the request, the publisher replies with success to the RPC request.
パブリッシャーが要求を満たすことができる場合、パブリッシャーはRPC要求に成功で応答します。
If the publisher cannot satisfy the request, the publisher sends an <rpc-error> element indicating the modification didn't work. Figure 11 shows a valid response for an existing valid subscription identifier, but that subscription identifier was created on a different transport session:
パブリッシャーが要求を満たせない場合、パブリッシャーは変更が機能しなかったことを示す<rpc-error>要素を送信します。図11は、既存の有効なサブスクリプション識別子に対する有効な応答を示していますが、そのサブスクリプション識別子は別のトランスポートセッションで作成されています。
HTTP status code - 404
HTTPステータスコード-404
{
"ietf-restconf:errors" : {
"error" : [
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag":
"ietf-subscribed-notifications:no-such-subscription"
]
}
}
Figure 11: Unsuccessful "delete-subscription"
図11：失敗した「サブスクリプションの削除」
A publisher will send subscription state notifications according to the definitions within [RFC8639].
パブリッシャーは、[RFC8639]内の定義に従ってサブスクリプション状態通知を送信します。
A "subscription-modified" encoded in JSON would look like:
JSONでエンコードされた「サブスクリプション変更」は次のようになります。
{
"ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-modified": {
"id": 39,
"uri": "https://example.com/restconf/subscriptions/22"
"stream-xpath-filter": "/example-module:foo",
"stream": {
"ietf-netconf-subscribed-notifications" : "NETCONF"
}
}
}
}
Figure 12: "subscription-modified" Subscription State Notification
図12：「サブスクリプションが変更された」サブスクリプション状態通知
A.2.2. "subscription-completed", "subscription-resumed", and "replay-completed"
A.2.2. 「subscription-completed」、「subscription-resumed」、および「replay-completed」
A "subscription-completed" notification would look like:
「サブスクリプション完了」通知は次のようになります。
{
"ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-completed": {
"id": 39,
}
}
}
Figure 13: "subscription-completed" Notification in JSON
図13：JSONでの「サブスクリプション完了」通知
The "subscription-resumed" and "replay-complete" are virtually identical, with "subscription-completed" simply being replaced by "subscription-resumed" and "replay-complete".
「subscription-resumed」と「replay-complete」は実質的に同じですが、「subscription-completed」は単に「subscription-resumed」と「replay-complete」に置き換えられます。
A "subscription-terminated" would look like:
「サブスクリプション終了」は次のようになります。
{
"ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-terminated": {
"id": 39,
"error-id": "suspension-timeout"
}
}
}
Figure 14: "subscription-terminated" Subscription State Notification
図14：「サブスクリプション終了」サブスクリプション状態通知
The "subscription-suspended" is virtually identical, with "subscription-terminated" simply being replaced by "subscription-suspended".
「サブスクリプションの一時停止」は実質的に同一であり、「サブスクリプション終了」は単に「サブスクリプションの一時停止」に置き換えられます。
This section provides an example that illustrates the method of filtering event record contents. The example is based on the YANG notification "vrrp-protocol-error-event" as defined per the ietf-vrrp.yang module within [RFC8347]. Event records based on this specification that are generated by the publisher might appear as:
このセクションでは、イベントレコードのコンテンツをフィルタリングする方法を示す例を示します。この例は、[RFC8347]内のietf-vrrp.yangモジュールで定義されているように、YANG通知「vrrp-protocol-error-event」に基づいています。この仕様に基づいて発行元によって生成されたイベントレコードは、次のように表示されます。
data: {
data: "ietf-restconf:notification" : {
data: "eventTime" : "2018-09-14T08:22:33.44Z",
data: "ietf-vrrp:vrrp-protocol-error-event" : {
data: "protocol-error-reason" : "checksum-error"
data: }
data: }
data: }
Figure 15: RFC 8347 (VRRP) - Example Notification
図15：RFC 8347（VRRP）-通知の例
Suppose a subscriber wanted to establish a subscription that only passes instances of event records where there is a "checksum-error" as part of a Virtual Router Redundancy Protocol (VRRP) protocol event. Also assume the publisher places such event records into the NETCONF stream. To get a continuous series of matching event records, the subscriber might request the application of an XPath filter against the NETCONF stream. An "establish-subscription" RPC to meet this objective might be:
サブスクライバーが、仮想ルーター冗長プロトコル（VRRP）プロトコルイベントの一部として「チェックサムエラー」があるイベントレコードのインスタンスのみを渡すサブスクリプションを確立したいとします。また、発行者がそのようなイベントレコードをNETCONFストリームに配置するとします。連続する一連の一致するイベントレコードを取得するには、サブスクライバーがNETCONFストリームに対してXPathフィルターの適用を要求する場合があります。この目標を達成するための「確立サブスクリプション」RPCは次のようになります。
POST /restconf/operations
/ietf-subscribed-notifications:establish-subscription
{
"ietf-subscribed-notifications:input": {
"stream": "NETCONF",
"stream-xpath-filter":
"/ietf-vrrp:vrrp-protocol-error-event[
protocol-error-reason='checksum-error']/",
}
}
Figure 16: Establishing a Subscription Error Reason via XPath
図16：XPathによるサブスクリプションエラーの理由の確立
For more examples of XPath filters, see [XPATH].
XPathフィルターのその他の例については、[XPATH]を参照してください。
Suppose the "establish-subscription" in Figure 16 was accepted. And suppose later a subscriber decided they wanted to broaden this subscription cover to all VRRP protocol events (i.e., not just those with a "checksum error"). The subscriber might attempt to modify the subscription in a way that replaces the XPath filter with a subtree filter that sends all VRRP protocol events to a subscriber. Such a "modify-subscription" RPC might look like:
図16の「establish-subscription」が受け入れられたとします。そして、後でサブスクライバーがこのサブスクリプションカバーをすべてのVRRPプロトコルイベント（つまり、「チェックサムエラー」のあるイベントだけではない）に広げたいと決定したとします。サブスクライバーは、XPathフィルターをすべてのVRRPプロトコルイベントをサブスクライバーに送信するサブツリーフィルターに置き換える方法で、サブスクリプションを変更しようとする場合があります。このような「変更サブスクリプション」RPCは次のようになります。
POST /restconf/operations
/ietf-subscribed-notifications:modify-subscription
{
"ietf-subscribed-notifications:input": {
"stream": "NETCONF",
"stream-subtree-filter": {
"/ietf-vrrp:vrrp-protocol-error-event" : {}
}
}
}
Figure 17: Example "modify-subscription" RPC
図17：「modify-subscription」RPCの例
For more examples of subtree filters, see [RFC6241], Section 6.4.
サブツリーフィルタのその他の例については、[RFC6241]のセクション6.4をご覧ください。
Acknowledgments
謝辞
We wish to acknowledge the helpful contributions, comments, and suggestions that were received from Ambika Prasad Tripathy, Alberto Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu, and Robert Wilton.
Ambika Prasad Tripathy、Alberto Gonzalez Prieto、Susan Hares、Tim Jenkins、Balazs Lengyel、Kent Watsen、Michael Scharf、Guangying Zheng、Martin Bjorklund、Qin Wu、Robertから寄せられた有益な貢献、コメント、提案に感謝いたしますウィルトン。
Authors' Addresses
著者のアドレス
Eric Voit Cisco Systems
Eric Voit Cisco Systems
Email: evoit@cisco.com
Reshad Rahman Cisco Systems
Reshad Rehman Cisco Systems
Email: rrahman@cisco.com
Einar Nilsen-Nygaard Cisco Systems
Einar Nilsen-Nygaard Cisco Systems
Email: einarnn@cisco.com
Alexander Clemm Futurewei
アレクサンダークレムフューチャーウェイ
Email: ludwig@clemm.org
Andy Bierman YumaWorks
アンディ・ビアマンYumaWorks
Email: andy@yumaworks.com