Umbrella: レポートに関する Umbrella API について

[tkitahar]

• 1. はじめに
• 2. Umbrella API 内のレポートについて
• 3. 使用例

※ 2025 年 5 月 27 日現在の情報をもとに作成しています

1. はじめに

本記事では、レポートに関する Umbrella API の概要と簡単な使用例について解説します。本記事を読む前に、Umbrella API の記事に目を通しておくことを強く推奨します。

※ 以前は「Umbrella: Reporting API について」というタイトルの記事でしたが、Umbrella API の導入に伴い、内容を一新しました

※ 契約しているサブスクリプションの種類により、一部の API を使用できない場合があります

2. Umbrella API 内のレポートについて

Umbrella API は、サードパーティのセキュリティ製品や自組織で開発したプログラムやスクリプトなど、Umbrella の外部にあるアプリケーションが HTTPS プロトコルを介して Umbrella の設定を操作したり、データを取得したりするためのインターフェースです。

Umbrella API を通して、Umbrella Dashboard のメニュー項目「レポート」に関する操作やデータ取得を行いたい場合、API キー (およびキーシークレット) の作成時に、レポートに関する権限を付与する必要があります。具体的には、「キーの範囲」にある「Reports」にチェックを入れます。

なお、Umbrella API がリリースされる以前から、Umbrella には Reporting API (v1 と v2) というレポート用の API 機能が存在していました。

Umbrella API は、それまでたくさんあった API を統廃合するために用意された新しい API で、Reporting API も Umbrella API に吸収される形となりました。

サードパーティ製品との互換性のため、Reporting API の一部の操作は現在も利用可能ですが、Reporting API のサポートそのものは終了しているため、それ以外の目的で Reporting API を使うことは推奨されません。

※ Reporting API キーは、API キー画面の「レガシーキー」にある「Umbrella レポート」から入手可能です

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' `
-H 'Accept: application/json' `
-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/reports/v2/activity?from=1748358035000&to=1748359235000&limit=1' `
-H 'Authorization: Bearer (3)' `
-H 'Accept: application/json'

※ (3) を アクセストークンに置き換えます
※ パラメーターの from (開始日時)、to (終了日時)、limit (件数) は必須です。任意の値に書き換えてください
※ from と to は Unix 時間に 000 を付け加えた値となります

以下が出力結果 (抜粋) です。

{"meta":{},"data":[{"destinationip":"x.x.x.x",(中略),"blockeddestinationcountries":[]}]}

その他にも Umbrella API で数多くのレポートの操作を行うことが可能です。各操作のための URL およびその詳細については、以下の公開文書からたどることができます。

API Reference - Reports - Overview

https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-reports-overview/