Polecenia urządzeń

Przegląd

Każde wywołanie dotyczy dokładnie jednego urządzenia, identyfikowanego przez jego assetId, który jest wartością pathName zwracaną przez GET /assets. Nie ma punktu końcowego do operacji zbiorczych. Aby wysłać polecenie do kilku urządzeń, wykonaj jedno wywołanie na urządzenie w ramach limitu żądań. Punkty końcowe działają tak samo jak narzędzia poleceń MCP.

Klucz wymaga uprawnień DEVICES_COMMAND i DEVICES_READ. change-policy wymaga również POLICIES_READ. Polecenia destrukcyjne wymagają zamiast tego DEVICES_COMMAND_DESTRUCTIVE i DEVICES_READ. Wyślij klucz w nagłówku X-API-Key. Interfejs REST API nie akceptuje nagłówka Authorization.

Urządzenie musi być zarejestrowane (stan ACTIVE, INACTIVE lub SYNCHRONIZING). Niektóre polecenia działają tylko na jednym typie urządzeń, zgodnie z poniższymi opisami: urządzenia z Android Management (zarządzane przez Google) lub urządzenia zarządzane przez agenta Nomid (AOSP). W przypadku każdego innego urządzenia zwracany jest kod 409. Wiadomość jest powiadomieniem push wysyłanym do agenta Nomid i wymaga zarejestrowanego tokenu push.

Punkty końcowe

Przesyłaj Content-Type: application/json wraz z punktami końcowymi lost-mode, message, launch-app, clear-app-data, change-policy oraz change-screen-lock-password. Pozostałe punkty końcowe nie przyjmują treści. Nieznane pola są odrzucane, a wymagane pola tekstowe nie mogą być puste.

Polecenia destrukcyjne

Cztery polecenia usuwają dane, zdejmują lub zmieniają blokadę ekranu bądź kończą zarządzanie urządzeniem. W przypadku użycia klucza API są one wykonywane natychmiast po zaakceptowaniu żądania. W portalu nie ma etapu zatwierdzania.

Wymagają one klucza API z uprawnieniami DEVICES_COMMAND_DESTRUCTIVE oraz DEVICES_READ. Firma musi również włączyć polecenia destrukcyjne w sekcji dostępu agenta AI w portalu. To ustawienie jest domyślnie wyłączone i wymaga także włączenia poleceń urządzeń. Bez tego żądanie zwraca kod 403 z błędem forbidden.

Polecenie change-screen-lock-password przyjmuje nowe hasło w newPassword. Nomid nigdy go nie przechowuje, nie zwraca ani nie zapisuje w dziennikach.

Treści żądań

Treść żądania trybu utraconego

Treść żądania wiadomości

Przykład: wyślij wiadomość

Zastąp identyfikator zasobu (asset id) wartością pathName z GET /assets i przechowuj klucz w zmiennej środowiskowej.

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"
}

Odpowiedź 200 oznacza, że polecenie zostało utworzone. Pole status określa stan polecenia w momencie zwrócenia żądania. W przypadku wiadomości SUCCESS oznacza, że powiadomienie push zostało zaakceptowane do doręczenia, a nie, że użytkownik je wyświetlił. Sprawdź dalsze informacje za pomocą GET /assets/ASSET_ID/commands.

Przykład: zablokuj urządzenie

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"
}

Blokada i tryb utracony (lost mode) zwracają IN_PROGRESS, dopóki urządzenie nie potwierdzi polecenia. Gdy to nastąpi, historia poleceń pokazuje SUCCESS. Punkt końcowy lock nie przyjmuje treści żądania.

Przykład: wyczyszczenie urządzenia

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"
}

Wyczyszczenie urządzenia zarządzanego przez Android Management odpowiada statusem IN_PROGRESS bez pola createdAt. Sprawdź historię poleceń, aby śledzić postęp.

Odpowiedzi i dalsze kroki

Zasady ponawiania mają znaczenie. Ponowienie próby wykonania polecenia, którego wynik jest nieznany, może spowodować jego dwukrotne doręczenie.

Treści błędów

Błędy z punktów końcowych poleceń używają application/problem+json (RFC 9457). W punktach końcowych lock, lost-mode, found i message kody 401 oraz 429 zwracają mały obiekt JSON z polami error, message i status, 404 nie ma treści, a tylko 502 i 503 dodają logiczne pole retryable. W pozostałych punktach końcowych każdy błąd oprócz 401 jest obiektem szczegółów problemu z polem code, takim jak not_found, unsupported, forbidden, invalid_arguments lub rate_limited, a 429, 500, 502 i 503 zawierają również retryable. Odpowiedź 202 nie jest błędem: zawiera standardowy obiekt wyniku.

Przykładowa odpowiedź 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."
}

Przykładowa odpowiedź 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
}

Przykładowa odpowiedź 404 z punktu końcowego innego niż lock, lost-mode, found i 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"
}

Limit szybkości

Polecenia są ograniczone do 10 na minutę na klucz API, wliczając polecenia destrukcyjne. Ten sam budżet jest współdzielony z narzędziami poleceń MCP, ze zmianami zasad (każde wywołanie propose i apply) oraz z kodami QR do aprowizacji, za pośrednictwem REST lub MCP. W przypadku REST żądania przekraczające limit otrzymują HTTP 429 z nagłówkiem Retry-After.

W punktach końcowych lock, lost-mode, found i message tylko klucze z uprawnieniem DEVICES_COMMAND zużywają ten budżet, a żądanie z nieprawidłową treścią lub nieznanym identyfikatorem zasobu nadal się liczy, ponieważ limit jest stosowany przed walidacją żądania. Pozostałe punkty końcowe poleceń, wywołania zmian zasad i żądania kodów QR do aprowizacji zużywają go dopiero po pomyślnym przejściu kontroli uprawnień i walidacji argumentów.

Ścieżka audytu

Każde polecenie jest rejestrowane w historii poleceń urządzenia w portalu Nomid i przypisywane do klucza API, który je wysłał, a nie do osoby. Wpis pokazuje api-key, identyfikator klucza i prefiks klucza. Historia zwracana przez GET /assets/ASSET_ID/commands oraz przez narzędzie MCP list_device_commands zawiera tylko type, status, createdAt, feedbackAt i outcome, bez informacji o tym, kto wysłał polecenie.

• Dokumentacja Assets API
• Obsługa błędów
• Przewodnik po serwerze MCP