Postman経由でUmbrella Reporting APIを使用

はじめに

このドキュメントでは、PostmanでCisco Umbrella Reporting API(UMBRELLA)を使用する方法について説明します。

前提条件

要件

このドキュメントに関する固有の要件はありません。

使用するコンポーネント

このドキュメントの情報は、Cisco Umbrellaに基づくものです。

このドキュメントの情報は、特定のラボ環境にあるデバイスに基づいて作成されました。このドキュメントで使用するすべてのデバイスは、クリアな（デフォルト）設定で作業を開始しています。本稼働中のネットワークでは、各コマンドによって起こる可能性がある影響を十分確認してください。

概要

Umbrella APIは2022年9月にリリースされ、Umbrellaの構築、拡張、統合を可能にする使いやすい安全なプラットフォームを提供します。

Umbrella APIエンドポイントは、ユースケースごとにグループ化されたパスを使用して、api.umbrella.comでホストされます。APIキーは、UmbrellaダッシュボードのAdmin > API keysで管理することも、KeyAdmin APIを使用してプログラムで管理することもできます。各キーは、5つの主な使用例に基づいてグループ化された複数のスコープを使用して細かく設定できます。

• Admin APIエンドポイントを使用すると、Umbrella APIキーとユーザーのプロビジョニングと管理、ロールの表示、およびプロバイダーとマネージドプロバイダーの顧客の管理を行うことができます。
• Auth APIエンドポイントを使用すると、他のサービスとUmbrellaプラットフォームの統合を許可できます。
• 導入APIエンドポイントを使用すると、ネットワークやその他のさまざまなエンティティをプロビジョニング、監視、管理し、既存のUmbrellaポリシーで設定することで保護できます。
• ポリシー APIエンドポイントを使用すると、宛先リストおよびリストごとの宛先をプロビジョニングおよび管理できます。
• レポートAPIエンドポイントを使用すると、展開に関するリアルタイムのセキュリティ情報を読み取って監査できます。Umbrella App Discovery APIは、クラウドベースのアプリケーションに対する洞察を提供します。

この記事では、APIを使用してアクティビティ検索レポートを収集する方法について説明します。

包括的な手順

1. Umbrellaダッシュボードから、Admin > API Keysに移動します。

2. API Keys > Addの順に選択します。

3. Key Scopeで、Reports、Create Keyの順に選択します。

21495050167956

管理者は、各APIキーの使用目的に応じて、読み取り/書き込みと読み取り専用の間でスコープごとのアクセスレベルを調整できます。また、APIキーは、事前定義された日付で期限切れになるように設定できます。APIキー/シークレットは現在表示されているため、このステップで収集する必要があります。後で表示することはできません。 

APIクレデンシャルにより、60分間有効なAPIアクセストークンが生成されます。この手順では、OAuth 2.0クライアントの資格情報フローをサポートします。Umbrellaマルチ組織またはサービスプロバイダー環境では、親組織APIクレデンシャルを使用して、認証プロセス中に指定された子組織と同じスコープのアクセストークンを生成できます。

郵便局手続き

最初に、OAuth 2.0アクセストークンを作成する必要があります。Umbrella APIの認証パスはhttps://api.umbrella.com/auth/v2で始まります。POSTクエリとユーザAPIキーをユーザ名として、APIパスワードをパスワードとして送信すると、アクセストークンが生成されます。

21606708808468

21607051456276

このステップでは、アクセストークンを収集する必要があります。これで、アクセストークンを使用して情報を取得できます。

GETメソッドを選択し、APIパス（必要なパラメータを含む）とアクセストークンの両方を入力する必要があります。 この例では、過去7日間のDNSトラフィック専用のアクティビティ検索から100個のレポートを取得できます。

21607952074772

別の例では、特に「gsa.apple.com」ドメインについて、過去7日間のDNSトラフィック専用に、アクティビティ検索から1000個のレポートを抽出できます。

21607927544468

要求クエリパラメータを参照して、APIクエリで使用できる追加のパラメータを見つけることができます。

注:HTTPクライアント要求がUmbrellaデータウェアハウスの場所と同じ大陸から発信されていない場合、Umbrellaサーバは302 Foundで応答します。HTTP要求を自動的にリダイレクトしてHTTP認証ヘッダーを保持するには、追加フラグを設定するか、リダイレクト設定を有効にします。

curl:curl HTTP要求をリダイレクトして認証ヘッダーを保持するには、-Lまたは – locationおよび – location-trustedフラグを渡す必要があります。

21608126036628

Postman:Postman環境内でAPIに移動し、GETメソッドを選択します。Settings > Enable Follow Authorization headerの順に移動して、リダイレクト要求のAuthorizationヘッダーを保持します。

21608126042388

回答

GETアクションをURLに送信した後で、さまざまなステータスコードを受信できます。

• ステータス：200：要求された情報が要求によって正常に取得されました。
• ステータス： 400：無効な要求です。これは、クエリーに送信したURLに関連している可能性があります。1つ以上のパラメーターが正しくありません。
• ステータス： 401：承認されていません。承認ヘッダーがないか、トークンが承認されていません。
• Status:403：禁止。トークンが無効です。