Cisco Crosswork Hierarchical Controller 7.0 NBI および SHQL 参照ガイド

 

Crosswork Hierarchical Controller API の紹介

Cisco Crosswork Hierarchical Controller は、サービスオーケストレータ、OSS、インベントリ システムへのノースバウンド インターフェイスとして、広範な API セットを提供しています。これらの API は、運用ワークフロー、計画シナリオ、管理タスクを自動化するために不可欠なツールです。これらの API を使用して、情報の取得、サービスとリソースのプロビジョニング、ネットワークの構築、通知の登録を行うことができます。

Crosswork Hierarchical Controller は、これらの API に複数のテクノロジーを利用しています。

●        RESTCONF – NETCONF 用に定義された YANG モデルに基づく

●        本文に JSON を含む REST

●        本文に SHQL を含む REST

API アーキテクチャおよびテクノロジー

RESTCONF/YANG プロトコルの紹介

RESTCONF プロトコルは、ネットワーク設定プロトコル（NETCONF）[RFC 6241] で定義され、NMDA [RFC 8342] でさらに拡張されたデータストアの概念を使用して、YANG 1.0 [RFC 6020] または YANG 1.1 [RFC 7950] で定義されたデータにアクセスするためのプログラムインターフェイスを提供する HTTP ベースのプロトコルです。

RESTCONF を選択する主な理由は次のとおりです。

●        モデル駆動型 API を提供するために HTTP CRUD 操作をマッピングする機能。

●        多くの Web アプリケーションで使用されるユビキタスな REST アーキテクチャを使用する機能。

●        複数の SDO によって生成された YANG モデリング言語で定義されたさまざまな標準データモデルを使用および混合する機能。これにより、実装者は SDN アーキテクチャ（IETF ACTN、ONF TAPI、MEF TAPI）を選択できる可能性があります。

Crosswork Hierarchical Controller の RESTCONF 実装は、次のリソースで構成されています。

●        +restconf}/data（データ API）：YANG データモデルで定義された設定データツリー全体の作成/取得/更新/削除（CRUD）ベースの API。

●        +restconf}/operations（操作 API）：YANG で定義された RPC をトリガーする RPC ベースの API エントリ。

●        +restconf}/data/ietf-restconf-monitoring:restconf-state/streams（通知 API）：RESTCONF プロトコルで定義されている潜在的な通知ストリームを検出する RESTCONF API。詳細については、「デバイス管理」を参照してください。

●        +restconf}/yang-library-version：この必須リーフは、このサーバーによって実装された「ietf-yang-library」YANG モジュールの改訂日を識別する。

RFC 8040 に従って、RESTCONF 実装は YANG データの JSON エンコーディングをサポートします [RFC 7951]。サーバーは「application/yang-data+json」を受け入れます。

クエリのフィルタ処理

RESTCONF 仕様によると、各操作には、0 個以上のクエリパラメーターをリクエスト URI に含めることができます。具体的には、クエリ操作のパラメータは [RFC 8040] のセクション 4.8 で説明されています。次の表で、サポートされるクエリパラメータを示します。

表 1.                サポートされるクエリパラメータ

転送のセキュリティ

データの完全性

Crosswork Hierarchical Controller は、TLS [RFC 5246] を介してすべての NBI アクセスデータを処理します。TLS は、データの完全性と機密性を提供するトランスポートレイヤーです。Crosswork Hierarchical Controller にアクセスするすべてのクライアントは、TLS 1.2 以上をサポートしている必要があります。

サーバー認証

Crosswork Hierarchical Controller NBI は、クライアントとの TLS 接続の確立時に X.509v3 証明書を提示します。

クライアントは、RESTCONF [RFC 8040 セクション 2] に従って、証明書の検証をサポートしている必要があります。RESTCONF クライアントは、(1) X.509 証明書パス検証 [RFC5280] を使用して RESTCONF サーバーの TLS 証明書の整合性を検証するか、(2) サーバーの TLS 証明書を信頼できるメカニズム（たとえば、ピン留めされた証明書）と一致させる必要があります。X.509 証明書パスの検証が失敗し、提示された X.509 証明書が信頼できるメカニズムによって取得された証明書と一致しない場合、[RFC5246] のセクション 7.2.1 の規定に従い接続を終了しなければなりません。

注：テストの目的で、クライアントの証明書の検証を無効にしてインターフェイスの機能をチェックできます。

クライアント認証

Crosswork Hierarchical Controller クライアント認証は、HTTP 基本認証 [RFC 7617] に基づいています。クライアントは、確立された TLS 接続を介してユーザー名とパスワードを提示する必要があります。より具体的には、クライアントは、基本認証スキームを使用する認証ヘッダーを使用する必要があります。詳細については、HTTP 認証スキームレジストリ [RFC 7235] を参照してください。

API エンドポイント

Crosswork Hierarchical Controller は、通知、情報、プロビジョニング サービスを受信するための API をサポートします。

●        デバイスマネージャ：アダプタ、デバイス、クレデンシャルを管理できるさまざまな API です。

●        インベントリの取得：光デバイスとルータ、それらのカード、ポート、属性を取得します。

●        パフォーマンスカウンタの取得：特定のポートまたはリンクごとに L2 パフォーマンス（スループット）カウンタを取得します。

●        クロスリンク：クロスリンクを管理するためのさまざまな API です。

●        共有リスク：共有リスクのポリシーとルールを管理できるさまざまな API です。

●        一般的なクエリ：SHQL コマンドを使用して、Crosswork Hierarchical Controller モデルから任意のデータをクエリします。

Object IDs

API での特定のオブジェクトの参照では、オブジェクト ID を使用します。ID は、ネットワーク、サイト、ノード、TP（ターミネーションポイント）、LSP、サービス、リンク、ネットワークアクセス、VLAN に使用できます。

Crosswork Hierarchical Controller がこれらの ID を実装したものが GUID です。GUID はモデル内のオブジェクトの一意の識別子であり、関連する GET API を使用してオブジェクト ID として取得できます。取得すると、その後はオブジェクト参照として使用できます。

Device Management

Crosswork Hierarchical Controller は、デバイス管理のための API を提供します。

Swagger を使用してデバイスマネージャ API にアクセスできます。

●        https://<host>/api/v2/apps/device_manager/rest/doc

API には次のものが含まれています。

●        すべてのアダプタの取得

●        アダプタ構成スキーマの取得

●        アダプタデバイススキーマの取得

●        すべてのデバイスの取得

●        Crosswork Hierarchical Controller へのデバイスの追加

●        アダプタへのデバイスの追加

●        デバイスのアダプタ構成の更新

●        アダプタからのデバイス割り当て解除

●        デバイス名の更新

●        サイトへのデバイスの割り当て

●        デバイスステータスの取得

●        デバイスの取得

●        Crosswork Hierarchical Controller からのデバイスの削除

●        クレデンシャルキーの名前とタイプの取得

●        新しいクレデンシャルの追加

●        クレデンシャルの更新

●        クレデンシャルの削除

●        指定されたクレデンシャルタイプのパラメータスキーマの取得。

アダプタの入手

この API を使用して、すべてのアダプタのリストを取得します。応答の guid は、他のいくつかのデバイスマネージャメソッドで使用される adapterGuid です。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/adapter

要求パラメータ

なし

応答の例

[

  {

    "guid": "cisco_ios_xr",

    "enabled": true,

    "config": {

      "polling": 300,

      "concurrency": 1,

      "ssh_config": {

        "enabled": false,

        "connect_timeout": 10,

        "command_timeout": 10

      },

      "file_bringer": {

        "enabled": false,

        "location": "",

        "file_type": "XX"

      },

      "collection_parameters": {

        "enable_igp_isis": true,

        "enable_stats": true,

        "enable_vrf": true,

        "enable_lldp": true,

        "enable_mpls": true,

        "enable_snmp": true,

        "igp_isis_priority": 1,

        "igp_seed_routers": true

      }

    }

  },

  {

    "guid": "juniper_os_1",

    "enabled": true,

    "config": {

      "polling": 300,

      "concurrency": 1,

      "ssh_config": {

        "enabled": false,

        "connect_timeout": 10,

        "command_timeout": 10

      },

      "file_bringer": {

        "enabled": false,

        "location": "",

        "file_type": "XX"

      },

      "collection_parameters": {

        "enable_igp_isis": true,

        "enable_igp_ospf": true,

        "enable_stats": true,

        "enable_vrf": true,

        "enable_lldp": true,

        "enable_mpls": true,

        "enable_snmp": true,

        "igp_isis_priority": 1,

        "igp_seed_routers": true

      }

    }

  }

]

アダプタ構成スキーマの取得

この API を使用して、アダプタの構成スキーマを取得します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/ adapter/{adapterGuid}/adapter-schema

要求パラメータ

応答の例

{

  "$schema": "http://json-schema.org/draft-04/schema#",

  "type": "object",

  "properties": {

    "polling": {

      "type": "integer",

      "minimum": 0,

      "default": 300,

      "title": "Polling Cycle [sec]",

      "description": "Poll every X seconds"

    },

    "concurrency": {

      "type": "integer",

      "default": 1,

      "title": "Number of concurrent routers collected"

    },

    "ssh_config": {

      "type": "object",

      "title": "SSH Configuration Parameters",

      "properties": {

        "enabled": {

          "type": "boolean",

          "default": false,

          "title": "Enable Tunnel"

        },

        "host": {

          "type": "string",

          "title": "Tunnel Host"

        },

        "port": {

          "type": "integer",

          "title": "Tunnel Port"

        },

        "tunnel_credentials_key": {

          "type": "string",

          "title": "Tunnel Credentials Key",

          "credentials-types": [

            "SSH_USER_PASSWORD"

          ]

        },

        "connect_timeout": {

          "type": "integer",

          "default": 10,

          "title": "Router Connect timeout"

        },

        "command_timeout": {

          "type": "integer",

          "default": 10,

          "title": "Router Command timeout"

        }

      },

      "additionalProperties": false

    },

    "file_bringer": {

      "type": "object",

      "title": "File Bringer Parameters",

      "properties": {

        "enabled": {

          "type": "boolean",

          "default": false,

          "title": "Enable File Bringer"

        },

        "location": {

          "type": "string",

          "title": "File Server Location",

          "description": "\"[sftp|file]://<server>:<port>/<absolute path>\"",

          "default": ""

        },

        "file_type": {

          "title": "File Type",

          "enum": [

            "XX",

            "XX"

          ],

          "default": "XX"

        },

        "authentication": {

          "type": "string",

          "credentials-types": [

            "SFTP"

          ]

        }

      },

      "additionalProperties": false

    },

    "collection_parameters": {

      "type": "object",

      "title": "Collection Parameters",

      "properties": {

        "enable_igp_isis": {

          "type": "boolean",

          "default": false,

          "title": "Enable IGP IS-IS Collection"

        },

        "enable_stats": {

          "type": "boolean",

          "default": false,

          "title": "Enable Stats Collection"

        },

        "enable_vrf": {

          "type": "boolean",

          "default": false,

          "title": "Enable VRF Collection"

        },

        "enable_lldp": {

          "type": "boolean",

          "default": false,

          "title": "Enable LLDP Collection"

        },

        "enable_mpls": {

          "type": "boolean",

          "default": false,

          "title": "Enable MPLS Tunnels Collection"

        },

        "enable_snmp": {

          "type": "boolean",

          "default": false,

          "title": "Enable SNMP Collection"

        },

        "igp_isis_priority": {

          "type": "integer",

          "default": 1,

          "title": "IGP IS-IS Priority"

        },

        "igp_seed_routers": {

          "type": "boolean",

          "default": true,

          "title": "Collect only IGP IS-IS seed routers"

        }

      },

      "additionalProperties": false

    }

  },

  "additionalProperties": false,

  "required": [

    "polling"

  ]

}

アダプタデバイススキーマの取得

この API を使用して、特定のアダプタのデバイス構成スキーマを取得します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/adapter/{adpaterGuid}/device-schema

要求パラメータ

応答の例

{

  "type": "object",

  "properties": {

    "host": {

      "type": "string"

    },

    "port": {

      "type": "integer",

      "default": 22

    },

    "direct_connect": {

      "type": "boolean",

      "default": false,

      "title": "Direct Connect (avoid tunnel if configured)"

    },

    "authentication": {

      "type": "string",

      "credentials-types": [

        "SSH_USER_PASSWORD"

      ]

    },

    "enabled": {

      "type": "boolean",

      "default": false

    }

  },

  "additionalProperties": false,

  "required": [

    "enabled",

    "host",

    "port"

  ]

}

すべてのデバイスの取得

この API を使用して、特定のアダプタのすべてのデバイスを取得します。応答で返される device_manager_guid は、関連するデバイスマネージャ API の deviceGuid として使用されます。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device?adapter={adpaterGuid}

要求パラメータ

応答の例

[

  {

    "device_manager_guid": "0a9af2d2-324a-45dd-895e-9e6edb2f9d39",

    "inventory_type": "ROUTER",

    "device_model_guid": "IN/cisco_ios_xr/ROUTER-xrv-p1",

    "name": "cisco_1",

    "adapters": {

      "cisco_ios_xr": {

        "adapter_guid": "cisco_ios_xr",

        "config": {

          "port": 22,

          "direct_connect": true,

          "enabled": true,

          "host": "10.1.0.58",

          "authentication": "Cisco"

        },

        "enabled": false

      }

    },

    "identifiers": {

      "host_name": "10.1.0.58",

      "tid": null,

      "serial": null,

      "loopback_mac": null,

      "loopback_ip": null,

      "extra": {}

    },

    "site": null,

    "pending_delete": false,

    "enabled": false

  },

  {

    "device_manager_guid": "9988749383",

    "inventory_type": "ROUTER",

    "device_model_guid": "IN/cisco_ios_xr/ROUTER-xrv-p2",

    "name": "cisco_2",

    "adapters": {

      "cisco_ios_xr": {

        "adapter_guid": "cisco_ios_xr",

        "config": {

          "port": 22,

          "direct_connect": true,

          "enabled": true,

          "host": "10.1.0.71",

          "authentication": "Cisco"

        },

        "enabled": false

      }

    },

    "identifiers": {

      "host_name": "10.1.0.71",

      "tid": null,

      "serial": null,

      "loopback_mac": null,

      "loopback_ip": null,

      "extra": {}

    },

    "site": null,

    "pending_delete": false,

    "enabled": false

  }

]

Crosswork Hierarchical Controller へのデバイスの追加

この API を使用して、デバイスを Crosswork Hierarchical Controller に追加します。

要求メソッド

POST

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device

要求パラメータ

なし

要求本文

リクエストボディの例

{

  "name": "router-a",

  "site": null

}

応答の例

{

  "device_manager_guid": "a2087abe-5753-4387-b372-f8cfb571bb1e"

}

デバイスをアダプタに割り当てる

この API を使用してデバイスをアダプタに割り当てます。

要求メソッド

POST

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device/{deviceGuid}/adapters/{adapterGuid}

要求パラメータ

要求本文

リクエストボディの例

{

    "host": "1.1.1.1",

    "port": 22,

    "enabled": false

}

応答の例

201 Successful

デバイスのアダプタ構成の更新

この API を使用してデバイスアダプタの構成を更新します。

要求メソッド

PUT

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device/{deviceGuid}/adapters/{adapterGuid}

要求パラメータ

要求本文

リクエストボディの例

{

    "host": "1.1.1.1",

    "port": 22,

    "enabled": true

}

応答の例

200 Successful

アダプタからのデバイス割り当て解除

この API を使用して、アダプタからデバイスの割り当てを解除します。デバイスはネットワークから削除されません。

要求メソッド

DELETE

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device/{deviceGuid}/adapters/{adapterGuid}

要求パラメータ

応答の例

200 Successful

デバイス名の更新

この API を使用してデバイス名を更新します。

要求メソッド

PUT

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device/{deviceGuid}/name/{name}

要求パラメータ

応答の例

200 Successful

デバイスをサイトに割り当てる

この API を使用してデバイスをサイトに割り当てます。

要求メソッド

PUT

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device/{deviceGuid}/site

要求パラメータ

要求本文

リクエストボディの例

{

  "guid": "ST/e7df76d7a9cb"

}

応答の例

200 Successful operation.

デバイスステータスの取得

この API を使用して、デバイスのステータスを取得します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device/{deviceGuid}/status

要求パラメータ

応答の例

{

  "adapte-name": {

    "last-successfull-discovery": "2020-05-04T17:50:15.530Z"

  }

}

デバイスの取得

この API を使用してデバイスを取得します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/ device/{deviceGuid}

要求パラメータ

応答の例

{

  "device_manager_guid": "83ce57e9-a82b-488a-994b-f8c4191f0158",

  "inventory_type": null,

  "device_model_guid": null,

  "name": "router-a",

  "adapters": {

    "cisco_ios_xr": {

      "adapter_guid": "cisco_ios_xr",

      "config": {

        "host": "1.1.1.2",

        "port": 22,

        "enabled": false

      },

      "enabled": false

    }

  },

  "identifiers": {

    "host_name": null,

    "tid": null,

    "serial": null,

    "loopback_mac": null,

    "loopback_ip": null,

    "extra": {}

  },

  "site": null,

  "pending_delete": false,

  "enabled": false

}

Crosswork Hierarchical Controller からのデバイスの削除

この API を使用して、Crosswork Hierarchical Controller からデバイスを削除します。

要求メソッド

DELETE

要求 URL

https://example-host/api/v2/apps/device_manager/rest/device/{deviceGuid}?force=true

要求パラメータ

応答の例

200 OK!

クレデンシャルの取得

この API を使用して、構成されたすべてのクレデンシャルキーの名前とタイプを取得します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/credentials?type={type}

要求パラメータ

応答の例

[

  {

    "name": "A",

    "type": "SSH_USER_PASSWORD"

  },

  {

    "name": "Cisco",

    "type": "SSH_USER_PASSWORD"

  },

  {

    "name": "junos",

    "type": "SSH_USER_PASSWORD"

  }

]

新しいクレデンシャルの追加

この API を使用して、新しいクレデンシャルを追加します。

要求メソッド

POST

要求 URL

https://example-host/api/v2/apps/device_manager/rest/credentials/{name}

要求パラメータ

要求本文

リクエストボディの例

{

  "type": "SSH_USER_PASSWORD",

  "config": {}

}

応答の例

201 Successful Operation

資格情報の更新

この API を使用してクレデンシャルを更新します。

要求メソッド

PUT

要求 URL

https://example-host/api/v2/apps/device_manager/rest/credentials/{name}

要求パラメータ

要求本文

リクエストボディの例

{

  "type": "SSH_USER_PASSWORD",

  "config": {}

}

応答の例

200 Successful Operation

クレデンシャルの削除

この API を使用してクレデンシャルを削除します。

要求メソッド

DELETE

要求 URL

https://example-host/api/v2/apps/device_manager/rest/ credentials/{name}

要求パラメータ

応答の例

200 Successful

指定されたクレデンシャルタイプのパラメータスキーマの取得。

この API を使用して、指定されたクレデンシャルタイプのパラメータスキーマを取得します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/device_manager/rest/XXX

要求パラメータ

応答の例

{

  "type": "object",

  "properties": {

    "username": {

      "title": "Username",

      "type": "string"

    },

    "password": {

      "title": "Password",

      "type": "string",

      "encrypted": true

    }

  },

  "required": [

    "username",

    「password」

  ]

}

物理インベントリ

物理インベントリ API は、デバイスの属性、スロット、カード、ポートに関する情報を提供します。

この API は、光デバイスのみをサポートします。

物理インベントリの取得

API は次の 2 つのクエリを受け入れます。

●        デバイス ID – デバイスの完全なリストまたは ID ごとの特定のデバイスを取得します。

●        Full – 詳細なデバイスインベントリまたはその ID のみを取得します（full=true/false）。

要求メソッド

GET

要求 URL

/api/v2/apps/network-inventory-app/rest/devices/

要求ヘッダー

Accept: application/yang-data+json

Content-Type: application/yang-data+json

応答の例

{

    "id": "XX-01011",

    "type": "ONE",

    "desc": "XX-01011",

    "vendor_model": "ciena_6500",

    "tid": "TID111",

    "serial_number": "[Shelf-1 [1-XX,2-XX]]",

    "SHELF": [

        {

            "id": "1",

            "type": "SHELF",

            "desc": "6500 14-Slot Converged Optical Shelf Assembly, OCP",

            "vendor_model": "ciena_6500",

            "tid": "XX-01011",

            "aid": "SHELF-1",

            "clei": "WWW",

            "serial_number": "SSS",

            "FAN": [

                {

                    "id": "FAN-1-1",

                    "type": "FAN",

                    "desc": "XX-01011/MNG-EQPT/FAN-1-1 (FAN), ctype=\"Fan Rear Exhaust High Flow Cooling\")",

                    "vendor_model": "ciena_6500",

                    "tid": "XX-01011",

                    "aid": "FAN-1-1",

                    "clei": "WWW",

                    "part_number": "NNN",

                    "serial_number": "MMM"

                }

            ],

            "CARD": [

                {

                    "id": "1-1",

                    "type": "CARD",

                    "desc": "XX-01011/1-1 (OTSC), ctype=\"2x10G OTR 4x XFP\")",

                    "vendor_model": "ciena_6500",

                    "tid": "XX-01011",

                    "aid": "OOO-1-1",

                    "clei": "WWW",

                    "part_number": "MM",

                    "serial_number": "NNN",

                    "PORT": [

                        {

                            "id": "1-1-1",

                            "type": "PORT",

                            "desc": "XX-01011/1-1-1 (P10GSOEL), ctype=\"OC192 SR1/I64.1 10GBASE-LR/LW OTU2 10GFC 1200SMLLL 1310 nm XFP\")",

                            "vendor_model": "ciena_6500",

                            "tid": "XX-01011",

                            "aid": "UU-1-1-1",

                            "clei": "WWW",

                            "pluggable": "PLUGGABLE",

                            "part_number": "NNNA",

                            "serial_number": "MMM"

                        },

                       

                },

            

            "POWER_SUPPLY": [

                {

                    "id": "PWR-1-17-1",

                    "type": "POWER_SUPPLY",

                    "desc": "XX-01011/MNG-EQPT/PWR-1-17-1 (PWR), ctype=\"Power Card 60A breakered\")",

                    "vendor_model": "ciena_6500",

                    "tid": "XX-01011",

                    "aid": "PWR-1-17-1",

                    "clei": "WWWD",

                    "part_number": "NNNA",

                    "serial_number": "MMM"

                },

            ]

        }

    ]

}

応答パラメータ

応答には、すべてのデバイス インベントリ モジュールに関する情報が含まれています。

●        デバイス – すべてのデバイスレベルの属性

●        シェルフ – 1 つ以上のシェルフ

●        ファン – ファントレイ

●        カード – トランシーバーを含む、すべての着脱可能なカード、ラインカード、アグリゲーションカード

●        ポート – すべての物理ポート

●        電源 – すべての電源モジュール

パフォーマンス カウンタ

Crosswork Hierarchical Controller パフォーマンス API は、シスコが作成した非 SDO データモデルに基づいています。SDO には、管理対象ネットワークオブジェクトの実パフォーマンスカウンタへの NBI アクセスを可能にするネットワークレベルのパフォーマンスデータモデルがありません。

IETF の現在のパフォーマンス カウンタ データ モデルは、ietf-interfaces などのデバイスレベルに対応していますが、ネットワーク レベル データ モデルは、帯域幅などの取得値に焦点を当てています。シスコは、IETF から利用可能になった時点で標準データモデルを実装します。

Crosswork Hierarchical Controller データモデルは、ポートおよび IP/MPLS LSP から収集された実パフォーマンスカウンタを公開します。これは YANG RPC の形式で実装され、NBI クライアントが RESTCONF NBI を介して操作をトリガーして、レートや平均などを取得するためのパケットおよび/またはオクテットカウンタを取得できます。

URIs

最新の PM 間隔または特定の期間のカウンタを取得できます。統計は、特定の LSP/ポート/リンク、すべてのオブジェクト、またはオブジェクトのグループ（POST メッセージで設定）に対して取得できます。

パフォーマンスの最新統計の取得

1 つのオブジェクトまたはすべてのオブジェクトの最新の期間のパフォーマンス統計を取得します。特定のポート/LSP またはストリーム ID を使用して、特定の PM タイプを指定できます。

要求メソッド

GET

要求 URL

api/v2/timeseries/stats/latest

要求ヘッダー

Accept: application/yang-data+json

Content-Type: application/yang-data+json

要求パラメータ

要求の例

GET /api/v2/timeseries/stats/latest?pmType=DELAY_USEC&objGuid=PO/juniper-northstar/LGC-LabMX960-02:ae5.0

GET /api/v2/timeseries/stats/latest?pmType=DELAY_USEC&streamId=3

要求パラメータ

応答の例

{

  "objGuid": "LI/lsp/f66fa3288d396e47/f66fa3288d396e47/f1e815107b715b67/f1e815107b715b67/lsp_1619081766048",

  "timeStamp": 1622602613000,

  "deviceType": "ROUTER",

  "timePeriodSec": 0,

  "pmType": "OCTET_OUT",

  "value": 273252081213835,

  "streamId": 6

}

期間中のパフォーマンス統計の取得

1 つのオブジェクトまたはすべてのオブジェクトの特定の期間のパフォーマンス統計を取得します。特定のポート/LSP またはストリーム ID を使用して、特定の PM タイプを指定できます。

要求メソッド

GET

要求 URL

api/v2/timeseries/stats

要求ヘッダー

Accept: application/yang-data+json

Content-Type: application/yang-data+json

要求パラメータ

要求の例

GET /api/v2/timeseries/stats?startTimeStamp=1643793190000&

endTimeStamp=1643878292000&pmTypeDELAY_USEC&objGuid= PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3

要求パラメータ

応答の例

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643874592000,

  "deviceType": "ROUTER",

  "timePeriodSec": 859,

  "pmType": "DELAY_USEC",

  "value": 649907,

  "streamId": 5

}

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643875520000,

  "deviceType": "ROUTER",

  "timePeriodSec": 928,

  "pmType": "DELAY_USEC",

  "value": 724091,

  "streamId": 5

}

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643876484000,

  "deviceType": "ROUTER",

  "timePeriodSec": 927,

  "pmType": "DELAY_USEC",

  "value": 69079,

  "streamId": 5

}

{

  "objGuid": "PO/r_logical/16f1596a46b13da5/7d82f458ff24bfa3",

  "timeStamp": 1643877388000,

  "deviceType": "ROUTER",

  "timePeriodSec": 904,

  "pmType": "DELAY_USEC",

  "value": 665969,

  "streamId": 5

}

特定のポートのパフォーマンス統計の送信

特定のポート（1 つのポート、またはすべてのポートではない）の特定の期間のパフォーマンス統計を取得します。

要求メソッド

PUT

要求 URL

api/v2/timeseries/stats/bulkStatsQuery

要求ヘッダー

Accept: application/yang-data+json

Content-Type: application/yang-data+json

要求パラメータ

要求の例

POST /api/v2/timeseries/stats/bulkStatsQuery?startTimeStamp=1659402468000&endTimeStamp=1659802468000' -d@ports.json

 

request.json は GUID のリストです。

[

    "PO/r_logical/1d80163d31fa18ee/870a15983eafb41f",

    "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4"

]

応答パラメータ

応答の例

[

  {

    "objGuid": "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4",

    "timeStamp": 1659608730000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "MAX_RTT_USEC",

    "value": 481463,

    "streamId": 4

  },

  {

    "objGuid": "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4",

    "timeStamp": 1659608730000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "DELAY_USEC",

    "value": 443345,

    "streamId": 4

  },

  {

    "objGuid": "PO/r_logical/7b4564a1ccb6e4cb/5a52cb94b8d7dbc4",

    "timeStamp": 1659608730000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "MIN_RTT_USEC",

    "value": 441197,

    "streamId": 4

  },

  {

    "objGuid": "PO/r_logical/1d80163d31fa18ee/870a15983eafb41f",

    "timeStamp": 1659608735000,

    "deviceType": "ROUTER",

    "timePeriodSec": 900,

    "pmType": "OCTET_OUT",

    "value": 17939855810587,

    "streamId": 4

  }

クロスリンク

Crosswork Hierarchical Controller は、クロスリンクを管理するための API を提供します。詳細については、『Cisco Crosswork Hierarchical Controller Administration Guide』を参照してください。

API には次のものが含まれています。

●        隣接するすべてのクロスリンクの取得

●        すべてのクロスリンクの検証

●        1 つのクロスリンクの検証

●        すべての手動クロスリンクの取得

●        すべての手動クロスリンクの取得

●        クロスリンクの取得

●        Crosswork Hierarchical Controller への手動クロスリンクの追加

●        クロスリンクの削除

注：ユーザーに API を実行する権限がない場合、403 Forbidden が返されます。間違ったクレデンシャルが使用されると、401 Authorization Required が返されます。

隣接するすべてのクロスリンクの取得

この API を使用して、LLDP などの自動検出プロトコルを使用して検出されたポートの隣接関係（アジャセンシー）を返します。このリストの要素は、構成されておらず、手動クロス リンクの一部ではない隣接関係である場合があります。

要求メソッド

GET

要求 URL

https://example-host/api/v2/crosslinks/adjacencies

要求パラメータ

なし

応答の例

応答には、隣接するすべてのクロスリンクに関する情報が含まれます。クロスリンクに関する次のものが返されます。

●        interfaceA – deviceName、interfaceName、type、guid

●        interfaceB – deviceName、interfaceName、type、 guid

●        technology（ETH または NMC）

●        relatedModelObjectGuid

すべてのクロスリンクの検証

この API を使用して、すべてのクロスリンクの検証をトリガーします。これにより、クロスリンク、ルータ物理リンク、eth リンクなどの最新のステータスに基づいてモデル（リンクとパス）を更新するプロセスが実行されます。すべてのクロスリンクを検証（および新しい手動クロスリンクを追加）すると、r-phy リンクのパスが更新される場合があり、まだ存在しない場合は r-phy リンクが一から作成される可能性もあります。新しい手動クロスリンクの結果として、光回線全体がエンドツーエンドで検出される可能性があります。

イーサネットリンクの場合、手動で追加されたクロスリンクとネットワークから検出されたクロスリンクの間に競合がある場合、手動で追加されたリンクは Cisco Crosswork Hierarchical Controller ネットワークモデルから削除されます。手動リンクは手動リンクデータベースに残り、ネットワークで検出されたリンクが消え、競合がなくなった後に手動リンクが肯定的な検証を得た場合に、ネットワークモデルに再度追加されます（これは、肯定的な検証がなくてもネットワークモデルに追加される競合のない手動リンクとは対照的です）。

この API メソッドは空の結果を返します。すべての手動クロスリンクの取得メソッドを使用して、最新のステータスを表示できます。

要求メソッド

GET

要求 URL

https://example-host/api/v2/crosslinks/validate

要求パラメータ

なし

応答の例

なし

1 つのクロスリンクの検証

この API を使用して、特定のクロスリンクの検証をトリガーします。この API は、トポロジモデルに触れることなく、検証済みの手動クロスリンクの関連する検証フィールドのみを更新します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/crosslinks/validate/{guid}

応答パラメータ

応答の例

応答は、クロス リンクに対して次を返します。

●        guid：リンクの GUID

●        interfaceA – deviceName、interfaceName、type、guid

●        interfaceB – deviceName、interfaceName、type、 guid

●        technology（ETH または NMC）

●        relatedModelObjectGuid

●        additionTimeEpochMillis

●        説明

●        validated：リンクが検証されているかどうか。

●        validationResult：検証結果（VALIDATED_BY_PORT_ADJACENCY、VALIDATED_BY_CORRELATION、NOT_CORRELATED、INCONCLUSIVE、UNKNOWN、CONFLICT）。

●        lastValidationCheck：リンクが最後に検証されたときのタイムスタンプ。

●        lastConflictTime：競合が発生しなかった場合、このタイムスタンプは非表示になります。これが lastValidationCheck と同じ場合、手動リンクは現在競合しています。lastValidationCheck が lastConflictTime より後の場合、手動リンクは以前は競合していましたが、現在は競合していません。さらに validated が true の場合、この手動リンクがネットワークモデルに追加されます。

●        conflicts：リンクが競合している、または過去に競合していた場合、conflicts リストには 1 つまたは 2 つの競合するペアが表示されます（手動リンクポートごとに 1 ペア）。

{

  "guid": "23f6e6c340268f068f817f8f9484aa54a2ba92d5d7072efd7940308f8ecc8fa5",

  "interfaceA": {

    "deviceName": "CR2.ATH",

    "interfaceName": "TenGigE0/0/1/13",

    "type": "R_PHYSICAL",

    "guid": "PO/r_physical/8ff611ed7ebcd772/2c4e6530608a213d"

  },

  "interfaceB": {

    "deviceName": "SD2ATH02",

    "interfaceName": "ETH-1-1-8",

    "type": "ETH",

    "guid": "PO/eth/ecf4e9a6bbb76cbc/86cdb5c6379e5c62"

  },

  "technology": "ETH",

  "relatedModelObjectGuid": "LI/eth/8ff611ed7ebcd772/2c4e6530608a213d/ecf4e9a6bbb76cbc/86cdb5c6379e5c62",

  "additionTimeEpochMillis": 1666695054475,

  "description": "cross link description",

  "validated": true,

  "validationResult": "VALIDATED_BY_PORT_ADJACENCY",

  "lastValidationCheck": 1668598747209,

  "conflicts": [

    {

      "a": { "deviceName": "dev-name-of-manual-link-interfaceA", "interfaceName": "iface-name-of-manual-link-interfaceA" },

      "b": { "deviceName": "dev-name-of-different-than-manual-link-interfaceB", "interfaceName": "iface-name-different-than-manual-link-interfaceB" }

 },

 {

       "a": { "deviceName": "dev-name-of-manual-link-interfaceB", "interfaceName": "iface-name-of-manual-link-interfaceB" },

       "b": { "deviceName": "dev-name-of-different-than-manual-link-interfaceA", "interfaceName": "iface-name-different-than-manual-link-interfaceA" }

   }

   ]

}

すべての手動クロスリンクの取得

この API を使用して、一連の手動クロスリンクを取得します。返された guid は、他のクロスリンク API の要求パラメータとして使用できます。

要求メソッド

GET

要求 URL

https://example-host/api/v2/crosslinks/manual

要求パラメータ

なし

応答の例

応答は、以下の情報と合わせて一連のクロスリンクを返します。

●        guid

●        interfaceA – deviceName、interfaceName、type、guid

●        interfaceB – deviceName、interfaceName、type、 guid

●        technology（ETH または NMC）

●        relatedModelObjectGuid

●        additionTimeEpochMillis

●        説明

●        validated

●        validationResult（VALIDATED_BY_PORT_ADJACENCY、VALIDATED_BY_CORRELATION、NOT_CORRELATED、INCONCLUSIVE、UNKNOWN、CONFLICT）。

●        lastValidationCheck

●        conflicts

{

  "guid": "23f6e6c340268f068f817f8f9484aa54a2ba92d5d7072efd7940308f8ecc8fa5",

  "interfaceA": {

    "deviceName": "CR2.ATH",

    "interfaceName": "TenGigE0/0/1/13",

    "type": "R_PHYSICAL",

    "guid": "PO/r_physical/8ff611ed7ebcd772/2c4e6530608a213d"

  },

  "interfaceB": {

    "deviceName": "SD2ATH02",

    "interfaceName": "ETH-1-1-8",

    "type": "ETH",

    "guid": "PO/eth/ecf4e9a6bbb76cbc/86cdb5c6379e5c62"

  },

  "technology": "ETH",

  "relatedModelObjectGuid": "LI/eth/8ff611ed7ebcd772/2c4e6530608a213d/ecf4e9a6bbb76cbc/86cdb5c6379e5c62",

  "additionTimeEpochMillis": 1666695054475,

  "description": "cross link description",

  "validated": true,

  "validationResult": "VALIDATED_BY_PORT_ADJACENCY",

  "lastValidationCheck": 1668598747209,

  "conflicts": []

}

クロスリンクの取得

この API を使用して手動クロスリンクを取得します。

要求メソッド

GET

要求 URL

https://example-host/api/v2/crosslinks/manual/{guid}

要求パラメータ

応答の例

応答は、クロス リンクに対して次を返します。

●        guid

●        interfaceA – deviceName、interfaceName、type、guid

●        interfaceB – deviceName、interfaceName、type、 guid

●        technology（ETH または NMC）

●        relatedModelObjectGuid

●        additionTimeEpochMillis

●        説明

●        validated：リンクが検証されているかどうか。

●        validationResult：検証結果（VALIDATED_BY_PORT_ADJACENCY、VALIDATED_BY_CORRELATION、NOT_CORRELATED、INCONCLUSIVE、UNKNOWN、CONFLICT）。

●        lastValidationCheck：リンクが最後に検証されたときのタイムスタンプ。

●        lastConflictTime：競合が発生しなかった場合、このタイムスタンプは非表示になります。これが lastValidationCheck と同じ場合、手動リンクは現在競合しています。lastValidationCheck が lastConflictTime より後の場合、手動リンクは以前は競合していましたが、現在は競合していません。さらに validated が true の場合、この手動リンクがネットワークモデルに追加されます。

●        conflicts：リンクが競合している、または過去に競合していた場合、conflicts リストには 1 つまたは 2 つの競合するペアが表示されます（手動リンクポートごとに 1 ペア）。

{

  "guid": "fa6262a2f1202b4bba1dd699cc78b2cf9cc45c826487de6daad69e3fa0cf0a90",

  "interfaceA": {

    "deviceName": "CR2.BCN",

    "interfaceName": "TenGigE0/0/1/8",

    "type": "R_PHYSICAL",

    "guid": "PO/r_physical/b876eefb0f288974/146956e90f8b5b6d"

  },

  "interfaceB": {

    "deviceName": "OTN1MIL01",

    "interfaceName": "1-2-3",

    "type": "ETH",

    "guid": "PO/eth/5979a210307b1e66/fba4016fb0ebde72"

  },

  "technology": "ETH",

  "relatedModelObjectGuid": "LI/CL/PO/r_physical/b876eefb0f288974/146956e90f8b5b6d/PO/eth/5979a210307b1e66/fba4016fb0ebde72",

  "additionTimeEpochMillis": 1668597718579,

  "description": "example",

  "validated": false,

  "validationResult": "UNKNOWN",

  "lastValidationCheck": 1668597744370,

  "conflicts": []

}

Crosswork Hierarchical Controller への手動クロスリンクの追加

この API を使用して、Crosswork Hierarchical Controller に手動クロスリンクを追加します。

要求メソッド

POST

要求 URL

https://example-host/api/v2/apps/crosslinks/manual

要求パラメータ

なし

要求本文

リクエストボディの例

{

  "interfaceA": {

    "deviceName": "CR2.BCN",

    "interfaceName": "TenGigE0/0/1/8"

  },

  "interfaceB": {

    "deviceName": "OTN1MIL01",

    "interfaceName": "1-2-3"

  },

  "technology": "ETH",

  "description": "example"

}

応答の例

{"guid":"d33ac2ec12c237e3a53bef30aec690e8f1ecff1a9c600c98b406ea9be30e91b7"}

クロスリンクの削除

この API を使用して手動クロスリンクを削除します。クロスリンクは削除済みとしてマークされ、次の検証の実行時に削除されます。

要求メソッド

DELETE

要求 URL

https://example-host/api/v2/crosslinks/manual/{guid}

要求パラメータ

応答の例

200 OK

共有リスク

Crosswork Hierarchical Controller は、共有リスクポリシーとルールを管理するための API を提供します。

Swagger を使用して Shared Risk API にアクセスできます。https://<host>/api/v2/apps/srlg-app/rest/doc

API には次のものが含まれています。

●    特定のポリシーの取得

●    すべてのポリシーの取得

●    ポリシーの作成

●    ポリシーの削除

●    ポリシーの共有リスクタイプの変更

●    ポリシーの種類の変更

●    ポリシーへの新しいルールの追加

●    ルールリソースの更新

●    ポリシーからのルールの削除

ポリシーの取得

この API を使用して、すべてのポリシーのリストを取得します。これにより、すべてのポリシーとそのルールのリストが返されます。

要求メソッド

GET

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy

要求パラメータ

なし

応答の例

{

    "name": "policy-1",

    "shared_risk_types": [

      "Link",

      "Port",

      "Card",

      "Shelf",

      "Device"

    ],

    "policy_type": "MULTIPLE-LINKS",

    "rules": [

      {

        "name": "rule-1",

        "resources": [

          "LI/eth/000fc44c94a1f2cd/51308dfd752c1574/df753d953c1e1c8f/f8e7b20537ce03b7"

        ]

      },

      {

        "name": "rule99",

        "resources": [

          "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

        ]

      }

    ]

  },

  {

    "name": "test",

    "shared_risk_types": [

      "Link",

      "Device",

      "Shelf",

      "Port",

      "Card"

    ],

    "policy_type": "MULTIPLE-LINKS",

    "rules": [

      {

        "name": "rule001",

        "resources": [

          "inventory[.name=\"ILA-SD1EVO01-SD1SEV01-1\"]|port|link[.layer=\"R_LOGICAL\"]"

        ]

      }

    ]

  },

  {

    "name": "policy-3",

    "shared_risk_types": [

      "Link"

    ],

    "policy_type": "SINGLE-PROTECTED",

    "rules": [

      {

        "name": "rule-99",

        "resources": [

          "link[.layer=\"R_LOGICAL\"]"

        ]

      }

    ]

}

ポリシーの取得

この API を使用してポリシーを取得します。

要求メソッド

GET

要求 URL

https:// example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}

要求パラメータ

応答の例

{

  "name": "policy-1",

  "shared_risk_types": [

    "Link",

    "Port",

    "Card",

    "Shelf",

    "Device"

  ],

  "policy_type": "MULTIPLE-LINKS",

  "rules": [

    {

      "name": "rule-1",

      "resources": [

        "LI/eth/000fc44c94a1f2cd/51308dfd752c1574/df753d953c1e1c8f/f8e7b20537ce03b7"

      ]

    },

    {

      "name": "rule99",

      "resources": [

        "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

      ]

    }

  ]

}

ポリシーの作成

この API を使用してポリシーを作成します。

要求メソッド

POST

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}

要求パラメータ

要求本文

リクエストボディの例

{

  "shared_risk_types": [

    "Link"

  ],

  "policy_type": "SINGLE-PROTECTED"

応答の例

201 Successful Operation

Delete Policy

この API を使用してポリシーを削除します。

要求メソッド

DELETE

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}

要求パラメータ

応答の例

200 Successful

ポリシーの共有リスクタイプの更新

この API を使用して、ポリシーの共有リスクタイプを変更します。

要求メソッド

PUT

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/shared_risk_types

要求パラメータ

要求本文

リクエストボディの例

{

  "shared_risk_types": [

    "Link"

  ]

}

応答の例

200 Successful Operation

ポリシータイプの更新

この API を使用してクレデンシャルを更新します。

要求メソッド

PUT

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/policy-type

要求パラメータ

要求本文

リクエストボディの例

{

  "policy_type": "SINGLE-PROTECTED"

}

応答の例

200 Successful Operation

ポリシーへのルールの追加

この API を使用して、ルールをポリシーに追加します。GUID の配列や SHQL クエリを使用してルールを作成できます。

要求メソッド

POST

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/rules{ruleName}

要求パラメータ

要求本文

リクエストボディの例

{

  "resources": [

    "link[.layer=\"R_LOGICAL\"]"

  ]

}

または

{

  "resources": [

    "LI/guid1",

    "LI/guid2"

  ]

}

または

{

  "resources": [

        "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

   ]

}

応答の例

201 Successful Operation

ルールの更新

この API を使用して、ルールのリソースを更新します。GUID の配列や SHQL クエリを使用してルールを作成できます。

要求メソッド

PUT

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid}/rules{ruleName}

要求パラメータ

要求本文

リクエストボディの例

{

  "resources": [

    "link[.layer=\"R_LOGICAL\"]"

  ]

}

または

{

  "resources": [

    "LI/guid1",

    "LI/guid2"

  ]

}

または

{

  "resources": [

        "inventory[.name=\"CR1.PAR\"]|port|link[.layer=\"R_LOGICAL\"]"

   ]

}

応答の例

201 Successful Operation

ポリシーからのルールの削除

この API を使用して、ポリシーからルールを削除します。

要求メソッド

DELETE

要求 URL

https://example-host/api/v2/apps/srlg-app/rest/policy/{policyGuid} /policy/{policyGuid}/rules/{ruleName}

要求パラメータ

応答の例

200 Successful

SHQLを使用した一般的な情報の検索

Crosswork Hierarchical Controller は、Sedona Hierarchical Query Language (SHQL) と呼ばれる、ネットワークデータ用に設計された特殊なクエリ言語を提供します。SHQL を使用すると、ユーザーは任意クエリを指定して結果をすばやく確認できるだけでなく、他のユーザーのためにクエリを保存することもできます。

SHQL には、ユーザーが単純なキーワードを使用して多層モデルにクエリを実行できるという固有の機能があります。キーワードを使用すると、モデルをナビゲートしたり、あるオブジェクトタイプから別のオブジェクトタイプに遷移したり、複雑な条件の必要性を排除したりできます。

遷移とは、SHQL がオブジェクトのリストを取得し、これを使用して関連するオブジェクトに移動する場合を意味します。たとえば、システム内のすべての SITES を取得してから、言語演算子「|」（パイプ演算子）を使用して、それらのサイトのすべての INVENTORY を取得する場合などのです。

たとえば、特定の LSP によって使用されるすべての OMS は「downward」コマンドを使用するだけで取得できます。これは、指定された LSP について、指定された下位レイヤーのすべてのリンクを取得するコマンドです。

link[.name="my_lsp"] | downward ("OMS")

SHQL コマンドと構文については、『Crosswork Hierarchical Controller SHQL Guide』で説明されています。

SHQL は、Crosswork Hierarchical Controller の UI アプリケーションで、または REST POST コマンドとして使用できます。

要求メソッド

POST

要求 URL

https://<server>/api/v2/shql

要求の例

この例では、クエリは、動作状態が down のすべての LSP のアンダーレイである OMS のリストを取得します。

link[.layer="LSP" and .operStatus="DOWN"] | downward | link[.layer="OMS" and .operStatus="DOWN"]

応答の例

{

    "activeProtectionPriority": null,

    "bidi": true,

    "desc": null,

    "distanceMeters": null,

    "extra": null,

    "guid": "LI/oms/af5e85ffc6049e8f/8c290fec341b62da/9bf4b791d3191519/3837d2f977f671bd",

    "inverseLinkId": null,

    "latencyMicros": null,

    "layer": "OMS",

    "name": "SD1BKL01/1-2-5&8 to SD1SLO01/1-3-5&8",

    "operStatus": "DOWN",

    "pathGroupType": "SINGLE_PATH",

    "paths": [

        {

            "guid": "PA/oms/af5e85ffc6049e8f/8c290fec341b62da/9bf4b791d3191519/3837d2f977f671bd"

        }

    ],

    "portA": {

        "guid": "PO/oms/af5e85ffc6049e8f/8c290fec341b62da",

        "type": "OMS"

    },

    "portB": {

        "guid": "PO/oms/9bf4b791d3191519/3837d2f977f671bd",

        "type": "OMS"

    },

    "protectionStatus": "N_A",

    "provider": "Topogen",

    "role": "REGULAR",

    "srlgs": null,

    "teMetric": null

}

SQHL の概要

SHQL - 必要性

Cisco Crosswork Hierarchical Controller は、ネットワーク構造に関する有益な情報を提供し、複数の専用アプリケーションを使用してさまざまな条件をシミュレーションできるようにします。

ただし、独自の分析を実行して、結果のレポートを表示することもできます。多面的データモデルのクエリは複雑であり、モデルに関する深い理解と高度な開発スキルが必要です。次に例を示します。

●    あるレイヤーを別のレイヤーでフィルタ処理する

●    さまざまな時間からデータを取得する

●    異常を見つける

●    複数のディメンションで属性ごとにリンクをグループ化する

モデルデータは多面的であり、次のものが含まれます。

●    ベンダー

●    トポロジ

●    [レイヤ（Layers）]

●    ドメイン

●    Status（ステータス）

●    時刻

SHQL アプリケーションは、レイヤーテーブルとディメンションテーブルの間にクロスクエリを実装することにより、この問題を解決します。これによってデータの複雑さを隠し、これらすべてのディメンションにわたってモデルを簡単にクエリできる、シンプルかつ強力なクエリ言語を提供します。

SHQL の概要

SHQL アプリケーションを使用すると、複雑なクエリコマンドをすばやく作成し、Crosswork Hierarchical Controller SHQL REST API へのリクエストとして送信できます。SHQL アプリケーションにブラウザからアクセスすると、クエリを実行し、列見出しの下に規則正しく配列された結果を表示できます。列の種類と数は、表示されるオブジェクトタイプのプロパティに基づいています。

このアプリケーションは、クエリ言語のすべての機能をカバーしています。自動補完のコンテキストメニューを使用すると、実行可能なオブジェクトタイプとそれらに関連するプロパティを簡単に選択し、さまざまなオペランドを使用して複数の条件を適用できます。

SHQL を使用すると、同じクエリコマンドライン内でクエリをあるオブジェクトタイプから別のオブジェクトタイプに変換することにより、表示される情報を操作できます。または、すべてのクエリアイテムが関連する一連のオブジェクトタイプを指定できます。

注：   このガイドで使用されるオブジェクトタイプという用語は、同じプロパティを共有するアイテムまたはアイテムのグループとして定義されます。

Crosswork Hierarchical Controller のオブジェクトモデル

SHQL オブジェクトモデル

インベントリタイプ

表 2.                インベントリタイプ

リンク タイプ

表 3.                リンク タイプ

Crosswork Hierarchical Controller の接続モデル

例：100G OTN リンク上の 10GE

接続モデル

SQHL の例

この例では、2 つの LSP 間に共有 OMS があるかどうかを検出しています。

SHQL の例

SHQL の使用

SHQL インターフェースについて

ブラウザで、サイドバーのボタンをクリックして SHQL アプリケーションを開きます。

注：   Chrome を使用することをお勧めします。

SHQL アプリケーションのボタン

SHQL アプリケーション インターフェースが表示されます。クエリを挿入するフィールドは空です。

SHQL インターフェース

クエリを実行したら、後で使用するために保存できます（クエリの保存を参照）。

クエリーの実行

クエリを実行するには以下の手順に従ってください。

1.     [クエリ（Query）] フィールドにクエリコマンドを入力します（クエリの作成を参照）。

2.     [実行（Run）] をクリックします。

取得されたデータは、関連するタブの下に整理されます。

図 6 は、inventory_item というクエリを実行した後、2 つのタブの下に表示された結果のリストを示しています。

インベントリアイテムの結果を示すクエリ画面 – 光ノード

インベントリアイテムの結果を示すクエリ画面 – ルータ

GUID 列のオブジェクトの隣にある […] をクリックすると、そのプロパティが JSON 形式で表示されます。.JSON には、オブジェクトのプロパティとその値がリストされます。

.JSON 形式のインベントリオブジェクト

クエリの中止

結果を返すまでに時間がかかるクエリを実行する場合、クエリを中止できます。    

クエリを中止するには以下を実行します。

1.     [クエリ（Query）] フィールドにクエリコマンドを入力します（クエリの作成を参照）。

2.     [実行（Run）] をクリックします。クエリが結果を返すまでに時間がかかる場合は、中止オプションが提示されます。

クエリの中止

3.     クエリを終了する場合は、[中止（Abort）] をクリックします。

クエリの作成

フリー テキストを使用するか、オートコンプリート コンテキスト メニューから項目を選択して、またはその両方を組み合わせてクエリを作成できます。[クエリ（Query）] フィールドに入力する最初の項目はオブジェクトタイプです。

クエリ構文の任意の場所でオートコンプリート コンテキスト メニューを使用できます。

注：   クエリでは大文字と小文字が区別されません。

オートコンプリート コンテキスト メニューを表示するには以下を実行します。

●    [クエリ（Query）] フィールド内をクリックし、次のいずれかを実行します。

◦       Mac：Command + スペースバーを押します。

◦       PC：Ctrl + スペースバーを押します。

メニューが表示されます。

図 10 は、オブジェクトタイプのオートコンプリート コンテキスト メニューを示しています。

オートコンプリート コンテキスト メニュー

メニューから項目を選択すると、その項目が [クエリ（Query）] フィールドに表示されます。引き続きクエリを作成し、条件と関数を追加できます。

フリーテキストまたはコンテキストメニューの選択による入力に誤りがある場合、赤いアイコン  で示されます。アイコンにカーソルを合わせると、入力が実行可能でない理由が示されるか、予想される入力が示されます。

入力が実行不可能

エラーは、図 12 に示すように単純に構文の問題の場合もあります。図 12.

構文エラー

注：   クエリ対象のオブジェクトタイプの .JSON ファイルを調べて、実行可能な入力を確認してください。

クエリの保存

クエリを作成したら、それを [保存されたクエリ（Saved Queries）] ドロップダウンメニューに保存して、繰り返し使用することができます。

クエリを保存するには以下を実行します。

1.     クエリの作成が完了したら、[名前を付けて保存（Save As）] をクリックします。

次のダイアログボックスが表示されます。

クエリ名のダイアログボックス

2.     クエリの名前を入力し、[保存（Save）] をクリックします。

保存されたクエリ

3.     保存するすべてのクエリに対して手順 1 と 2 を繰り返します。

クエリの削除

クエリを削除するには以下を実行します。

1.     保存されたクエリのドロップダウンリストからクエリを選択します。

クエリの削除

2.     [削除（Delete）] をクリックします。

クエリがリストから削除されます。

列のソート

取得されたデータは、関連する列見出しの下に表示されます。

アイテムを昇順または降順に並べ替え、個々の列にフィルタを適用できます。

注：   列管理は、他の Crosswork Hierarchical Controller テーブルと同様に処理されます。

列をソートするには以下を実行します。

1.     列の見出しをクリックします。

上向きの矢印が表示されます。

降順に表示された列コンテンツ

2.     矢印をクリックすると、列のアイテムが昇順にソートされます。再度クリックすると、列のアイテムが降順にソートされます。

昇順に表示された列コンテンツ

列のコンテンツをフィルタ処理するには以下を実行します。

1.     列見出しで、 [フィルタ（Filter）] アイコンをクリックします。

列見出しが展開され、フィルタ処理オプションが表示されます。

列のコンテンツのフィルタ処理

2.     オプションの値を選択するか、テキストボックスにパターンを入力して、列のコンテンツをフィルタ処理します。列のフィルタアイコンが  に変わり、フィルタが列に適用されたことを示します。

列に適用されたフィルタ

条件の作成

以下の表のオペランドを使用して、オブジェクトタイプに条件を適用できます。

通常、条件では大文字と小文字が区別されません。定義済みの値リストの一部である場合にのみ、大文字と小文字を区別する必要があります。

条件は角カッコ（[ ]）で囲みます。

表 4.                オペランド

例 1：オペランドによるフィルタ処理

図 20. は、CR1 で始まる名前のルータのリストを取得します

オペランドを使用したフィルタ処理。

図 21 は結果を示しています。

クエリの結果

例 2：オペランドによるフィルタ処理

図 22 は、ベンダーが Ciena であるインベントリを取得します。

オペランドを使用したフィルタ処理。

図 23 は結果を示しています。

クエリの結果

例 3：オペランドによるフィルタ処理

図 24 は、（port_a.guid = "PO/igp/06c0868cc5601e85/06c0868cc5601e85" and port_b.guid ="PO/igp/c3b0dc2cd3ad6406/c3b0dc2cd3ad6406"）または（port_a.guid = "PO/igp/c3b0dc2cd3ad6406/c3b0dc2cd3ad6406" and port_b.guid = "PO/igp/06c0868cc5601e85/06c0868cc5601e85"）のリンクを探します。

オペランドを使用したフィルタ処理。

図 25 は結果を示しています。

クエリの結果

例 4：オペランドによるフィルタ処理

図 26は、一昨日（>-2d および <-1d）にキャプチャされたイベントを取得して合計します。.timeStamp プロパティは、d（日）、h（時間）、m（月0）、M（分）、S（秒）、y（年）、または w（週）と合わせて使用できます。

オペランドを使用したフィルタ処理。

図 27 は結果を示しています。

クエリの結果

オブジェクトタイプの変換/収集

オブジェクトタイプをクエリコマンドに追加して、取得するデータが 1 つのオブジェクトタイプから別のオブジェクトタイプに変換されるかどうか、またはデータが複数のオブジェクトタイプのコレクションとそれらの関連アイテムを反映するかどうかを判断できます。

●    変換：新しいオブジェクトタイプを追加する前に、クエリコマンドにパイプ（|）を追加します。以前のオブジェクトタイプに関連する結果を、新しいオブジェクトタイプの出力に変換します。

●    コレクション：新しいオブジェクトタイプを追加する前に、クエリコマンドにアンパサンド（&）を追加します。先行するすべてのオブジェクトタイプのすべての出力を取得します。

●    As：一時変数を追加します。先行するオブジェクトタイプに関連しないオブジェクトタイプでクエリを作成できます。

以下の表は、オブジェクトタイプと、それらが直接関連するオブジェクトタイプを示しています。

表 5.                オブジェクトのタイプとプロパティ

例：オブジェクトタイプの変換

図 28.図 28 は、オブジェクトタイプのインベントリアイテムに属するポートを取得するために作成されたクエリを示しています。オブジェクトタイプはパイプ（|）で区切られます。

オブジェクトタイプの変換を使用したクエリ

図 29 は結果を示しています。

変換の結果

例：オブジェクトタイプのコレクション

図 30は、サイトとサイトが属するインベントリアイテムを取得するために作成されたクエリを示しています。オブジェクトタイプは、アンパサンド（&）で区切られます。

オブジェクト タイプ コレクションを使用したクエリ

図 31 は結果を示しています。

コレクションの結果

例：As 一時変数

As を使用すると、クエリの出力をコレクションの入力として使用できます。

次の図は、一時変数を使用して、関連のないオブジェクトタイプをサポートするように構築されたクエリを作成する方法を示しています。

図 32 は、オブジェクトタイプ link で構成されるクエリコマンドを示しています。

クエリ

図 33 は結果を示しています。

クエリの結果

図 34 は、As を使用して一時変数を作成する方法を示しています。変数 L は、有効なオブジェクトタイプとしてコンテキストメニューに表示されます。

As の追加

図 35 は、一時変数 L を使用して、リンクのリストをポート、パス、サイトリンクに変換する方法を示しています。

as を使用したクエリ

図 36 は結果を示しています。

一時変数を使用した結果

機能

SHQL には、取得するアイテムの数量、タイプ、ネットワークレイヤを正確に定義できる関数がいくつか用意されています。

クエリコマンドラインでは、関数の前にパイプが付きます。

アイテムを取得してから、関連アイテムをレイヤの上または下のいずれかから取得するか、上下の両方から取得するかを指定できます。これらの再帰操作は、ポート、リンク、サイト、インベントリ、ビジュアルサイトに対して有効です。

レトロスペクティブとタイムスタンプを使用すると、現在より前の状況をクエリできます。たとえば、サイトが現在は稼働しているものの、同じ日のダウンしていたときのステータスを確認できます。

さらに、SHQL 関数により、フリーテキストに基づいてデータを取得できます。

以下の表で SHQL 関数について説明します。SHQL 関数

表 6.                SHQL 関数

例：downward 関数

次の図は、GUID に従って、リンクの下にあるすべてのレイヤからアイテムを取得するクエリを作成する方法を示しています。

図 37 は、オブジェクトタイプと後に続く GUID で構成されるクエリコマンドを示しています。

クエリコマンド

図 38 は結果を示しています。

GUID の結果

図 39 は、コマンドに downward 関数を追加した後に取得された、リンクレイヤの下にある 9 つの追加アイテムを示しています。

downward 関数の結果

例：retrospective 関数

図 40 は、過去の特定の時間におけるネットワーク内の状況を取得するために作成されたクエリコマンドを示しています。

さまざまな時間形式を使用できます。

●    絶対時間：@2019-05-10 10:00:00

●    '-'[0-9]+[ymwdHMS]: @-10H の形式の相対時間

●    Unix タイムスタンプ（ミリ秒）：@1558610956000

@ およびエポックタイムスタンプ

図 41 は結果を示しています。

タイムスタンプの結果

例：group_by 関数

図 42 は、デバイスをサイトごとにグループ化する（およびそれらをカウントする）クエリコマンドを示しています。

group_by

図 23 は結果を示しています。

group_by の結果

履歴関数

Crosswork Hierarchical Controller は、ネットワークインベントリとトポロジのすべての変更を記録します。変更は、イベントのリストとしてイベント履歴テーブルに保存されます。イベントは、リソースの追加（ADD）、削除（DELETE）、または属性変更（UPDATE）の記録です。イベントは、モデル内のオブジェクトへの指数として GUID を使用してモデルにリンクされます。イベントテーブルには、時間、リソース ID、オブジェクトタイプ、イベントタイプ、変更前後の値など、変更のすべての詳細が含まれます。

独自の実装が選択されており、返される結果には、選択された時間範囲のある時点でモデル内にあったすべてのリソースが含まれます。そのため、後で削除されたサービスやリンクも検出されることが保証されています。たとえば、特定のタグが付いたすべてのサービスに関する過去 2 週間のイベントを取得するようにテーブルをクエリすると、結果には期間終了時に存在しなくなったサービスを含め、関連サービスが含まれます。詳細については、『Crosswork Hierarchical Controller Network History Guide』を参照してください。

標準の SHQL クエリを使用してモデルをフィルタ処理し、パイプ（|）を追加して履歴テーブルをフィルタ処理するクエリを作成できます。履歴テーブルは、すべてのエントリ属性でフィルタ処理できます。

●    変更されたオブジェクト GUID

●    変更されたオブジェクトタイプ

●    変更タイプ（ADD、UPDATE、DELETE）

●    変更前の値

●    変更後の値

結果はイベント履歴テーブルから返されます（一方、通常の SHQL クエリはオブジェクトテーブルから結果を返します）。

例：history

図 44 は、2 つの日付間のリンクのイベントを取得するために作成されたクエリコマンドを示しています。たとえば、UPDATE イベントのみを表示したり、ダウンしたリンクを検索したりするなど、履歴テーブルのオプションを追加してクエリ結果を絞り込むことができます。

@ および history

図 45 は結果を示しています。

history の結果

その他の出力関数

以下の表の関数を追加して、結果を取得して特定の順序で表示することができます。通常、これらの関数はクエリコマンドの最後に追加されます。クエリ結果の特定のプロパティを表示することもできます。

関数の順序は重要であり、次の順序にする必要があります。

●        fibre talk set > view > operands > asc/desc > limit > after

次に例を示します。

●        このクエリは無効です：port | limit(10) | asc(.name)

●        このクエリは有効です：port | asc(.name) | limit(10)

出力関数の前にはパイプ（|）が付きます。

表 7.                出力関数

例：after

図 46 は、指定された GUID を持つアイテムに続くアイテムのみを取得するために構築されたクエリを示しています。

after の出力関数

図 47 は結果を示しています。

after の出力結果

例 1：add_counters

図 48 は、各リンクレイヤの総数を取得するために作成されたクエリを示しています。クエリに | limit (0) を追加することで、応答がカウンタのみに制限されます。

add_counters 関数

図 49 は結果を示しています。

add_counters の結果

例 2: add_counters

図 50 は、各リンクレイヤの総数と、各動作ステータス（UP、DOWN、または N_A）のリンクの総数を取得するために作成されたクエリを示しています。クエリに | limit (0) を追加することで、応答がカウンタのみに制限されます。

add_counters 関数

図 51 は結果を示しています。

add_counters の結果

例：view

図 52 は、IGP ポートのポート GUID、名前、device.name、teMetric を取得するために作成されたクエリを示しています。

view 出力関数

図 53 は結果を示しています。

view の出力結果

例 2：view

図 54 は、リンクが FIBER または FIBER_SEGMENT レイヤにない場合に、リンクの GUID とリンク内のパス数を取得するために作成されたクエリを示しています。

view 出力関数

図 55 は結果を示しています。

view の出力結果

例 3：view

図 56 は、リンクが FIBER または FIBER_SEGMENT レイヤにない場合に、リンクの GUID とポート名を取得するために作成されたクエリを示しています。出力は 20 エントリに制限されています。

view 出力関数

図 57 は結果を示しています。

view の出力結果

例 4：view

図 58 は、指定されたパスのホップ数をカウントするために作成されたクエリを示しています。

view 出力関数

図 59 は結果を示しています。

view の出力結果

複雑な例

複雑な例 1

次の図は、LSP が失敗する原因となる OMS リンクを取得する方法を示しています。

クエリコマンドには次のものが含まれます。

site[.name="DUB"] | inventory_item | port | link[.layer="LSP"] as w; site[.name="BEL"] | inventory_item | port | link[.layer="LSP" and .guid in w] | downward("OMS") | link[.layer="OMS" and .operStatus="DOWN"]

サイト DUB と BEL 間のすべての LPS を取得する

●    | を使用して、あるオブジェクトタイプから別のオブジェクトタイプに変換します。

●    エイリアス と in を使用して、リストを DUB と BEL 間のみに減らします。

OMS リンクまでの downward にし、動作ステータスでフィルタ処理します。

●    「downward」関数を使用します。

●    関数でレイヤ名を使用し（downward (“OMS”)）、downward を特定のレベルまでに制限します。

クエリの結果

クエリの結果

複雑な例 2

次の図は、OMS の現在のリストを取得する方法を示しています。

クエリコマンドには次のものが含まれます。

link[.name="CR1.DUB:CR1.BEL:lsp_0"] | downward | link[.layer="OMS"]

特定の LSP によって使用されるすべての OMS を取得する

●    LSP を名前で取得します。

●    LSP によって使用される OMS までの downward にします。

次のものを含むクエリコマンドとなります。

クエリコマンド

クエリの結果

時間の経過に伴う LSP パスの変更を追跡する場合は、たとえば @-1d を使用できます。

クエリコマンド

複雑な例 3

次の図は、2 つの IP リンク間の共有リスクを見つける方法を示しています。

クエリコマンドには次のものが含まれます。

link[.name="10.40.0.157 to 10.40.0.158"] | downward | link[.layer="OMS"] as p; link[.name="10.40.0.154 to 10.40.0.153"] | downward | link[.layer="OMS"] as w; link[.guid in p and .guid in w]

最初の IP 論理リンクの OMS を取得する

●        リンク名でフィルタ処理し、その OMS までの downward として、エイリアスを p とします。

2 番目の IP 論理リンクの OMS を取得する

●        リンク名でフィルタ処理し、その OMS までの downward として、エイリアスを w とします。

すべての共有 OMS リンクを取得する

●        両方のグループのリンクを取得します。

クエリコマンド

クエリの結果

複雑な例 4

次の図は、サイト内のサービスに向けた空きポートを見つける方法を示しています。

次のものを含むクエリコマンドとなります。

site[.name contains "MIL"] | inventory_item | port[.type="ETH"] | link | port as p; site[.name contains "MIL"] | inventory_item | port[.type="ETH" and .guid not in p]

リンクで使用される特定のサイトのすべての ETH ポートを取得する

●        サイトのポートを取得し、リンクに変換してからポートに変換し、エイリアスを p とします。

リンクで使用されていないすべてのポートを取得する。

●    サイトのポートを取得し、ポートに変換し、p で表示されるものをフィルタで除外します。

クエリコマンド

クエリの結果

実際に試す

独自の複雑なクエリを作成してみてください。

図 69 は、以下を含む例を示しています。

●    オペランド

●    変換

●    コレクション

●    機能

複雑なクエリ

表 8.                複雑なクエリの内容

図 70 は結果を示しています。

複雑なクエリの結果

タイムマシンを使う

タイムマシンは、過去のある日付のネットワークの状態のスナップショットを提供します。このモードでは、すべてのアプリケーションに、この時点に適用されるデータと分析が反映されます。

タイムマシンを使用して、過去の日付と同じようにモデルをクエリできます。

モデルの日付を変更するには以下を実行します。

1.     Crosswork Hierarchical Controller のアプリケーションバーで、[SHQL] を選択します。

2.     [ライブ（Live）] をクリックし、日付を選択して [確認（Confirm）] をクリックします。

3.     必要なクエリを実行します。

オブジェクトタイプのプロパティ

次のセクションでは、異なるオブジェクトタイプに対応するすべてのプロパティの一覧を示します。

Inventory_item プロパティ

表 9.                Inventory_item プロパティ

port プロパティ

表 10.             port プロパティ

link プロパティ

表 11.             link プロパティ

site プロパティ

表 12.             site プロパティ

service プロパティ

表 13.             service プロパティ

service_intent プロパティ

表 14.             service_intent プロパティ

service_intent_resource プロパティ

表 15.             service_intent_resource プロパティ

event プロパティ

表 16.             event プロパティ

srlg Resource プロパティ

表 17.             srlg プロパティ

path プロパティ

表 18.             path プロパティ

site_link プロパティ

表 19.             site_link プロパティ

visual_site プロパティ

表 20.             visual_site プロパティ

inventory プロパティ

表 21.             inventory プロパティ

srlg_risk_resource_mtm プロパティ

表 22.             srlg_risk_resource_mtm プロパティ

risk_resource プロパティ

表 23.             risk_resource プロパティ

region プロパティ

表 24.             region プロパティ

history プロパティ

表 25.             history プロパティ

SHQL ウィジェットの作成

SHQL ウィジェットについて

カスタマイズされたウィジェットをすぐに作成できます。開発の手間やソフトウェアの配布は必要ありません。SHQL ダッシュボードアプリケーションを開くとウィジェットクエリが実行され、ウィジェットが表示されます。ウィジェットには、クエリを手動で実行するための更新ボタンもあります。

SHQL ウィジェットの作成

ウィジェットの属性は次のとおりです。

●    タイトル：SHQL ダッシュボードに表示される SHQL ウィジェットの名前。

●    クエリ：5 ビューまでにする必要があり、制限（100）があります。

●        ビジュアルモード：

◦       円/棒 - クエリにカウンタのみが含まれている場合

◦       グラフ - クエリにタイムスタンプとカウンタが含まれている場合

◦       テーブル - クエリがリストを返す場合

●    「About」テキスト。

●        オプション：ウィジェットへのドリルダウンとして使用される追加のクエリ（自動的に生成可能で、カウンタと制限は削除されます）。

SHQL ウィジェットを作成するには以下を実行します。

1.     Crosswork Hierarchical Controller のアプリケーションバーで、[SHQLウィジェット（SHQL Widgets）] を選択します。

2.     [+新しいSHQLウィジェット（+ New SHQL Widget）] をクリックします。

新しいウィジェットの作成

3.     [タイプ（Type）] を選択します。[テーブル（Table）]、[グラフ（Graph）]、または [円グラフ（Pie）] にすることができます。

選択したウィジェットのタイプに応じて、SHQL で許可される操作に関するガイダンスが提供されます。