※ 2025 年 5 月 28 日現在の情報をもとに作成しています
1. はじめに
本記事では、ネットワークデバイスに関する Umbrella API の概要と簡単な使用例について解説します。本記事を読む前に、Umbrella API の記事に目を通しておくことを強く推奨します。
※ 以前は「Umbrella: Umbrella API の概要と使用例」というタイトルの記事でしたが、Umbrella API のリニューアルに伴い、内容を一新しました
※ 契約しているサブスクリプションの種類により、一部の API を使用できない場合があります
2. Umbrella API 内のネットワークデバイスについて
Umbrella API は、サードパーティのセキュリティ製品や自組織で開発したプログラムやスクリプトなど、Umbrella の外部にあるアプリケーションが HTTPS プロトコルを介して Umbrella の設定を操作したり、データを取得したりするためのインターフェースです。
Umbrella API を通して、Umbrella Dashboard のメニュー項目「導入」>「ネットワークデバイス」に関する操作やデータ取得を行いたい場合、API キー (およびキーシークレット) の作成時に、ネットワークデバイスに関する権限を付与する必要があります。具体的には、「キーの範囲」にある「Deployments」>「Network Devices」にチェックを入れます。
※ Umbrella API でネットワークデバイスに関する何らかの変更も行いたい場合は、右側のプルダウンから Read / Write を選びます
※ 旧 Umbrella API の API キーは、API キー画面の「レガシーキー」にある「Umbrella ネットワークデバイス」または「レガシーネットワークデバイス」から入手可能です。どちらの API キーを使うべきかは、各ネットワーク機器のマニュアルに明記されています
3. 使用例
Umbrella API の記事の記載と同様に、Windows PC の PowerShell 上から curl.exe コマンドを使用し、ネットワークデバイスの一覧を取得してみます。
まず、 API キーとキーシークレットを使って、認証のために必要な「アクセストークン」を取得します。
curl.exe --user '(1):(2)' --request POST --url 'https://api.umbrella.com/auth/v2/token' `
-H 'Content-Type: application/x-www-form-urlencoded' `
-d 'grant_type=client_credentials'
※ (1) を API キー、(2) をキーシークレットに置き換えます
※ バッククォート (`) は PowerShell における改行ですので、他のプラットフォームの curl を実行する場合、適宜置き換えてください
実行結果は以下のようになります。
{"token_type":"bearer","access_token":"(3)","expires_in":3600}
※ (3) の内容がアクセストークンで、この後使用します
※ アクセストークンの有効期限は 1 時間です
取得したアクセストークンを使って、ネットワークデバイスの一覧を取得します。
curl.exe --location --location-trusted `
--request GET --url 'https://api.umbrella.com/deployments/v2/networkdevices' `
-H 'Authorization: Bearer (3)' `
-H 'Content-Type: application/json'
※ (3) を アクセストークンに置き換えます
以下が出力結果 (抜粋) です。
[{"deviceId":"0123456789abcdef",(中略),"serialNumber":"0123456789A"}]
その他にも Umbrella API でネットワークデバイス関連の操作を行うことが可能です。各操作のための URL およびその詳細については、以下の公開文書からたどることができます。
API Reference - Deployments - Network Devices
https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-network-devices-overview/
