このドキュメントでは、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 パラメータを使用することです。