Categories: Cisco DevNet

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) で私宛にお知らせください。では、また次回をお楽しみに。

Kazumasa Ikuta

シスコシステムズ合同会社 APJアーキテクチャー プリンシパルアーキテクト。2001 年入社。エリア担当 SE、通信事業者担当 SE、SDN応用技術室を経て、2021年よりアジア太平洋地域アーキテクチャーセントラルグループ所属、プリンシパルアーキテクト。主に企業向けのネットワーク運用管理全般および製品、SDNやネットワークプログラマビリティ関連、Cisco DevNetを担当。提案、構築、運用維持管理における技術サポート、本社開発部門と連携したアジア地域での製品や技術のロールアウトプラン策定と実行、対外的なプレゼンテーションなど、仕事を選ばず幅広く活動中。書籍:Ciscoネットワーク構築教科書[解説編](共著)Ciscoネットワーク構築教科書[設定編](共著)Cisco WAN 実践ケーススタディ(共著)