Richtlinienänderungen

So funktioniert es

Jede Änderung erfolgt in zwei Schritten. Zuerst schlagen Sie sie vor: Die API erfasst einen Vorschlag und gibt dessen Änderungsliste zurück, mit dem aktuellen und neuen Wert jeder Einstellung, den Auswirkungen und dem Zeitpunkt, zu dem der Vorschlag abläuft. An der Richtlinie ändert sich vorerst nichts. Anschließend wenden Sie den Vorschlag anhand seiner proposalId an, nachdem die zuständige Person die Änderungsliste überprüft hat.

Nur der API-Schlüssel, der einen Vorschlag erstellt hat, kann ihn lesen oder anwenden. Bei einer OAuth-Verbindung können dies nur dieselbe Verbindung und derselbe Benutzer. Ein Vorschlag läuft 10 Minuten nach seiner Erstellung ab; das Feld expiresAt gibt den genauen Zeitpunkt an.

Nur Android-Richtlinien können auf diese Weise geändert werden. Von Nomid verwaltete Richtlinien können dies nicht. Das Erstellen einer Richtlinie erfordert außerdem, dass das Unternehmen mit Android Enterprise verbunden ist.

Voraussetzungen

• Ein API-Schlüssel mit der Berechtigung POLICIES_WRITE (Richtlinienänderungen), kombiniert mit POLICIES_READ. Nur ein Portal-Benutzer mit der Berechtigung zum Bearbeiten von Richtlinien kann einen Schlüssel mit POLICIES_WRITE erstellen. Erforderlich für die vier POST-Endpunkte und die MCP-Tools für Richtlinienänderungen.
• Die Unternehmenseinstellung „Richtlinienänderungen“ unter „KI-Agenten-Zugriff“ im Portal muss aktiviert sein. Sie ist standardmäßig deaktiviert. Solange sie deaktiviert ist, gibt jeder Vorschlags- und Anwendungsaufruf den Status 403 zurück. Das Lesen von Einstellungen, Revisionen und Vorschlägen erfordert lediglich POLICIES_READ.
• MCP-Clients, die sich statt mit einem API-Schlüssel über „Mit Nomid anmelden“ verbinden, benötigen den Scope mcp:policies:write.

Endpunkte

Alle Pfade sind relativ zur API-Basis-URL und erfordern den X-API-Key-Header. Anfragetexte sind im JSON-Format.

Request-Bodys

Der Vorschlag

Jeder Vorschlags-Endpunkt sowie die Get- und Apply-Endpunkte geben den Vorschlag zurück. Die nützlichsten Felder:

Auswirkung und Bestätigung

Ein Vorschlag hat die Auswirkung HIGH, wenn die Richtlinie mindestens ein Gerät umfasst und mindestens eine der folgenden Bedingungen zutrifft:

• Es handelt sich um ein Rollback.
• Es ändert eine Einstellung mit hoher Auswirkung: Apps aus unbekannten Quellen, Google Play Protect, Zurücksetzen auf Werkseinstellungen, Entwickleroptionen, USB-Datenübertragung oder Speicherverschlüsselung.
• Die Richtlinie umfasst 50 oder mehr Geräte, unabhängig von der Änderung.

Alles andere ist NORMAL, einschließlich jeder neuen Richtlinie, da sie noch von keinem Gerät verwendet wird.

Vorschläge sind an eine Richtlinienversion gebunden

Ein Vorschlag zeichnet die Richtlinienversion auf, auf der seine Änderungsliste basiert. Wenn die Richtlinie vor dem Anwenden des Vorschlags erneut gespeichert wird – von wem und von wo auch immer –, schlägt das Anwenden mit 409 und dem Code stale_proposal fehl, und es ändert sich nichts. Lesen Sie die Richtlinie erneut aus, erstellen Sie den Vorschlag neu und prüfen Sie die neue Änderungsliste.

Beispiel: Vorschlagen und Anwenden

Lesen Sie zuerst die aktuellen Einstellungen der Richtlinie aus, um die Einstellungs-IDs und zulässigen Werte zu erhalten:

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

Vorschlagen, die Kamera und die USB-Datenübertragung zu sperren:

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
}

Gekürzte Antwort. Die USB-Datenübertragung ist eine Einstellung mit hoher Auswirkung und die Richtlinie umfasst Geräte, daher hat der Vorschlag die Auswirkung HIGH und erfordert eine Bestätigung. Zeigen Sie der zuständigen Person die Änderungsliste, bevor Sie sie anwenden.

Sobald die Person zustimmt und den Namen der Richtlinie eingibt, wenden Sie den Vorschlag mit der eingegebenen Zeichenfolge an:

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

Gekürzte Antwort. Geräte unter dieser Richtlinie wenden die neuen Einstellungen bei ihrer nächsten Synchronisierung an.

Wenn die Richtlinie in der Zwischenzeit geändert wurde

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
}

Bearbeitbare Einstellungen

Dies sind die Einstellungs-IDs, die bei Änderungen akzeptiert werden, zusammen mit ihren zulässigen Werten. Die Beschriftung ist der Name, den die API in der Änderungsliste zurückgibt.

Beim Lesen von Einstellungen kann ein Wert auch NOT_SET (wird dem Gerät oder dem Standard von Google überlassen) oder CUSTOM (ein im Portal festgelegter Wert, den diese Werte nicht ausdrücken können) sein. Keiner von beiden kann gesendet werden, aber beide können durch einen zulässigen Wert ersetzt werden.

MCP-Tools

Der MCP-Server stellt dieselben Operationen als Tools bereit. Sie akzeptieren dieselben Argumente wie die REST-Endpunkte, wobei policyId und proposalId als Argumente anstelle von Pfadsegmenten verwendet werden.

Ein Assistent muss dem Benutzer die Änderungsliste anzeigen und dessen ausdrückliche Zustimmung in der Konversation einholen, bevor er apply_policy_proposal aufruft. Bei einem Vorschlag mit HOHER Auswirkung (HIGH impact) muss er den Benutzer auffordern, den Namen der Richtlinie einzugeben, und genau das übergeben, was eingegeben wurde.

Fehler

Sobald der API-Schlüssel authentifiziert ist, verwenden Fehler application/problem+json mit zwei zusätzlichen Feldern: code, eine stabile Kennung zur Verzweigung, und retryable, das angibt, ob dieselbe Anfrage erneut gesendet werden kann. Ein fehlender oder ungültiger Schlüssel erhält die gemeinsame 401-Antwort, ein kleines JSON-Objekt mit error, message und status. MCP-Tools geben denselben Code und dieselbe Nachricht als Tool-Fehler zurück.

Ratenbegrenzungen

Jeder Propose- und Apply-Aufruf zählt zum Schreiblimit von 10 Anfragen pro Minute für jeden API-Schlüssel oder jede „Sign in with Nomid“-Verbindung, geteilt mit den Gerätebefehls-Endpunkten, Bereitstellungs-QR-Codes und den MCP-Schreibtools. Leseaufrufe zählen nicht dazu.

Revisionen und Rollback

Jede angewendete Änderung speichert eine neue Revision der Richtlinie. Listen Sie Revisionen auf, um zu sehen, wer die Richtlinie wann geändert hat, und schlagen Sie ein Rollback vor, um eine Änderung rückgängig zu machen.