Utiliser l'API AGILITY

Owned by Dina Bennett (Deactivated)
Last updated: Nov 07, 2023
4 min read

Cette page vous guide dans l'utilisation de l'API AGILITY pour vous aider à démarrer rapidement.

Vous apprendrez comment intégrer et utiliser l'API AGILITY pour analyser facilement les traces réseau.

Prérequis

Assurez-vous d'avoir les identifiants et les autorisations nécessaires pour accéder à l'API (identifiant de connexion et mot de passe) auprès de votre administrateur.

Aperçu

L'API AGILITY est conçue pour les intégrateurs système et les développeurs afin de permettre une analyse avancée des traces réseau, en se spécialisant dans l'analyse des causes profondes des flux d'appels. L'API prend en charge les formats de fichier tels que .PCAP, .PCAPNG, .CAP et .ZIP.

URL de base de l'API

Utilisez l'URL de base pour accéder à la documentation OpenAPI :

http(s)://<YOUR_PUBLIC_DN>/cv/api/public/docs

(exemple: https://cv-dev.b-yond.com/cv/api/public/docs ).

Authentification

Utilisez le flux OAuth2 Password pour demander un id_token.

Demander le jeton

Point d'accès

POST /cv/auth/realms/agility/protocol/openid-connect/token

Fournissez votre username, password, and the client_id [nom d'utilisateur, votre mot de passe et l'identifiant du client] (qui est public et fourni sous la forme de d0d8b0d806f9) dans votre demande

Headers (En-têtes)

  • Content-Type: application/x-www-form-urlencoded

Body (Corps)

  • grant_type: password

  • client_id: d0d8b0d806f9

  • username: Votre nom d'utilisateur enregistré.

  • password: Votre mot de passe.

  • scope: openid

Exemple de requête cURL

curl -X POST https://cv-dev.b-yond.com/cv/auth/realms/agility/protocol/openid-connect/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password&client_id=d0d8b0d806f9&username=YOUR_USERNAME&password=YOUR_PASSWORD&scope=openid"

RemplacezYOUR_USERNAME etYOUR_PASSWORD par vos informations d'identification.

Réponse

Lors d'une authentification réussie, vous recevrez une réponse JSON contenant l'id_token parmi d'autres jetons.

  • Utilisez la valeur de YOUR_ID_TOKEN dans vos requêtes API ultérieures en tant que jeton Bearer pour authentifier vos actions.

  • Utilisez la valeur REFRESH_TOKEN_VALUE pour obtenir un nouveau jeton, comme décrit dans la section suivante.

{ "access_token": "ACCESS_TOKEN_VALUE", "expires_in": 300, "refresh_expires_in": 1800, "refresh_token": "REFRESH_TOKEN_VALUE", "id_token": "YOUR_ID_TOKEN", ... }

Dans l'exemple ci-dessus, le jeton expire en 300 secondes (5 minutes) tandis que le refresh_token est valide pendant 1800 secondes (30 minutes).

Remarque: Conservez toujours votre id_token, access_token, et refresh_token de manière sécurisée. Ne les exposez pas dans des scripts côté client ou d'autres emplacements non sécurisés.

Gestion des jetons expirés

Lorsqu'un jeton d'accès expire, l'API AGILITY n'acceptera plus de demandes entrantes et vous redirigera vers la page de connexion. Nous vous recommandons de demander un nouveau id_token en utilisant la demande de rafraîchissement du jeton si celui-ci est toujours valide, ou de vous réauthentifier.

Utilisez ces étapes pour gérer les jetons expirés et garantir un accès continu à l'API AGILITY sans obliger les utilisateurs à se réauthentifier.

Pour rafraîchir un jeton expiré, suivez ces étapes :

  1. Effectuez une demande de jeton de rafraîchissement : Envoyez une requête POST à l'URL du jeton avec les paramètres requis pour rafraîchir le jeton. Utilisez le jeton de rafraîchissement reçu lors de l'authentification initiale.

    Exemple de demande :

    POST /cv/auth/realms/agility/protocol/openid-connect/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token=[Your Refresh Token] &client_id=d0d8b0d806f9

     

  2. Recevez un nouveau id_token : Si le jeton de rafraîchissement est valide, AGILITY répondra avec un nouveau jeton d'accès et éventuellement un nouveau jeton de rafraîchissement.

    Exemple de réponse :

     

  3. Mettez à jour votre autorisation : Utilisez le nouveau jeton d'accès dans les en-têtes de votre demande pour les requêtes API ultérieures.

Note: N'oubliez pas de stocker et de gérer de manière sécurisée le jeton de rafraîchissement, car il permet un accès à long terme à l'API et doit être protégé contre un accès non autorisé.

Points d'API AGILITY

Récupérer les services pris en charge

Point d'accès

GET /cv/api/v1/services/

Utilisez ce point d'accès pour récupérer une liste des services pris en charge.

Paramètres

  • page: Spécifiez le numéro de page. (Par défaut : 1)

  • size: Spécifiez le nombre de résultats par page. (Par défaut : 50 ; Maximum : 100)

Exemple de requête

 

Démarrer une nouvelle analyse

Point d'accès

POST /cv/api/v1/analysis/file

Ce point d'accès vous permet de lancer une analyse en utilisant un fichier de trace réseau pris en charge.

Corps de la requête

  • uploadFile: Téléchargez votre fichier de trace réseau ici (le fichier doit être disponible localement).

  • serviceKeys: (Facultatif) Liste des clés de service pour l'analyse. Si vous n'êtes pas sûr, laissez ceci vide pour la découverte automatique des services.

Exemple de requête

Récupérer les résultats de l'analyse

Point d'accès

GET /cv/api/v1/analysis/{analysis_id}/summary

Après avoir lancé une analyse, utilisez ce point d'accès pour récupérer les résultats.

Paramètres

  • analysis_id: L'ID de l'analyse (reçu de l'étape précédente).

  • page: (Facultatif) Spécifiez le numéro de page. (Par défaut : 1)

  • size: (Facultatif) Spécifiez le nombre de résultats par page. (Par défaut : 50 ; Maximum : 1000)

Exemple de requête