Εντολές συσκευής

Επισκόπηση

Κάθε κλήση επενεργεί σε μία ακριβώς συσκευή, η οποία προσδιορίζεται από το assetId της, δηλαδή το pathName που επιστρέφεται από το GET /assets. Δεν υπάρχει τελικό σημείο μαζικών ενεργειών (bulk endpoint). Για να στείλετε εντολές σε πολλές συσκευές, πραγματοποιήστε μία κλήση ανά συσκευή εντός του ορίου ρυθμού (rate limit). Τα τελικά σημεία εκτελούν τις ίδιες λειτουργίες με τα εργαλεία εντολών MCP.

Το κλειδί απαιτεί τα δικαιώματα DEVICES_COMMAND και DEVICES_READ. Το change-policy απαιτεί επιπλέον το POLICIES_READ. Οι καταστροφικές εντολές απαιτούν αντ' αυτών τα δικαιώματα DEVICES_COMMAND_DESTRUCTIVE και DEVICES_READ. Στείλτε το κλειδί στην κεφαλίδα X-API-Key. Το REST API δεν δέχεται κεφαλίδα Authorization.

Η συσκευή πρέπει να είναι εγγεγραμμένη (κατάσταση ACTIVE, INACTIVE ή SYNCHRONIZING). Ορισμένες εντολές λειτουργούν μόνο σε έναν συγκεκριμένο τύπο συσκευής, όπως αναφέρεται σε κάθε περιγραφή παρακάτω: συσκευές Android Management (υπό τη διαχείριση της Google) ή συσκευές υπό τη διαχείριση του Nomid agent (AOSP). Οποιαδήποτε άλλη συσκευή λαμβάνει σφάλμα 409. Ένα μήνυμα είναι μια ειδοποίηση push προς τον Nomid agent και απαιτεί ένα καταχωρημένο push token.

Τελικά σημεία

Στείλτε Content-Type: application/json με τα τελικά σημεία lost-mode, message, launch-app, clear-app-data, change-policy και change-screen-lock-password. Τα υπόλοιπα τελικά σημεία δεν δέχονται σώμα. Άγνωστα πεδία απορρίπτονται, και τα υποχρεωτικά πεδία κειμένου δεν μπορούν να είναι κενά.

Καταστροφικές εντολές

Τέσσερις εντολές διαγράφουν δεδομένα, αφαιρούν ή αντικαθιστούν το κλείδωμα οθόνης ή τερματίζουν τη διαχείριση της συσκευής. Με ένα κλειδί API εκτελούνται μόλις γίνει αποδεκτό το αίτημα. Δεν υπάρχει στάδιο έγκρισης στην πύλη.

Απαιτούν ένα κλειδί API με DEVICES_COMMAND_DESTRUCTIVE και DEVICES_READ. Η εταιρεία πρέπει επίσης να ενεργοποιήσει τις καταστροφικές εντολές στην ενότητα πρόσβασης πράκτορα AI στην πύλη. Αυτή η ρύθμιση είναι απενεργοποιημένη από προεπιλογή και απαιτεί να είναι επίσης ενεργοποιημένες οι εντολές συσκευής. Χωρίς αυτήν, το αίτημα επιστρέφει 403 με κωδικό forbidden.

Το change-screen-lock-password λαμβάνει τον νέο κωδικό πρόσβασης στο newPassword. Το Nomid δεν τον αποθηκεύει, δεν τον επιστρέφει ούτε τον καταγράφει ποτέ.

Σώματα αιτημάτων

Σώμα αιτήματος λειτουργίας απώλειας

Σώμα αιτήματος μηνύματος

Παράδειγμα: αποστολή μηνύματος

Αντικαταστήστε το asset id με ένα pathName από το GET /assets, και διατηρήστε το κλειδί σε μια μεταβλητή περιβάλλοντος.

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/message" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Please return this device", "body": "Bring it to the IT desk by 5 pm."}'

{
  "assetId": "k3x9m2pa",
  "type": "NOTIFICATION_MESSAGE",
  "status": "SUCCESS",
  "createdAt": "2026-10-06T14:30:00Z"
}

Μια απάντηση 200 σημαίνει ότι η εντολή δημιουργήθηκε. Το πεδίο status είναι η κατάσταση της εντολής κατά την επιστροφή του αιτήματος. Για ένα μήνυμα, το SUCCESS σημαίνει ότι η προώθηση (push) έγινε αποδεκτή για παράδοση, όχι ότι ο χρήστης το είδε. Συνεχίστε με GET /assets/ASSET_ID/commands.

Παράδειγμα: κλείδωμα συσκευής

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/lock" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "IN_PROGRESS",
  "createdAt": "2026-10-06T14:30:00Z"
}

Το κλείδωμα και η λειτουργία απώλειας επιστρέφουν IN_PROGRESS ενόσω η συσκευή δεν έχει ακόμη επιβεβαιώσει την εντολή. Το ιστορικό εντολών εμφανίζει SUCCESS μόλις το κάνει. Το τελικό σημείο (endpoint) lock δεν δέχεται σώμα (body).

Παράδειγμα: πλήρης διαγραφή συσκευής

curl -X POST "https://api.nomid.tech/emm/api/v1/assets/k3x9m2pa/commands/wipe" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "assetId": "k3x9m2pa",
  "type": "WIPE_COMPANY_DATA",
  "status": "IN_PROGRESS"
}

Μια πλήρης διαγραφή μιας συσκευής Android Management αποκρίνεται με IN_PROGRESS χωρίς createdAt. Ελέγξτε το ιστορικό εντολών για να την παρακολουθήσετε.

Απαντήσεις και τι να κάνετε

Οι κανόνες επανάληψης προσπάθειας έχουν σημασία. Η επανάληψη μιας εντολής της οποίας το αποτέλεσμα είναι άγνωστο μπορεί να την παραδώσει δύο φορές.

Σώματα σφαλμάτων

Τα σφάλματα από τα τελικά σημεία εντολών χρησιμοποιούν το application/problem+json (RFC 9457). Στα τελικά σημεία lock, lost-mode, found και message, τα 401 και 429 επιστρέφουν ένα μικρό αντικείμενο JSON με error, message και status, το 404 δεν έχει σώμα και μόνο τα 502 και 503 προσθέτουν ένα boolean μέλος retryable. Στα υπόλοιπα τελικά σημεία, κάθε σφάλμα εκτός από το 401 είναι problem details με μέλος code, όπως not_found, unsupported, forbidden, invalid_arguments ή rate_limited, ενώ τα 429, 500, 502 και 503 φέρουν επίσης το retryable. Μια απόκριση 202 δεν είναι σφάλμα: φέρει το κανονικό αντικείμενο αποτελέσματος.

Παράδειγμα απόκρισης 202

HTTP/1.1 202 Accepted

{
  "assetId": "k3x9m2pa",
  "type": "LOCK",
  "status": "UNCONFIRMED",
  "detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
}

Παράδειγμα απόκρισης 503

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Command was not sent; it is safe to retry.",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
  "retryable": true
}

Παράδειγμα απόκρισης 404 από τελικό σημείο εκτός των lock, lost-mode, found και message

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No device found with assetId: k3x9m2pa",
  "instance": "/emm/api/v1/assets/k3x9m2pa/commands/reboot",
  "code": "not_found"
}

Όριο ρυθμού

Οι εντολές περιορίζονται σε 10 ανά λεπτό ανά κλειδί API, συμπεριλαμβανομένων των καταστροφικών εντολών. Ο ίδιος προϋπολογισμός διαμοιράζεται με τα εργαλεία εντολών MCP, με τις αλλαγές πολιτικής (κάθε κλήση propose και apply) και με τα QR codes προετοιμασίας (provisioning), μέσω REST ή MCP. Μέσω REST, τα αιτήματα πέραν του ορίου λαμβάνουν HTTP 429 με κεφαλίδα Retry-After.

Στα τελικά σημεία lock, lost-mode, found και message, μόνο τα κλειδιά με DEVICES_COMMAND καταναλώνουν αυτόν τον προϋπολογισμό, και ένα αίτημα με μη έγκυρο σώμα ή άγνωστο αναγνωριστικό asset εξακολουθεί να προσμετράται, επειδή το όριο εφαρμόζεται πριν από την επικύρωση του αιτήματος. Τα υπόλοιπα τελικά σημεία εντολών, οι κλήσεις αλλαγής πολιτικής και τα αιτήματα QR code προετοιμασίας τον καταναλώνουν μόνο αφού το αίτημα περάσει τους ελέγχους δικαιωμάτων και την επικύρωση ορισμάτων.

Ίχνος ελέγχου

Κάθε εντολή καταγράφεται στο ιστορικό εντολών της συσκευής στην πύλη Nomid και αποδίδεται στο κλειδί API που την έστειλε, όχι σε κάποιο άτομο. Η εγγραφή εμφανίζει το api-key, το αναγνωριστικό του κλειδιού και το πρόθεμα του κλειδιού. Το ιστορικό που επιστρέφεται από το GET /assets/ASSET_ID/commands και από το εργαλείο MCP list_device_commands περιέχει μόνο τα type, status, createdAt, feedbackAt και outcome, όχι το ποιος έστειλε την εντολή.

• Αναφορά API Assets
• Διαχείριση σφαλμάτων
• Οδηγός διακομιστή MCP