このドキュメントでは、レポート用の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エンドポイントの詳細
以下のエンドポイントは、レポートのエンドポイント一覧のごく一部です。すべての GET および POST エンドポイントの詳細と例を表示するには、 Settings > Tools > REST API v2 > API Documentationに移動して Swagger API ドキュメントにアクセスしてください。リストをスクロールして「レポート」セクションを探してください。
同期エンドポイント（標準クエリ用）
これらのエンドポイントは、標準的な、短時間で実行されるクエリ用です。
- List All Reports
- Endpoint: GET /api/v2/reporting/er/レポート
- Description: レポート名によるオプションのフィルタリングを使用して、ユーザーがアクセス可能なすべてのレポートを取得します。 検索では、レポート名に指定された名前が含まれているかどうかを確認します。さらに、部分一致フィルタリング用のオプションのreportNameクエリパラメータがあります（例：?reportName=CISO）。
- Get Widget Data (Synchronous)
- Endpoint: GET /api/v2/reporting/er/レポート/{reportid}/widgets
- Description: 特定のレポートのデータを取得します。
- Other Parameters: resultFormat (e.g. json).
非同期エンドポイント（大規模データクエリ用）
これは、大規模なデータセットを取得する際にAPIタイムアウトが発生するのを防ぐために設計された3段階のワークフローです。
Step 1: Create Asynchronous Task
- Endpoint: POST /api/v2/reporting/er/レポート/{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/er/tasks/{taskId}/status
- Description: このエンドポイントをポーリングし、ステップ 1 の query_task_id を使用してジョブのステータスを確認します。
- Successful Response: ステータスを返します。ステータスが「完了」になるまでポーリングしてください。
{
"status": "complete",
"dashboard_id": "333",
"widget_id": "363",
"result_format": "csv",
"runtime": 1.5,
"source": "async_api"
}
Step 3: Retrieve Task Result
- Endpoint: GET /api/v2/reporting/er/tasks/{taskId}/result
- Description: ステータスが「完了」になったら、このエンドポイントを呼び出して最終データペイロード（JSONまたはCSV形式）を取得します。
考慮事項
- No Pagination: API はページネーション (つまり 「page」または「offset」パラメータ) をサポートしていません。 データ量を制御する唯一の方法は、limit パラメータを使用することです。