Zmiany zasad

Jak to działa

Każda zmiana wymaga dwóch kroków. Najpierw ją proponujesz: API rejestruje wniosek i zwraca listę zmian z bieżącą i nową wartością każdego ustawienia, wpływem oraz terminem wygaśnięcia wniosku. W zasadzie nic się jeszcze nie zmienia. Następnie stosujesz wniosek na podstawie jego proposalId, po tym jak osoba odpowiedzialna przejrzy listę zmian.

Tylko klucz API, który utworzył wniosek, może go odczytać lub zastosować. W przypadku połączenia OAuth może to zrobić tylko to samo połączenie i ten sam użytkownik. Wniosek wygasa po 10 minutach od jego utworzenia; pole expiresAt podaje dokładny czas.

W ten sposób można zmieniać wyłącznie zasady Androida. Zasad zarządzanych przez Nomid nie można modyfikować w ten sposób. Utworzenie zasady wymaga również, aby firma była połączona z Android Enterprise.

Wymagania

• Klucz API z uprawnieniem POLICIES_WRITE (Zmiany zasad), połączonym z POLICIES_READ. Tylko użytkownik portalu z uprawnieniem do edycji zasad może utworzyć klucz z uprawnieniem POLICIES_WRITE. Wymagany przez cztery punkty końcowe POST oraz narzędzia MCP do wprowadzania zmian w zasadach.
• Ustawienie firmowe Zmiany zasad, w sekcji Dostęp agenta AI w portalu, musi być włączone. Domyślnie jest wyłączone. Gdy jest wyłączone, każde wywołanie propozycji i zastosowania zwraca kod 403. Odczytywanie ustawień, wersji i propozycji wymaga tylko uprawnienia POLICIES_READ.
• Klienci MCP, którzy łączą się za pomocą opcji Zaloguj się przez Nomid zamiast klucza API, wymagają zakresu mcp:policies:write.

Punkty końcowe

Wszystkie ścieżki są względne wobec bazowego adresu URL API i wymagają nagłówka X-API-Key. Ciała żądań są w formacie JSON.

Treści żądań

Propozycja

Każdy punkt końcowy propozycji oraz punkty końcowe pobierania i stosowania zwracają propozycję. Najbardziej przydatne pola:

Wpływ i potwierdzenie

Propozycja ma wpływ HIGH, gdy polityka obejmuje co najmniej jedno urządzenie i spełniony jest dowolny z poniższych warunków:

• Jest to wycofanie zmian.
• Zmienia ustawienie o dużym wpływie: aplikacje z nieznanych źródeł, Google Play Protect, przywracanie ustawień fabrycznych, opcje programisty, przesyłanie danych przez USB lub szyfrowanie pamięci masowej.
• Polityka obejmuje co najmniej 50 urządzeń, niezależnie od zmiany.

Wszystko inne ma status NORMAL, w tym każda nowa polityka, ponieważ żadne urządzenie jeszcze z niej nie korzysta.

Propozycje są przypisane do wersji polityki

Propozycja rejestruje wersję polityki, na podstawie której utworzono jej listę zmian. Jeśli polityka zostanie ponownie zapisana przed zastosowaniem propozycji – przez kogokolwiek i skądkolwiek – zastosowanie nie powiedzie się z kodem 409 i kodem stale_proposal, a nic nie ulegnie zmianie. Odczytaj politykę ponownie, zgłoś propozycję jeszcze raz i przejrzyj nową listę zmian.

Przykład: zgłoszenie propozycji i zastosowanie

Najpierw odczytaj bieżące ustawienia polityki, aby uzyskać identyfikatory ustawień i dozwolone wartości:

curl "https://api.nomid.tech/emm/api/v1/policies/p7k2m9qa4xz/settings" \
  -H "X-API-Key: $NOMID_API_KEY"

{
  "policyId": "p7k2m9qa4xz",
  "displayName": "Warehouse scanners",
  "version": 12,
  "deviceCount": 18,
  "editable": true,
  "settings": [
    {
      "id": "CAMERA",
      "label": "Camera",
      "group": "RESTRICTIONS",
      "value": "ALLOW",
      "allowedValues": ["ALLOW", "BLOCK"],
      "highImpact": false
    }
  ]
}

Zaproponuj zablokowanie aparatu i przesyłania danych przez USB:

curl -X POST "https://api.nomid.tech/emm/api/v1/policies/p7k2m9qa4xz/changes" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"changes": [{"setting": "CAMERA", "value": "BLOCK"}, {"setting": "USB_DATA_ACCESS", "value": "BLOCK"}]}'

HTTP/1.1 201 Created

{
  "capability": "update_policy_settings",
  "status": "PENDING",
  "title": "Edit policy settings",
  "summary": "Change 2 settings of policy \"Warehouse scanners\". 18 devices apply it on their next sync. High impact: type the policy's name to confirm.",
  "target": { "kind": "policy", "id": "p7k2m9qa4xz", "name": "Warehouse scanners" },
  "fields": [
    { "label": "Camera", "value": "BLOCK", "previousValue": "ALLOW" },
    { "label": "USB data transfer", "value": "BLOCK", "previousValue": "ALLOW" }
  ],
  "expiresAt": "2026-10-09T14:40:00Z",
  "impact": "HIGH",
  "proposalId": "prp_7GQv2LkR9sTn4WxY8bZcA1dE",
  "requiresConfirmation": true
}

Skrócona odpowiedź. Przesyłanie danych przez USB jest ustawieniem o dużym wpływie, a polityka ma przypisane urządzenia, więc propozycja ma wpływ HIGH i wymaga potwierdzenia. Przed zastosowaniem propozycji pokaż listę zmian osobie odpowiedzialnej.

Gdy osoba ta zatwierdzi zmianę i wpisze nazwę polityki, zastosuj propozycję wraz z wpisaną przez nią wartością:

curl -X POST "https://api.nomid.tech/emm/api/v1/policy-proposals/prp_7GQv2LkR9sTn4WxY8bZcA1dE/apply" \
  -H "X-API-Key: $NOMID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation": "Warehouse scanners"}'

HTTP/1.1 200 OK

{
  "capability": "update_policy_settings",
  "status": "SUCCEEDED",
  "impact": "HIGH",
  "proposalId": "prp_7GQv2LkR9sTn4WxY8bZcA1dE",
  "requiresConfirmation": true,
  "result": {
    "policyId": "p7k2m9qa4xz",
    "displayName": "Warehouse scanners",
    "version": 13,
    "message": "Policy settings changed. Devices on the policy apply them on their next sync."
  }
}

Skrócona odpowiedź. Urządzenia objęte polityką zastosują nowe ustawienia podczas kolejnej synchronizacji.

Gdy polityka zmieniła się w międzyczasie

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Policy \"Warehouse scanners\" was changed after this proposal was made. Nothing was applied: read it again and propose again.",
  "instance": "/emm/api/v1/policy-proposals/prp_7GQv2LkR9sTn4WxY8bZcA1dE/apply",
  "code": "stale_proposal",
  "retryable": false
}

Edytowalne ustawienia

Oto identyfikatory ustawień akceptowane w zmianach wraz z ich dozwolonymi wartościami. Etykieta to nazwa zwracana przez API na liście zmian.

Podczas odczytu ustawień wartością może być także NOT_SET (pozostawiona urządzeniu lub domyślna dla Google) lub CUSTOM (wartość ustawiona w portalu, której te wartości nie mogą wyrazić). Żadnej z nich nie można wysłać, ale obie można zastąpić wartością dozwoloną.

Narzędzia MCP

Serwer MCP udostępnia te same operacje jako narzędzia. Przyjmują one te same argumenty co punkty końcowe REST, z policyId i proposalId jako argumentami zamiast segmentów ścieżki.

Asystent musi pokazać użytkownikowi listę zmian i uzyskać jego wyraźną zgodę w konwersacji, zanim wywoła apply_policy_proposal. W przypadku wniosku o statusie HIGH impact musi poprosić użytkownika o wpisanie nazwy zasady i przekazać dokładnie to, co wpisał.

Błędy

Po uwierzytelnieniu klucza API błędy używają formatu application/problem+json z dwoma dodatkowymi polami: code, czyli stałym identyfikatorem do rozgałęziania logiki, oraz retryable, który określa, czy to samo żądanie może zostać wysłane ponownie. Brakujący lub nieprawidłowy klucz powoduje zwrócenie wspólnej odpowiedzi 401, czyli małego obiektu JSON z polami error, message i status. Narzędzia MCP zwracają ten sam kod i komunikat jako błąd narzędzia.

Limity szybkości (Rate limits)

Każde wywołanie propose i apply wlicza się do limitu zapisu wynoszącego 10 żądań na minutę dla każdego klucza API lub połączenia Sign in with Nomid, współdzielonego z punktami końcowymi poleceń urządzeń, kodami QR do aprowizacji i narzędziami zapisu MCP. Wywołania odczytu nie wliczają się do tego limitu.

Wersje i wycofywanie zmian

Każda zastosowana zmiana zapisuje nową wersję polityki. Wyświetl listę wersji, aby zobaczyć, kto i kiedy zmienił politykę, oraz zaproponuj wycofanie, aby cofnąć zmianę.