REST API v2 レポート用エンドポイント - Netskope ナレッジポータル

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