Umbrella: Umbrella Dashboard 用の Management API について

[tkitahar]

※ Management API は 2023 年 9 月 1 日 (UTC) でサポート終了する予定です。それまでに新しい API へ移行することが推奨されています。

Introducing the new Cisco Umbrella Open API

https://support.umbrella.com/hc/en-us/articles/8989122216340-Introducing-the-new-Cisco-Umbrella-Open-API

• 1. はじめに
• 2. Management API の概要
• 3. Management API の使用例

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

1. はじめに

前回の記事では Umbrella API に新たに加わった 2 つの API のうち Reporting API について取り上げました。本記事では、もう 1 つの API である Management API について紹介します。

※ Management API は契約しているサブスクリプションの種類により使用できないものが含まれます

2. Management API の概要

Management API は、これまで取り上げてきた Deployments > Network Devices と Reporting 以外の Umbrella Dashboard の項目の中から、以下の項目についての情報表示や操作を提供しています。

Umbrella Dashboard の項目	可能な操作	一意に識別する ID
Deployments > Networks	一覧表示、個別表示、削除	originId
Deployments > Roaming Computers	一覧表示、個別表示、リネーム、削除	deviceId
Deployments > Internal Networks	新規作成、一覧表示、個別表示、内容変更、削除	originId
Deployments > Sites and Active Directory の中の Virtual Appliance	一覧表示、個別表示、サイトの変更、削除	originId
Deployments > Sites and Active Directory の中の Sites	新規作成、一覧表示、個別表示、リネーム、削除	siteId
Admin > Accounts	新規作成、一覧表示、個別表示、削除	id
Admin > User Roles	一覧表示	roleId

※ Management API には、これら以外にも、Multi-Org や MSP などの複数の組織を管理するコンソール用の API も含まれるが、本記事では取り扱わない

3. Management API の使用例

Management API を使うには、他の API と同様に API Key と API Secret を取得する必要があります。まず、Umbrella Dashboard の Admin > API Keys を開きます。

API Keys 画面で Umbrella Management にチェックを入れて、CREATE ボタンを押します。

Umbrella Management という項目が追加され、API Key と API Secret がそれぞれ Your Key と Your Secret の箇所に表示されますので、これらを記録します。これで準備完了です。

では、Roaming Computers の一覧を表示し、エントリーを 1 つリネームした後に削除してみます。Roaming Computers の場合、一覧表示をするためには以下のように指定します。

curl -X GET -u 'XXXXXX:YYYYYY' 'https://management.api.umbrella.com/v1/organizations/ZZZZZZZ/roamingcomputers?limit=10'

実際には、XXXXXX を API Key に、YYYYYY を API Secret に、ZZZZZZZ を Org ID に置き換えてください。また、URL パラメーターの limit には最大取得件数を指定します。以下は出力結果例です。

[{"originId":XXXXXXXXX,"deviceId":"0123456789abcdef","type":"roaming",
"status":"VA","lastSyncStatus":"VA","lastSync":"2018-10-19T03:05:44.000Z",
"version":"2.2.109","osVersion":"Microsoft Windows [Version 10.0.17763.55]",
"osVersionName":"Windows 10","appliedBundle":85184588,"name":"PC1","hasIpBlocking":false}]

PC1 という Roaming Computers を一意に識別する deviceId (0123456789abcdef) が分かりましたので、次にこのエントリーの名前を PUT メソッドを使用して PC2 に変更します。変更内容は json 形式で渡します。

curl -X PUT -u 'XXXXXX:YYYYYY' 'https://management.api.umbrella.com/v1/organizations/ZZZZZZZ/roamingcomputers/0123456789abcdef' -H 'Content-Type: application/json' -d '{"name": "PC2"}'

実行後、以下のように変更後の内容が表示されます。

[{"originId":XXXXXXXXX,"deviceId":"0123456789abcdef","type":"roaming",
"status":"VA","lastSyncStatus":"VA","lastSync":"2018-10-19T03:05:45.000Z",
"version":"2.2.109","osVersion":"Microsoft Windows [Version 10.0.17763.55]",
"osVersionName":"Windows 10","appliedBundle":85184588,"name":"PC2","hasIpBlocking":false}]

最後にこのエントリーを DELETE メソッドを使用して削除します。今回はレスポンス ヘッダーを確認するため、curl の -i オプションを指定します。

curl –i -X DELETE -u 'XXXXXX:YYYYYY' 'https://management.api.umbrella.com/v1/organizations/ZZZZZZZ/roamingcomputers/0123456789abcdef'

実行後、以下のようにレスポンス ヘッダーのステータス コードが 204 No Content になれば削除完了です。

HTTP/1.1 204 No Content