API publique¶
L'API publique est l'API à utiliser pour tous les scripts, connecteurs et intégrations externes. Elle est versionnée, documentée et stable : son comportement ne change pas d'une version mineure à l'autre.
API publique et API interne¶
Canopsis expose deux API distinctes, servies par deux services différents :
| API | Préfixe | Service | Port par défaut | Usage |
|---|---|---|---|---|
| API publique | /api/v5 |
canopsis-public-api |
8083 | Scripts, connecteurs, intégrations |
| API interne | /internal |
canopsis-internal-api |
8082 | Interface web de Canopsis uniquement |
L'API interne sert uniquement l'interface web. Ses routes peuvent être modifiées ou supprimées à chaque version, sans préavis. N'appelez pas /internal depuis un script : tout ce dont une intégration a besoin est disponible dans l'API publique.
Période de transition : /api/v4
L'ancien préfixe /api/v4 n'est plus servi par les API. Pour ne pas casser les intégrations existantes, la configuration Nginx fournie redirige /api/v4/<chemin> vers /internal/<chemin> : un script qui passe par Nginx continue donc de fonctionner, avec les anciennes méthodes d'authentification (authkey, authentification basique, jeton obtenu par /login).
Un script qui appelle directement le service, sans passer par Nginx, ou une installation qui utilise son propre reverse proxy, doit remplacer /api/v4 par /internal, ou reproduire cette redirection.
Cette compatibilité est temporaire. Les anciennes méthodes d'authentification seront supprimées dans une prochaine version, et les routes de l'API interne évoluent avec l'interface. Migrez vos scripts vers l'API publique dès maintenant (voir Migrer un script depuis l'API v4).
Versionnement¶
- Le préfixe de version (
/api/v5) ne change que si une version majeure de Canopsis introduit des changements incompatibles dans l'API publique. Il passe alors à/api/v6. - Les corrections de bugs de l'API publique sont reportées dans les versions maintenues, sans changement de préfixe.
- Aucune nouvelle fonctionnalité ni aucun changement de comportement n'est reporté dans une version déjà publiée.
URL de l'API¶
| URL | Usage |
|---|---|
https://<canopsis>/api/v5/ |
Via le reverse proxy Nginx (recommandé) |
http://<canopsis>:8083/api/v5/ |
Directement sur le service canopsis-public-api |
GET /api/v5/ renvoie le nom, la version de l'API et le lien vers sa documentation.
Documentation Swagger¶
Lorsque le service canopsis-public-api est démarré avec l'option -docs, la spécification OpenAPI de l'API publique de votre instance est disponible à l'adresse /api/v5/docs/swagger.yaml.
Authentification¶
L'API publique s'authentifie uniquement avec un jeton d'API publique, transmis dans l'en-tête Authorization :
Authorization: Bearer <jeton>
L'authkey, l'authentification basique et les jetons obtenus par /login ne sont pas acceptés par l'API publique.
Créer un jeton¶
Les jetons se créent dans le menu Administration > Jetons d'accès API, onglet Jetons d'API publique :
- Cliquez sur Créer un jeton d'API publique.
- Donnez-lui un nom, par exemple celui du script ou de l'intégration qui l'utilisera.
- Définissez éventuellement une durée de validité.
- Copiez le jeton affiché : pour des raisons de sécurité, sa valeur complète ne sera plus affichée.
La liste des jetons indique leur date d'expiration et leur date de dernière utilisation. Un jeton peut être supprimé à tout moment.
Un jeton hérite des droits de l'utilisateur qui l'a créé. Créez les jetons avec un compte dédié à l'intégration, disposant uniquement des droits nécessaires.
Droits¶
Chaque route de l'API publique demande un droit API, le même que pour l'ancienne API : par exemple api_alarm_read pour lire les alarmes, api_event pour envoyer des événements, api_entity en lecture pour lire les entités, api_pbehavior en création pour créer un comportement périodique, ou api_acl pour gérer les utilisateurs.
Conventions¶
Pagination¶
Les listes utilisent offset et limit, et indiquent s'il reste des résultats :
{ "data": [ ... ], "meta": { "offset": 0, "limit": 50, "has_more": true } }
Le nombre total de résultats n'est pas calculé. Pour tout récupérer, augmentez offset tant que meta.has_more vaut true :
offset=0
while :; do
body=$(curl -s -H "Authorization: Bearer $TOKEN" \
"https://<canopsis>/api/v5/entities?offset=$offset&limit=500")
echo "$body" | jq -c '.data[]'
[ "$(echo "$body" | jq '.meta.has_more')" = "true" ] || break
offset=$((offset + 500))
done
Tri¶
Un seul paramètre sort, sous la forme champ:sens, éventuellement répété avec des virgules : ?sort=name:asc ou ?sort=creation_date:asc,resource:desc. Sans sens, le tri est ascendant. Les champs triables dépendent de la route.
Filtres et patterns¶
Les filtres simples (type, catégorie, connecteur, composant, tag, dates...) sont des paramètres de la route GET. Les filtres par pattern passent par une route POST .../search, avec le pattern en JSON dans le corps de la requête :
curl -X POST "https://<canopsis>/api/v5/alarms/search" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"resolution":"open","alarm_pattern":[[{"field":"v.state.val","cond":{"type":"eq","value":3}}]]}'
La syntaxe des patterns est celle de Canopsis : le tableau extérieur est un OU, les tableaux intérieurs des ET.
Opérations en masse¶
Les routes /bulk/... répondent 207 Multi-Status, avec un résultat par élément, dans l'ordre de la requête :
[ { "id": "...", "status": 200 },
{ "status": 400, "errors": { "name": "The field is a required field" } } ]
Erreurs¶
| Code | Corps | Signification |
|---|---|---|
400 |
{"errors": {"<champ>": "<message>"}} |
Erreur de validation, par champ |
401 |
{"error": "Unauthorized"} |
Jeton absent ou expiré |
403 |
{"error": "Forbidden", "message": "..."} |
Le jeton n'a pas le droit nécessaire |
404 |
{"error": "Not Found"} |
Objet introuvable |
409 |
{"error": "Conflict", "message": "..."} |
Conflit, par exemple suppression d'un type de comportement périodique encore utilisé |
413 |
{"error": "Request Entity Too Large"} |
Corps de requête trop volumineux (import) |
Routes disponibles¶
| Domaine | Routes |
|---|---|
| Alarmes | GET /alarms, POST /alarms/search, GET /alarms/{id}/steps |
| Export d'alarmes | POST /alarm-exports, GET /alarm-exports/{id}, GET /alarm-exports/{id}/download |
| Événements | POST /event |
| Entités | GET /entities, POST /entities/search ; POST /entities/pause, POST /entities/resume ; POST /bulk/entities/pause, POST /bulk/entities/resume (voir Pause) |
| Export d'entités | POST /entity-exports, GET /entity-exports/{id}, GET /entity-exports/{id}/download |
| Import d'entités | POST /entity-imports, GET /entity-imports/{id} |
| Comportements périodiques | GET, POST /pbehaviors ; GET, PUT, PATCH, DELETE /pbehaviors/{id} ; POST, PUT, PATCH, DELETE /bulk/pbehaviors |
| Comportements périodiques de connecteur | POST, PUT, DELETE /bulk/connector-pbehaviors |
| Motifs et types de comportements périodiques | GET, POST /pbehavior-reasons et /pbehavior-types ; GET, PUT, DELETE /pbehavior-reasons/{id} et /pbehavior-types/{id} |
| Utilisateurs | GET, POST /users ; GET, PUT, PATCH, DELETE /users/{id} ; POST, PUT, PATCH, DELETE /bulk/users |
| JUnit (Pro) | POST /test-reports, POST /test-screenshots, POST /test-videos |
Toutes les routes sont préfixées par /api/v5. Le détail des paramètres et des réponses figure dans la documentation Swagger.
Exports asynchrones¶
Les exports d'alarmes et d'entités se font en trois temps : création de la tâche, suivi de son état, téléchargement du fichier. Le format est csv ou json.
job=$(curl -s -X POST "https://<canopsis>/api/v5/alarm-exports" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{
"format":"csv","delimiter":"semicolon","resolution":"open",
"fields":[{"name":"_id","label":"ID"},{"name":"entity.name","label":"Entité"}]
}' | jq -r ._id)
until [ "$(curl -s -H "Authorization: Bearer $TOKEN" "https://<canopsis>/api/v5/alarm-exports/$job" | jq -r .status)" = done ]; do sleep 2; done
curl -s -OJ -H "Authorization: Bearer $TOKEN" "https://<canopsis>/api/v5/alarm-exports/$job/download"
Le téléchargement répond 404 tant que la tâche n'est pas terminée, ou si elle a échoué (status vaut alors failed).
Import d'entités¶
POST /entity-imports?source=<nom> importe un tableau d'entités. Le paramètre source est obligatoire : il identifie le système d'origine et est enregistré sur chaque entité importée (filtre import_source). Chaque élément porte son action (set, disable, enable, delete) : les entités absentes de l'import ne sont pas modifiées. Un seul import s'exécute à la fois.
Migrer un script depuis l'API v4¶
| Point | API v4 | API publique |
|---|---|---|
| Préfixe | /api/v4/... |
/api/v5/... |
| Authentification | authkey (paramètre authkey ou en-tête x-canopsis-authkey), authentification basique, jeton /login |
Jeton d'API publique : Authorization: Bearer <jeton> |
| Pagination | ?page=3&limit=50, meta.page_count, meta.total_count |
?offset=100&limit=50, meta.has_more (pas de total) |
| Tri | ?sort_by=name&sort=asc, multi_sort[] |
?sort=name:asc |
| Patterns | Paramètres d'URL (alarm_pattern=... encodé) |
POST .../search avec un corps JSON |
| Opérations en masse | Chaque résultat reprend l'élément envoyé (item) |
Résultat par position ou par id, sans item |
| Alarmes | opened=true\|false, tstart/tstop |
resolution=open\|resolved (obligatoire), time_field + from/to |
| Export | "separator", CSV uniquement |
"delimiter", "format": "csv" ou "json", "resolution" obligatoire |
Routes renommées :
| API v4 | API publique |
|---|---|
alarm-export |
alarm-exports |
entity-export |
entity-exports |
PUT contextgraph-import, PUT contextgraph-import-partial |
POST entity-imports?source=<nom> (import partiel uniquement) |
cat/junit/upload/reports, /screenshots, /videos |
test-reports, test-screenshots?suite_name=..., test-videos?suite_name=... |
Routes sans équivalent public, et alternatives :
- Suppression d'un comportement périodique par nom : recherchez-le, puis supprimez-le par identifiant.
bulk/entity-pbehaviors: utilisezbulk/connector-pbehaviors, avec des dates de début et de fin.- Activation et désactivation en masse des comportements périodiques ou des utilisateurs :
PATCH /bulk/pbehaviorsouPATCH /bulk/usersavec{"_id": "...", "enabled": false}. - Les paramètres propres à l'interface (
active_columns[],filters[],correlation,with_*,only_bookmarks...) n'existent pas dans l'API publique.
Les utilisateurs créés par l'API publique sont des utilisateurs à authentification externe : source et external_id sont obligatoires, et il n'y a pas de champ password. Les comptes locaux se gèrent dans l'interface.