REST API v2 Advanced Analytics 向けレポートエンドポイント

このドキュメントでは、Netskope Advanced Analytics (AA) の API v2 レポートエンドポイントの概要を説明します。このバージョンには、大規模データセットを処理するための非同期エンドポイント、データ制限の引き上げ、より直感的でRESTfulなURL構造が含まれています。

主な特徴は以下のとおりです。

Asynchronous Endpoints: エンドポイントを使用すると、大規模なレポート/ウィジェットに対するクエリを開始し、そのステータスをポーリングし、完了後に結果を取得できます。
Increased Data Limit Parameter: the limit query parameter allows users to retrieve a custom number of rows (default 5000 (5K), maximum 10000 (10K)).
Report & Widget Filtering: レポートまたはウィジェットのリストをフィルターするには、部分一致の reportName または widgetName クエリパラメーターを使用します。
RESTful URL Convention: エンドポイントは、ID のクエリパラメーターではなく、直感的に使用できるパスパラメーター (例: /レポート/{reportId}/widgets/{widgetId}) です。

このREST APIに関する詳細情報はSwaggerで入手できます。UI上で、 Settings > Tools > REST API v2と移動し、 API DocumentationをクリックしてSwagger APIドキュメントにアクセスしてください。REST API の詳細については、「REST API v2 の概要」を参照してください。

認証と認可

API v2 では、以下のトークンタイプがサポートされています。

Personal User Token

Generation: Netskope UIのユーザープロファイルメニューから生成されました。
Scope: このトークンは、それを生成したユーザーに直接紐づけられています。このトークンを使用して行われるすべてのAPI呼び出しは、そのユーザーとして実行され、そのユーザーのすべての権限が尊重され、そのユーザーが閲覧できるデータ（個人レポートを含む）のみが返されます。

Service Account Token

Generation: NetskopeUIのRBACメニュから生成されます。
Scope: サービスアカウントは、特定のユーザーではなく、役割に紐づいています。
Consideration: このタイプのアカウントはユーザーに紐notていないため、個人用ダッシュボードやウィジェットは提供されません。ユーザーは、よくあるダッシュボードと共有ダッシュボードとウィジェットにのみアクセスできます。

APIエンドポイントの詳細

以下のエンドポイントはAAの完全リストの一部です。すべてのGETおよびPOSTエンドポイントおよび例の詳細を見るには、 Settings > Tools > REST API v2 > API Documentationに移動してSwagger APIのドキュメントにアクセスしてください。リストをスクロールして「レポート」セクションを探してください。

同期エンドポイント（標準クエリ用）

これらのエンドポイントは、標準的な、短時間で実行されるクエリ用です。

List All Reports
- Endpoint: GET /api/v2/reporting/aa/レポート
- Description: 認証されたユーザーがアクセスできるすべてのレポート（個人用、グループ用、Netskopeライブラリ用）のリストを取得します。さらに、部分一致フィルタリング用のオプションのreportNameクエリパラメータがあります（例：?reportName=CISO）。
Get Widget Data (Synchronous)
- Endpoint: GET /api/v2/reporting/aa/レポート/{reportId}/widgets/{widgetId}
- Description: レポート内の特定のウィジェットのデータを取得します。さらに、返される行数を指定するためのオプションのlimitクエリパラメータ（例：?limit=10000）があります。指定しない場合、ウィジェットの保存された制限 (デフォルトは 500) が消費されます。
- Other Parameters: 結果フォーマット（例：json、csv）。

非同期エンドポイント（大規模データクエリ用）

これは、大規模なデータセットを取得する際にAPIタイムアウトが発生するのを防ぐために設計された3段階のワークフローです。

Step 1: Create Asynchronous Task

Endpoint: POST /api/v2/reporting/aa/レポート/{reportId}/widgets/{widgetId}/async
Description: ウィジェットに対する非同期クエリを開始します。この呼び出しでは、limit パラメータと resultFormat パラメータも受け付けます。
Successful Response: query_task_id を返します。

{
  "query_task_id": "a1b2c3d4-..."
}

Step 2: Check Task Status

Endpoint: GET /api/v2/reporting/aa/tasks/{taskId}/status
Description: このエンドポイントをポーリングし、ステップ 1 の query_task_id を使用してジョブのステータスを確認します。
Successful Response: ステータスを返します。ステータスが「完了」になるまでポーリングしてください。

{
  "status": "complete",
  "dashboard_id": "...",
  "widget_id": "...",
  "source": "..."
}
{
  "status": "complete",
  "dashboard_id": "...",
  "widget_id": "...",
  "source": "..."
}

Step 3: Retrieve Task Result

Endpoint: GET /api/v2/reporting/aa/tasks/{taskId}/result
Description: ステータスが「完了」になったら、このエンドポイントを呼び出して最終データペイロード（JSONまたはCSV形式）を取得します。

考慮事項

No Pagination: API はページネーション (つまり「page」または「offset」パラメータ) をサポートしていません。データ量を制御する唯一の方法は、limit パラメータを使用することです。