はじめに
Crossworkに実装されている機能について、REST API からの使用が可能となっています。下記 URLのマニュアルでは、Postman を使用した方法が紹介しておりますが、これはWindowsなどのGUI環境が必要となりますので、CLI 環境で使用する例を提示したいと思います。
https://developer.cisco.com/docs/crosswork/#!getting-started
API のリファレンスマニュアル
Crossworkで使用可能な API は、以下にのページに詳細が公開されています。
https://developer.cisco.com/docs/crosswork/
左側フレームより確認したい機能を選ぶと、右側フレームでそれぞれの endpoint URL とパスやパラメータを確認出来ます。複数バージョンが選択できる場合は、以下を参照して正しい API を確認してください。
| コンポーネント |
CNC バージョン |
API バージョン |
| Crosswork Infrastructure APIs |
3 |
4.1 |
| 4.0 |
4.3 |
| 4.1 |
4.4 |
| Crosswork Health Insights APIs |
3, 4 |
3.x, 4.x |
| Crosswork Data Gatway APIs |
| Crosswork Network Controller APIs |
| Crosswork Optimization Engine APIs |
| Crosswork Service Health APIs |
| Crosswork Zero Touch Provisioning APIs |
ベースURL
全てのAPI使用において、以下のURLをベースとします。使用し易いよう、BASE_URL 環境変数へエクスポートしておきます。
export BASE_URL=https://<Crosswork VIP>:30603/crosswork
認証
API を使用する前に、ユーザ名とパスワードを用いて認証を行う必要があります。
参照: https://developer.cisco.com/docs/crosswork/#!crosswork-infrastructure-apis-4-1-release-apis-authentication-api
チケットの取得
ユーザ名、パスワードは正しいものへ置き換えてください。これによって、アクセスチケットを取得します。
export AUTH_API=/sso/v1
curl -w '\n' -X POST -k ${BASE_URL}${AUTH_API}/tickets \
-d 'username=admin&password=PASSWORD'
TGT-9-7Ixg2UngFZnUX40eDnPA2-gEciunv8jZiPRIV661W0WSOlp5QKDz0TAN4tJi-CqyF3I-cas-1
ここで得られたチケット TGT-9-7Ixg2UngFZnUX40eDnPA2-gEciunv8jZiPRIV661W0WSOlp5QKDz0TAN4tJi-CqyF3I-cas-1を次で使用します。
トークンの取得
curl -w '\n' -X POST -k ${BASE_URL}${AUTH_API}/tickets/TGT-9-7Ixg2UngFZnUX40eDnPA2-gEciunv8jZiPRIV661W0WSOlp5QKDz0TAN4tJi-CqyF3I-cas-1 \
--data-urlencode 'service=https://cw.domain.com/app-dashboard'
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImlzRnJvbU5ld0xvZ2luIjoidHJ1ZSIsInBvbGlj...
得られたトークンを TOKEN 環境変数へエクスポートしておきます。
export TOKEN=eyJhbGciOiJIUzUxMiJ9.eyJz...
API の使用
認証が完了しましたので、トークンを使用して各APIを使用することが出来ます。全ての例を示すことは出来ませんので、いくつか紹介します。
Device Lifecycle Management Inventory API
https://developer.cisco.com/docs/crosswork/#!crosswork-infrastructure-apis-4-1-release-apis-device-lifecycle-management-inventory-api
export DLM_INVENTORY_API=/inventory
登録されているデバイスの数を取得
$ curl -k -H "Authorization: Bearer $TOKEN" "${BASE_URL}${DLM_INVENTORY_API}/v1/nodes/count"
{"number_of_nodes":6}
$
デバイスリストを取得
種々のフィルタを設定して取得が出来ます。limit=0 を指定し、全てのノードを取得しています。
$ curl -k -X POST -H "Authorization: Bearer $TOKEN" "${BASE_URL}${DLM_INVENTORY_API}/v1/nodes/query" -d '{"limit": 0}'
...
$ curl -k -X POST -H "Authorization: Bearer $TOKEN" "${BASE_URL}${DLM_INVENTORY_API}/v1/nodes/query" \
-d '{"limit": 0}' | jq | head -n 10
{
"data": [
{
"uuid": "dd7fb935-5482-4b5e-8d71-3fb015732b7f",
"host_name": "xr-1",
"profile": "device",
"reachability_state": "CONN_STATE_UNKNOWN",
"admin_state": "ROBOT_ADMIN_STATE_UP",
"connectivity_info": [
{
Application Manager API
https://developer.cisco.com/docs/crosswork/#!crosswork-infrastructure-apis-4-1-release-apis-application-manager-api
export APPMAN_API=/platform
インストール済みアプリケーションのメタデータを取得
この例では、CAT (Active Topology), COE (Optmization Engine), Infra (Infrastructure) が入っていることがわかります。
$ curl -k -X POST -H "Authorization: Bearer $TOKEN" "${BASE_URL}/platform/v2/capp/applicationdata/query"
...
$ curl -s -k -X POST -H "Authorization: Bearer $TOKEN" "${BASE_URL}/platform/v2/capp/applicationdata/query" | jq '.application_data_list[] | {application_id, version}'
{
"application_id": "capp-cat",
"version": "3.0.3-rc.11+build.17"
}
{
"application_id": "capp-coe",
"version": "3.1.1-rc.5+build.8"
}
{
"application_id": "capp-infra",
"version": "4.1.4-rc.3+build.1"
}
Optimization Engine APIs
https://developer.cisco.com/docs/crosswork/#!crosswork-optimization-engine-apis-4-0-release-apis-l2-and-l3-topology-details-api
export OPTIMA_API=/nbi/optima/v2/restconf
ネットワーク全体を取得
Default-network に含まれるネットワークの、ノード情報やそれぞれの間のリンク情報が取得出来ます。
$ curl -k -X GET -H "Authorization: Bearer $TOKEN" "${BASE_URL}${OPTIMA_API}/data/ietf-network-state:networks"
...
$ curl -k -X GET -H "Authorization: Bearer $TOKEN" "${BASE_URL}${OPTIMA_API}/data/ietf-network-state:networks" | jq
{
"ietf-network-state:networks": {
"network": [
{
"network-id": "Default-network",
"network-types": {
"ietf-l3-unicast-topology-state:l3-unicast-topology": {
"ietf-sr-mpls-topology-state:sr-mpls": {},
"cisco-crosswork-ospf-topology:ospf": {}
}
},
"ietf-network-topology-state:link": [
{
"link-id": "xr-3 : GigabitEthernet0/0/0/1 : xr-2 : GigabitEthernet0/0/0/1 : IPv4",
"source": {
"source-node": "xr-3",
"source-tp": "GigabitEthernet0/0/0/1"
ランチャー
これらの手続きを、一つのスクリプトに書くと以下のようになります。
$ cat cncapi.sh
BASE_URL=https://<Crosswork VIP>:30603/crosswork
AUTH_API=/sso/v1
DLM_INVENTORY_API=/inventory
APPMAN_API=/platform
OPTIMA_API=/nbi/optima/v2/restconf
USER=admin
PASSWORD=<Password>
TICKET=$(curl -s -k -X POST -k ${BASE_URL}${AUTH_API}/tickets \
-d "username=${USER}&password=${PASSWORD}")
TOKEN=$(curl -s -k -X POST -k ${BASE_URL}${AUTH_API}/tickets/${TICKET} \
--data-urlencode 'service=https://cw.domain.com/app-dashboard')
CURL_POST="curl -k -s -X POST -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json'"
CURL_GET="curl -k -s -X GET -H 'Authorization: Bearer $TOKEN'"
eval $CURL_GET ${BASE_URL}${OPTIMA_API}/data/ietf-network-state:networks
以下のように実行できます。
$ sh cncapi.sh
{ "ietf-network-state:networks":
{ "network": [
{
ただし上記のままでは、都度 TOKEN の取得を行うため非効率です。取得したTOKENをキャッシュし、再利用するようなスクリプトとすることをお勧めします。
