RESTCONF URLにある複数のキーに対処する方法
この記事は、DevNet の Network Programmability Evangelist である Hank Preston によるブログ「How to Deal with Multiple Keys in a RESTCONF URL
」（2021/5/6）の抄訳です。
1 週間で同じ質問が 2 回ポップアップされたことに気付き、そのことを詳しく取り上げる価値があると思いました。私の得意なトピックの 1 つである RESTCONF に関連するものです。それは「Ask Hank」ブログ投稿にはうってつけでした。
この質問は、「DevNet の生徒」（私達みんな？）の1人である Guille さんから Twitter で受け取りました。
「質問です。RESTCONF の URL は、識別子が 2 つある場合、どのように作成したら良いですか?」
この文脈で、「識別子」は、リストのために YANG で定義されたキーを意味します。
回答に取りかかる前に、この質問をただしく理解できていることを確認しましょう。
リストの特定の要素のために RESTCONF URL を作ること
実証されている学習のための YANG モデル、ietf-interfaces.yang に話を戻すと、すべての「interface」は、その「name」によって一意に識別されていることが分かります。
pyang -f tree --tree-path /interfaces/interface ietf-interfaces.yang
module: ietf-interfaces
+--rw interfaces
+--rw interface* [name]
+--rw name string
+--rw description? string
+--rw type identityref
+--rw enabled? boolean
+--rw link-up-down-trap-enable? enumeration {if-mib}?
リーフを囲う角括弧は、それがキーであることを示します。 このように、それ自体が YANG モデルで構成されています。(注：以下の YANG モデルは、簡潔にするために編集されています。 full YANG model on GitHub を参照してください)
container interfaces {
description
"Interface parameters.";
list interface {
key "name";
description
"The list of interfaces on the device.";
leaf name {
type string;
description
"The name of the interface."
}
それでは、URL を作るために、この情報を RESTCONF にどのように使用すれば良いでしょう? 例えば、次の通りです。
curl 'https://sandbox-iosxe-latest-1.cisco.com/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet2' \
--header 'Accept: application/yang-data+json' \
--user developer:C1sco12345
{
"ietf-interfaces:interface": {
"name": "GigabitEthernet2",
"description": "Configured by RESTCONF",
"type": "iana-if-type:ethernetCsmacd",
"enabled": true,
"ietf-ip:ipv4": {
"address": [
{
"ip": "10.255.255.2",
"netmask": "255.255.255.0"
}
]
},
"ietf-ip:ipv6": {
}
}
}
上の例では、等号と、それに続く問題になっているキーの値が、URL に使用されていることを示しています。なかなか単純明快です。
しかし、複数のキーがあるリストではどうでしょうか?
そう、それが問題であることが分かります。もし、複数のキーがあるリストがあったらどうなるでしょうか? 多くのリストではキーが 1 つだけですが、ルートリストに関連する IOS XE Native モデルからの例を考えて見ましょう。
pyang -f tree --tree-path=/native/ip/route Cisco-IOS-XE-native.yang
module: Cisco-IOS-XE-native
+--rw native
+--rw ip
+--rw route
+--rw ip-route-interface-forwarding-list* [prefix mask]
| +--rw prefix inet:ipv4-address
| +--rw mask inet:ipv4-address
| +--rw dhcp? empty
| +--rw metric? uint8
| +--rw fwd-list* [fwd]
| | +--rw fwd union
| | +--rw interface-next-hop* [ip-address]
| | | +--rw ip-address inet:ipv4-address
論理的に考えれば、ルーティングテーブルの入力には、一意に識別できるように、プレフィックスとマスクの両方が必要です。それは、以下をルータ上で構成することが可能であるからです。
ip route 192.168.100.0 255.255.255.0 10.10.10.1
ip route 192.168.100.0 255.255.255.224 172.16.32.1
ここで、「192.168.100.0」のプレフィックスは 2 つの異なるルートと合わせて使用されていますが、1 つのルートにはより長いマスクがあります。YANG モデルは、一意のリスト要素のために、プレフィックスとマスクの両方をキャプチャする、この必要性を反映しています。
しかしながら、このことは RESTCONF URL にどのように反映されているでしょうか? それでは、以下の文書を見てみましょう。そこでは、RESTCONF は RFC8040 を意味します。
セクション 3.5.3リクエスト URI のデータリソース識別子のコード化に、必要とする情報が記されています。
o キーとなるリーフ値が 1 つしかない場合、パスセグメントは
リスト名を取ることにより構築され、それに「＝」記号が続き、
さらに 1 つのキーとなるリーフ値が続きます。
o キーとなるリーフ値が複数ある場合、パスセグメントは
リスト名を取ることにより構築され、「キー」ステートメント
で識別されたそれぞれのリーフの値が続きます。
この値は、YANG「キー」ステートメントで指定された順番でコード化されています。
それぞれのキーとなるリーフ値には、最後の 1 つを除いて、カンマ記号が続きます。
RFC の優れたリソース見つけましたが、それを直接読み取ることは簡単ではないかも知れません。しかし、その例は完璧です。
Examples:
container top {
list list1 {
key "key1 key2 key3";
...
list list2 {
key "key4 key5";
...
leaf X { type string; }
}
}
leaf-list Y {
type uint32;
}
}
For the above YANG definition, the container "top" is defined in the
"example-top" YANG module, and a target resource URI for leaf "X"
would be encoded as follows:
/restconf/data/example-top:top/list1=key1,key2,key3
これが機能する方法のキーとなる部分 はカンマです。URL のキーとなる値をただ普通に区切ります。これを、上述のルーティングモデルに当て嵌めます。
curl 'https://sandbox-iosxe-latest-1.cisco.com/restconf/data/Cisco-IOS-XE-native:native/ip/route/ip-route-interface-forwarding-list=1.1.1.0,255.255.255.0' \
--header 'Accept: application/yang-data+json' \
--user developer:C1sco12345
{
"Cisco-IOS-XE-native:ip-route-interface-forwarding-list": {
"prefix": "1.1.1.0",
"mask": "255.255.255.0",
"fwd-list": [
{
"fwd": "10.10.20.253"
}
]
}
}
まとめ
RESTCONF の使用が、誰にでもより分かりやすく説明ができていれば幸いです。引き続き RESTCONF をもっと掘り下げるには、Ask Hank シリーズの他のブログもチェックすることをお勧めします。いくつかはモデル駆動型プログラマビリティに触れており、実際、1 番目は RESTCONF URL の作成に関することです。そして、もちろんこの投稿の例は、DevNet Always On Sandboxes の 1 つを使用しています。読者を始めとして、誰でも使用できるこの素晴らしい無料リソースで、RESTCONF を遠慮なく探求してください。 RESTCONF を掘り下げたLearning Labsや動画もあり、それらを開いて探求することもできます。
「Ask Hank」に問い合わせたいご質問がありましたら、コメントしていただくか、電子メール (hapresto@cisco.com)、またはツイッター (@hfpreston) で私宛にお知らせください。では、また次回をお楽しみに。
