Introduction
Avec l’API NinjaRMM-REST-API, vous pouvez interroger vos organisations, appareils et avertissements NinjaRMM par programmation.
Validation
Aperçu
L’API NinjaRMM REST API utilise un schéma HTTP personnalisé basé sur un HMAC (Hash Message Authentication Code) clé pour l’authentification. Pour authentifier une requête, il faut d’abord enchaîner les éléments sélectionnés de la requête à une chaîne de caractères. Vous utilisez ensuite votre clé d’accès API secrète pour calculer le HMAC de cette chaîne. De manière informelle, nous appelons ce processus « signature de la requête », et nous appelons la sortie de l’algorithme HMAC la signature car elle simule les propriétés de sécurité d’une signature réelle. Enfin, vous ajoutez cette signature comme paramètre de la requête en utilisant la syntaxe décrite dans cette section.
Lorsque le système reçoit une demande authentifiée, il récupère la clé d’accès secrète de l’API que vous prétendez avoir et l’utilise de la même manière pour calculer une signature pour le message reçu. Il compare ensuite la signature qu’il calcule avec la signature fournie par le demandeur. Si les deux signatures correspondent, le système conclut que le demandeur doit avoir accès à la clé d’accès secrète de l’API et qu’il agit donc avec l’autorisation du mandant pour qui la clé a été émise. Si les deux signatures ne correspondent pas, la demande est supprimée et le système répond par un message d’erreur.
Exemple de demande authentifiée
GET /v1/customers HTTP/1.1 Host: api.ninjarmm.com Date: Sun, 01 May 2016 06:51:10 GMT Authorization: NJ TF4STGMDR4H7AEXAMPLE:rEZWuXR0X1wX3autLTHIl2zX98I= Code d’accès
Votre clé d’accès se trouve dans votre portail principal NinjaRMM sous Configuration -> Intégrations -> API
Voir la capture d’écran ci-dessous: 
L‘en-tête d’authentification
L’utilisation de l’en-tête d’ Autorisation HTTP est la méthode la plus courante pour fournir des informations d’authentification. Toutes les opérations sur objet utilisent l’en-tête de demande d’ Autorisation , pour fournir des informations d’authentification.
L’API NinjaRMM REST utilise l’en-tête d’ Autorisation , HTTP par défaut pour transmettre les informations d’authentification. (Le nom de l’en-tête par défaut est malheureux car il contient des informations d’authentification et aucune autorisation.) Sous le schéma d’authentification NinjaRMM, l’en-tête d’autorisation a la forme suivante:
Authorization: NJ AccessKeyId:SignatureLes développeurs reçoivent un code d’accès et une clé d’accès secrète lors de leur inscription. Pour demander l’authentification, l’élément AccessKeyId identifie la clé d’accès utilisée pour calculer la signature et identifie indirectement le développeur qui exécute la demande.
L’élément Signature est le RFC 2104 HMAC-SHA1 des éléments sélectionnés de la demande et donc la partie Signature de l’en-tête d’autorisation varie d’une demande à l’autre. Si la signature de demande calculée par le système correspond à la Signature contenue dans la demande, le demandeur aura démontré qu’il possédait la clé d’accès secrète. La demande sera ensuite traitée sous l’identité et l’autorité du développeur à qui la clé a été délivrée.
Ce qui suit est un pseudogramme qui illustre la construction de la demande Signature. (Dans l’exemple, n est le point de code Unicode U+000A, communément appelé Newline.
Signature = Base64( HMAC-SHA1( YourSecretAccessKeyID, Base64( UTF-8- Encoding-Of( StringToSign ) ) ) ); StringToSign = HTTP-Verb + "n" + Content-MD5 + "n" + Content-Type + "n" + Date + "n" + CanonicalizedResource;HMAC-SHA1 est un algorithme défini par la RFC 2104 – Keyed-Hashing pour l’authentification des messages . L’algorithme prend en entrée deux chaînes d’octets, une clé et un message. Pour l’authentification des requêtes API NinjaRMM, utilisez votre clé d’accès secrète (YourSecretAccessKeyID) comme clé et l’encodage UTF-8 de StringToSign comme message. La sortie du HMAC-SHA1 est également une séquence d’octets appelée Digest. Le paramètre de requête Signature est créé par Base64, qui code ce « Digest ».
Exigences relatives à l’horodatage
Un horodatage valide (avec l’en-tête HTTP Date ou avec un en-tête x-nj-date) est obligatoire pour les requêtes authentifiées. De plus, l’horodatage du client associé à une demande authentifiée doit se trouver dans les 15 minutes suivant la réception de la demande dans le système NinjaRMM. Si ce n’est pas le cas, la requête échoue avec le code d’erreur RequestTimeTooSkewed. Le but de ces restrictions est de limiter la possibilité qu’une demande interceptée puisse être répétée par un adversaire. Utilisez le transport HTTPS pour les demandes authentifiées afin d’augmenter la protection contre les écoutes clandestines.
Certaines bibliothèques-clientes HTTP ne permettent pas de définir la Date d’en-tête d’une requête. Si vous rencontrez des problèmes pour inclure la valeur de l’en-tête’Date’ dans les en-têtes correctement créés, vous pouvez définir l’horodatage de la requête en utilisant plutôt l’en-tête x-nj-date. La valeur de l’en-tête x-nj-date. La valeur de l’en-tête x-nj-date doit être dans un des formats RFC 2616 (http://www.ietf.org/rfc/rfc2616.txt ). Si un en-tête x-nj-date est présent dans un ordre, le système ignore chaque en-tête Date lors du calcul de la signature de l’ordre. Par conséquent, si vous utilisez l’en-tête x-nj-date , lorsque vous créez StringToSign , utilisez la chaîne vide pour la date . Voir la section suivante pour un exemple.
Exemples d’authentification
Les exemples de cette section utilisent les informations d’identification (non fonctionnelles) du tableau suivant.
| Parameter | Value |
|---|---|
| AccessKeyId | TF4STGMDR4H7AEXAMPLE |
| SecretAccessKey | eh14c4ngchhu6283he03j6o7ar2fcuca0example |
Dans l’exemple StringToSign , le formatage n’est pas significatif, et n signifie le point de code Unicode U+000A, qui est généralement appelé saut de ligne.
Exemple de demande authentifiée
Request GET /v1/customers HTTP/1.1 Host: api.ninjarmm.com Date: Sun, 01 May 2016 06:51:10 GMT Authorization: NJ TF4STGMDR4H7AEXAMPLE:rEZWuXR0X1wX3autLTHIl2zX98I= StringToSign GETn n n Sun, 01 May 2016 06:51:10 GMTn /v1/customersREMARQUE : Toutes les données doivent être dans l’un des formats RFC 2616 (http://www.ietf.org/rfc/rfc2616.txt).
Example
Sun, 01 May 2016 06:51:10 GMTFunctions API
Ping
Vérifiez la disponibilité de l’API et vérifiez vos identifiants. Un code de statut HTTP 204 vous sera retourné pour une demande valide.
Organisations (clients)
GET /v1/customers Récupérez une liste de toutes les organisations disponibles (clients).
Exemple de réponse
[{ "id": 1, "name": "ABC Consultants", "description": "IT repair shop" }, { "id": 2, "name": "Magic IT People", "description": "Quick IT Helpdesk" }] GET /v1/customers/id Appelez une organisation particulière (client).
Exemple de réponse
{ "id": 1, "name": "ABC Consultants", "description": "IT repair shop" }Appareils
GET /v1/devices
Récupérez une liste de tous les appareils disponibles.
Exemple de réponse
REMARQUE: »remote_control_url »est un lien symbolique pour démarrer une session TeamViewer. Ceci n’est maintenu que si vous avez activé l’intégration TeamViewer.
GET /v1/devices/
Appelez un appareil spécifique.
Exemple de réponse
Alertes
GET /v1/alerts
Appelez la liste des alertes. Les messages d’avertissement contiendront à la fois des informations sur l’appareil et sur le client.
[ { "id": 457115, "type": "MONITOR", "status": "WINDOWS_SERVICE_STOPPED", "message": "'WinDefend':'Windows Defender Service' stopped.", "severity": null, "result": null, "source": null, "os_user_name": null, "timestamp": "Sun, 15 May 2016 22:11:39 GMT", "can_reset": false, "device": { "id": 1743, "type": "AGENT", "sub_type": "AGENT_GENERAL", "role": "WINDOWS_WORKSTATION", "customer_id": 107, "parent_device_id": null, "display_name": "DESKTOP1", "dns_name": "DESKTOP-MHOMN54", "system_name": "DESKTOP-MHOMN54", "netbios_name": "DESKTOP-MHOMN54", "last_online": "Wed, 18 May 2016 17:07:19 GMT", "last_update": "Wed, 18 May 2016 17:07:19 GMT" }, "customer": { "id": 107, "name": "Ninja TEST", "description": "Test customer" } } ]GET /v1/alerts/since
Récupérez les alertes depuis la dernière identification d’alerte connu (). Même schéma que /v1/alerts
DELETE /v1/alerts/
Réinitialisez un avertissement. Seuls les avertissements avec can_reset peuvent être supprimés. Renvoie d’un code d’état HTTP 204 pour une requête réussie.
Limites
Liste de API
Toutes les listes API seront limitées à 10 requêtes par intervalle de 10 minutes.
Entity API
Toutes les API de l’organisation seront limitées à pas moins de 10 requêtes par minute.
Erreurs
Réponses aux erreurs
Le serveur renvoie une erreur avec un message d’erreur significatif s’il n’a pas pu traiter votre demande avec succès. Le message d’erreur est accompagné d’un code d’état HTTP 4xx / 5xx correspondant.
Champs de réponse
- error – Une chaîne courte pour chaque type d’erreur
- error_description – Une description lisible de l’erreur avec des détails
- error_code – Un code numérique unique pour chaque type d’erreur
Types d’erreurs
- invalid_header – Un en-tête de requête syntaxiquement incorrect a été trouvé.
- missing_header – La requête ne contient pas d’en-tête obligatoire.
- skewed_time – La date de la demande est trop éloignée de l’heure actuelle.
- not_authenticated – ID clé d’accès invalide ou signature erronée
- invalid_id – L’entité requise n’existe pas
- rate_limit_exceeded – Une ressource a été demandée au-delà de ses limites permises.
Appendice
Dénombrement
Tous les périphériques ont un type et un sub_type. Un rôle facultatif peut exister. Les valeurs possibles de ces propriétés et leur description sont indiquées ci-dessous.
Type
- AGENT – Tous les périphériques Windows et Mac
- MONITOR_SERVER –Tous les dispositifs de surveillance de Cloud
- NMS_SERVER – Agent de gestion de réseau, responsable de la surveillance des terminaux de votre réseau
- NMS_TARGET – Points finaux du réseau surveillés par l’agent de gestion du réseau
Sous-type
- AGENT_GENERAL – Tous les appareils de type AGENT ont une valeur de Sub_Typ de AGENT_GENERAL
- MONITOR_SERVER_GENERAL – Tous les dispositifs de surveillance du Cloud, à l’exception des moniteurs de courrier électronique
- MONITOR_SERVER_EMAIL – Tous les dispositifs de surveillance du Cloud de courriels
- NMS_SERVER_GENERAL –Tous les périphériques de type Typ NMS_SERVER auront une valeur Sub_Typ de NMS_SERVER_GENERAL
- NMS_TARGET_GENERAL – Tous les périphériques de type NMS_TARGET auront une valeur Sub_Typ de NMS_TARGET_GENERAL
Rôle Pour tous les appareils AGENT le Rôle est défini sur l’une des valeurs suivantes en fonction du système d’exploitation et de la fonction de l’appareil.
- WINDOWS_SERVER
- WINDOWS_WORKSTATION
- MAC
- EFOLDER_IMAGEMANAGER_SERVICE
Le rôle suivant est défini pour tous les périphériques NMS_SERVER.
- NMS_NETWORK_MANAGEMENT_AGENT
Pour tous les dispositifs NMS_TARGET , le rôle est défini sur l’une des valeurs suivantes en fonction du rôle du dispositif.
- NMS_SWITCH
- NMS_ROUTER
- NMS_FIREWALL
- NMS_PRIVATE_NETWORK_GATEWAY
- NMS_PRINTER
- NMS_SCANNER
- NMS_DIAL_MANAGER
- NMS_WAP
- NMS_IPSLA
- NMS_COMPUTER
- NMS_VM_HOST
- NMS_APPLIANCE
- NMS_OTHER
- NMS_SERVER
- NMS_PHONE
- NMS_VIRTUAL_MACHINE
