Introduction
Avec l'API NinjaRMM-REST-API, vous pouvez interroger vos organisations, appareils et avertissements NinjaRMM par programmation.
Voir NinjaRMM en action !
Avec l'API NinjaRMM-REST-API, vous pouvez interroger vos organisations, appareils et avertissements NinjaRMM par programmation.
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=
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'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:Signature
Les 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".
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 (https://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.
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 (https://www.ietf.org/rfc/rfc2616.txt).
Example
Sun, 01 May 2016 06:51:10 GMT
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.
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" }
GET /v1/devices
Récupérez une liste de tous les appareils disponibles.
Exemple de réponse
[ { "id": 4460, "type": "AGENT", "sub_type": "AGENT_GENERAL", "role": "WINDOWS_WORKSTATION", "customer_id": 357, "parent_device_id": null, "display_name": "REBEL-ALIEN", "dns_name": "rebel-alien", "system_name": "REBEL-ALIEN", "netbios_name": "REBEL-ALIEN", "last_online": "Wed, 01 Jun 2016 08:23:31 GMT", "last_update": "Wed, 01 Jun 2016 08:23:29 GMT", "last_logged_in_user": "REBEL-ALIENthe_r_000", "ninja_url": "https://app.ninjarmm.com/#/deviceDashboard/4460/overview", "remote_control_url": "teamviewer10://control?device=d123456789&authorization=password", "ip_addresses": [ "192.168.142.1", "fe80::6d58:dd4e:313d:436b", "192.168.116.1", "fe80::24cd:799c:afe8:5190", "192.168.1.71", "fe80::48a7:9c5c:a2a3:33e9", "2602:30a:c7e9:a120:e4f0:4be:c13a:242b", "2602:30a:c7e9:a120:48a7:9c5c:a2a3:33e9" ], "mac_addresses": [ "00:50:56:C0:00:08", "00:50:56:C0:00:01", "20:47:47:C5:23:33" ], "memory": { "capacity": 17179869184 }, "os": { "manufacturer": "Microsoft Corporation", "name": "Microsoft Windows 10 Home", "os_architecture": "64-bit", "last_boot_time": "Tue, 31 May 2016 18:36:52 GMT" }, "system": { "manufacturer": "Alienware", "name": "REBEL-ALIEN", "model": "Alienware 15", "dns_host_name": "rebel-alien", "bios_serial_number": "9547Z52", "domain": "WORKGROUP" }, "processor": { "name": "Intel(R) Core(TM) i7-4720HQ CPU @ 2.60GHz", "architecture": "x64", "num_cores": 4, "num_logical_cores": 8, "current_clock_speed": 2601000000, "max_clock_speed": 2601000000 }, "disks": [{ "name": "C:", "type": "Local Disk", "file_system": "NTFS", "serial_number": "876457785", "volume_label": "", "capacity": 42842714112, "free_space": 3738173440 }] }, { "id": 4823, "type": "NMS_TARGET", "sub_type": "NMS_TARGET_GENERAL", "role": "NMS_PRINTER", "customer_id": 435, "parent_device_id": 4822, "display_name": "172.16.1.20", "dns_name": null, "system_name": null, "netbios_name": null, "last_online": "Tue, 10 May 2016 22:58:24 GMT", "last_update": "Tue, 10 May 2016 22:58:24 GMT", "ninja_url": "https://app.ninjarmm.com/#/nmsDashboard/4823/overview", "ip_addresses": [ "172.16.1.20" ], "mac_addresses": [ "00:F0:56:C0:AB:08", ] }, { "id": 4847, "type": "NMS_SERVER", "sub_type": "NMS_SERVER_GENERAL", "role": "NMS_NETWORK_MANAGEMENT_AGENT", "customer_id": 434, "parent_device_id": null, "display_name": "JERRYPC", "dns_name": null, "system_name": "JERRYPC", "netbios_name": null, "last_online": "Mon, 16 May 2016 19:08:42 GMT", "last_update": "Mon, 16 May 2016 19:08:42 GMT", "ninja_url": "https://app.ninjarmm.com/#/nmsDashboard/4847/overview", "remote_control_url": "teamviewer10://control?device=d123456789&authorization=password", "ip_addresses": [ "172.16.1.24" ], "mac_addresses": [ "01:F0:56:C0:FB:08", ] }, { "id": 4342, "type": "MONITOR_SERVER", "sub_type": "MONITOR_SERVER_GENERAL", "role": null, "customer_id": 368, "parent_device_id": null, "display_name": "Ping Test", "dns_name": null, "system_name": "Ping Test", "netbios_name": "Ping Test", "last_online": "Mon, 16 May 2016 19:03:52 GMT", "last_update": "Mon, 16 May 2016 19:03:52 GMT", "ninja_url": "https://app.ninjarmm.com/#/cloudMonitorDashboard/4342" } ]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
{ "id": 4460, "type": "AGENT", "sub_type": "AGENT_GENERAL", "role": "WINDOWS_WORKSTATION", "customer_id": 357, "parent_device_id": null, "display_name": "REBEL-ALIEN", "dns_name": "rebel-alien", "system_name": "REBEL-ALIEN", "netbios_name": "REBEL-ALIEN", "last_online": "Wed, 01 Jun 2016 08:23:31 GMT", "last_update": "Wed, 01 Jun 2016 08:23:29 GMT", "last_logged_in_user": "REBEL-ALIENthe_r_000", "ninja_url": "https://app.ninjarmm.com/#/deviceDashboard/4460/overview", "ip_addresses": [ "192.168.142.1", "fe80::6d58:dd4e:313d:436b", "192.168.116.1", "fe80::24cd:799c:afe8:5190", "192.168.1.71", "fe80::48a7:9c5c:a2a3:33e9", "2602:30a:c7e9:a120:e4f0:4be:c13a:242b", "2602:30a:c7e9:a120:48a7:9c5c:a2a3:33e9" ], "mac_addresses": [ "00:50:56:C0:00:08", "00:50:56:C0:00:01", "20:47:47:C5:23:33" ], "memory": { "capacity": 17179869184 }, "os": { "manufacturer": "Microsoft Corporation", "name": "Microsoft Windows 10 Home", "os_architecture": "64-bit", "last_boot_time": "Tue, 31 May 2016 18:36:52 GMT" }, "system": { "manufacturer": "Alienware", "name": "REBEL-ALIEN", "model": "Alienware 15", "dns_host_name": "rebel-alien", "bios_serial_number": "9547Z52", "domain": "WORKGROUP" }, "processor": { "name": "Intel(R) Core(TM) i7-4720HQ CPU @ 2.60GHz", "architecture": "x64", "num_cores": 4, "num_logical_cores": 8, "current_clock_speed": 2601000000, "max_clock_speed": 2601000000 }, "disks": [{ "name": "C:", "type": "Local Disk", "file_system": "NTFS", "serial_number": "876457785", "volume_label": "", "capacity": 42842714112, "free_space": 3738173440 }], "software": [{ "name": "Mozilla Firefox 45.0.1 (x86 en-US)", "publisher": "Mozilla", "version": "45.0.1", "install_date": "20160410", "size": 92580864 }, { "name": "Google Chrome", "publisher": "Google, Inc.", "version": "49.0.2623.112", "install_date": "20160410", "size": 53498880 }, { "name": "Microsoft .NET Framework 4.5.2", "publisher": "Microsoft Corporation", "version": "4.5.51209", "install_date": "20160229", "size": 40685568 }] }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.
Toutes les listes API seront limitées à 10 requêtes par intervalle de 10 minutes.
Toutes les API de l'organisation seront limitées à pas moins de 10 requêtes par minute.
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
Types d'erreurs
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
Sous-type
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.
Le rôle suivant est défini pour tous les périphériques NMS_SERVER
.
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.