Ce document décrit les points d'accès aux rapports de l'API v2 pour Netskope Advanced Analytics (AA). Cette version comprend des points de terminaison asynchrones pour la gestion de grands ensembles de données, des limites de données accrues et des structures URL RESTful plus intuitives.
Les principales caractéristiques sont les suivantes :
- Asynchronous Endpoints: permettent de lancer une requête pour un rapport/widget volumineux, d'interroger son état et de récupérer les résultats une fois qu'ils sont complets.
- 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: filtrer la liste des rapports ou des widgets à l'aide d'un paramètre de requête à correspondance partielle (ReportName ou WidgetName).
- RESTful URL Convention: sont intuitifs et utilisent des paramètres de chemin (par exemple, /reports/{reportId}/widgets/{widgetId}) au lieu de paramètres de requête pour les identifiants.
Vous trouverez plus d'informations sur cette API REST dans Swagger. Dans l'interface utilisateur, naviguez vers Settings > Tools > REST API v2 et cliquez sur API Documentation pour accéder à la documentation de l'API Swagger. Pour en savoir plus sur les API REST, consultez la présentation de l'API REST v2.
Authentification et autorisation
L'API v2 prend en charge les types de jetons suivants :
Personal User Token
- Generation: Généré à partir du menu du profil de l'utilisateur dans l'interface utilisateur de Netskope.
- Scope: Ce jeton est directement lié à l'utilisateur qui l'a généré. Tous les appels API effectués avec ce jeton s'exécuteront en tant que cet utilisateur, en respectant toutes ses autorisations et en ne renvoyant que les données qu'il peut consulter (y compris ses rapports personnels).
Service Account Token
- Generation: Généré à partir du menu RBAC dans l’interface Netskope.
- Scope: Le compte de service est lié à un rôle et non à un utilisateur spécifique.
- Consideration: Il n'y aura pas de tableaux de bord ou de widgets personnels pour ce type de compte car il est not lié à un utilisateur. Les utilisateurs peuvent uniquement accéder aux tableaux de bord et widgets communs ou partagés.
Détails du point de terminaison de l'API
Les points de terminaison suivants sont un sous-ensemble de la liste complète pour l’AA. Pour consulter les détails de tous les points de terminaison GET et POST ainsi que des exemples, rendez-vous dans Settings > Tools > REST API v2 > API Documentation pour accéder à la documentation de l’API Swagger. Faites défiler la liste jusqu’à la section Rapports.
Points de terminaison synchrones (pour les requêtes standard)
Ces points d'accès sont destinés à des requêtes standard et rapides.
- List All Reports
- Endpoint: GET /api/v2/reporting/aa/reports
- Description: Récupère une liste de tous les rapports (personnels, de groupe et de la bibliothèque Netskope) accessibles à l'utilisateur authentifié. En outre, il existe un paramètre de requête facultatif ReportName pour le filtrage des correspondances partielles (par exemple, ?reportName=RSSI).
- Get Widget Data (Synchronous)
- Endpoint: GET /api/v2/reporting/aa/reports/{reportId}/widgets/{widgetId}
- Description: Récupère les données d'un widget spécifique dans un rapport. En outre, il existe un paramètre de requête optionnel limit (par exemple, ?limit=10000) pour spécifier le nombre de lignes à renvoyer. Si elle n'est pas spécifiée, elle utilise la limite sauvegardée du widget (par défaut 500).
- Other Parameters: resultFormat (par exemple, json, csv).
Points de terminaison asynchrones (pour les requêtes de données volumineuses)
Il s'agit d'un site workflow en trois étapes conçu pour éviter les dépassements de délai de l'API lors de l'extraction de grands ensembles de données.
Step 1: Create Asynchronous Task
- Endpoint: POST /api/v2/reporting/aa/reports/{reportId}/widgets/{widgetId}/async
- Description: Lance une requête asynchrone pour un widget. Cet appel accepte également les paramètres limit et resultFormat.
- Successful Response: Renvoie un query_task_id.
{
"query_task_id": "a1b2c3d4-..."
}
Step 2: Check Task Status
- Endpoint: GET /api/v2/reporting/aa/tasks/{taskId}/status
- Description: Interrogez ce point d'accès en utilisant le query_task_id de l'étape 1 pour vérifier l'état de la tâche.
- Successful Response: Renvoie l'état. Vous devez interroger jusqu'à ce que le statut soit "complet".
{
"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: Une fois que le statut est "complet", appelez ce point de terminaison pour récupérer les données finales (au format JSON ou CSV).
Considérations
- No Pagination: l'API ne prend pas en charge la pagination (c'est-à-dire l'utilisation des paramètres "page" ou "offset"). La seule méthode pour contrôler le volume de données est d'utiliser le paramètre de limite.