Αλλαγές πολιτικής

Πώς λειτουργεί

Κάθε αλλαγή απαιτεί δύο βήματα. Πρώτα την προτείνετε: το API καταγράφει μια πρόταση και επιστρέφει τη λίστα αλλαγών της, με την τρέχουσα και τη νέα τιμή κάθε ρύθμισης, τον αντίκτυπο και τον χρόνο λήξης της πρότασης. Τίποτα δεν αλλάζει ακόμα στην πολιτική. Στη συνέχεια εφαρμόζετε την πρόταση βάσει του proposalId της, αφού ο υπεύθυνος ελέγξει τη λίστα αλλαγών.

Μόνο το κλειδί API που δημιούργησε μια πρόταση μπορεί να την αναγνώσει ή να την εφαρμόσει. Για μια σύνδεση OAuth, μόνο η ίδια σύνδεση και ο ίδιος χρήστης μπορούν. Μια πρόταση λήγει 10 λεπτά μετά τη δημιουργία της· το πεδίο expiresAt παρέχει την ακριβή ώρα.

Μόνο οι πολιτικές Android μπορούν να τροποποιηθούν με αυτόν τον τρόπο. Οι πολιτικές που διαχειρίζεται το Nomid δεν μπορούν. Η δημιουργία μιας πολιτικής απαιτεί επίσης τη σύνδεση της εταιρείας με το Android Enterprise.

Απαιτήσεις

• Ένα κλειδί API με το δικαίωμα POLICIES_WRITE (Αλλαγές πολιτικής), σε συνδυασμό με το POLICIES_READ. Μόνο ένας χρήστης της πύλης με δικαίωμα επεξεργασίας πολιτικών μπορεί να δημιουργήσει κλειδί με το POLICIES_WRITE. Απαιτείται από τα τέσσερα τελικά σημεία POST και τα εργαλεία αλλαγής πολιτικής MCP.
• Η ρύθμιση εταιρείας Αλλαγές πολιτικής, στην ενότητα Πρόσβαση πράκτορα AI στην πύλη, πρέπει να είναι ενεργοποιημένη. Είναι απενεργοποιημένη από προεπιλογή. Ενώ είναι απενεργοποιημένη, κάθε κλήση proposal και apply επιστρέφει 403. Η ανάγνωση ρυθμίσεων, αναθεωρήσεων και προτάσεων απαιτεί μόνο POLICIES_READ.
• Οι πελάτες MCP που συνδέονται με Σύνδεση μέσω Nomid αντί για κλειδί API χρειάζονται το εύρος mcp:policies:write.

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

Όλες οι διαδρομές είναι σχετικές με τη βασική διεύθυνση URL του API και απαιτούν την κεφαλίδα X-API-Key. Τα σώματα των αιτημάτων είναι JSON.

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

Η πρόταση

Κάθε τελικό σημείο propose και τα τελικά σημεία get και apply επιστρέφουν την πρόταση. Τα πιο χρήσιμα πεδία:

Αντίκτυπος και επιβεβαίωση

Μια πρόταση έχει αντίκτυπο HIGH όταν η πολιτική έχει τουλάχιστον μία συσκευή και ισχύει οποιοδήποτε από τα παρακάτω:

• Είναι επαναφορά (rollback).
• Αλλάζει μια ρύθμιση υψηλού αντίκτυπου: εφαρμογές από άγνωστες πηγές, Google Play Protect, επαναφορά εργοστασιακών ρυθμίσεων, επιλογές για προγραμματιστές, μεταφορά δεδομένων μέσω USB ή κρυπτογράφηση χώρου αποθήκευσης.
• Η πολιτική έχει 50 ή περισσότερες συσκευές, ανεξάρτητα από την αλλαγή.

Όλα τα υπόλοιπα είναι NORMAL, συμπεριλαμβανομένης κάθε νέας πολιτικής, καθώς καμία συσκευή δεν τη χρησιμοποιεί ακόμα.

Οι προτάσεις είναι καρφιτσωμένες σε μια έκδοση πολιτικής

Μια πρόταση καταγράφει την έκδοση πολιτικής πάνω στην οποία δημιουργήθηκε η λίστα αλλαγών της. Εάν η πολιτική αποθηκευτεί ξανά πριν εφαρμόσετε την πρόταση, από οποιονδήποτε και από οπουδήποτε, η εφαρμογή αποτυγχάνει με 409 και κωδικό stale_proposal, και τίποτα δεν αλλάζει. Διαβάστε ξανά την πολιτική, προτείνετε ξανά και ελέγξτε τη νέα λίστα αλλαγών.

Παράδειγμα: πρόταση και εφαρμογή

Διαβάστε πρώτα τις τρέχουσες ρυθμίσεις της πολιτικής, για να λάβετε τα αναγνωριστικά ρυθμίσεων (setting IDs) και τις επιτρεπόμενες τιμές:

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

Προτείνετε τον αποκλεισμό της κάμερας και της μεταφοράς δεδομένων μέσω 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
}

Συνοπτική απόκριση. Η μεταφορά δεδομένων μέσω USB είναι μια ρύθμιση υψηλού αντίκτυπου και η πολιτική διαθέτει συσκευές, επομένως η πρόταση έχει αντίκτυπο HIGH και απαιτεί επιβεβαίωση. Δείξτε τη λίστα αλλαγών στον υπεύθυνο πριν την εφαρμόσετε.

Μόλις εγκρίνουν και πληκτρολογήσουν το όνομα της πολιτικής, εφαρμόστε την πρόταση με αυτό που πληκτρολόγησαν:

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

Συνοπτική απόκριση. Οι συσκευές στην πολιτική εφαρμόζουν τις νέες ρυθμίσεις στον επόμενο συγχρονισμό τους.

Όταν η πολιτική άλλαξε στο μεταξύ

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
}

Επεξεργάσιμες ρυθμίσεις

Αυτά είναι τα αναγνωριστικά ρυθμίσεων (setting IDs) που γίνονται δεκτά σε αλλαγές, μαζί με τις επιτρεπόμενες τιμές τους. Η ετικέτα είναι το όνομα που επιστρέφει το API στη λίστα αλλαγών.

Κατά την ανάγνωση ρυθμίσεων, μια τιμή μπορεί επίσης να είναι NOT_SET (αφήνεται στη συσκευή ή στην προεπιλογή της Google) ή CUSTOM (μια τιμή που έχει οριστεί στην πύλη και την οποία αυτές οι τιμές δεν μπορούν να εκφράσουν). Καμία από τις δύο δεν μπορεί να σταλεί, αλλά και οι δύο μπορούν να αντικατασταθούν με μια επιτρεπόμενη τιμή.

Εργαλεία MCP

Ο διακομιστής MCP εκθέτει τις ίδιες λειτουργίες ως εργαλεία. Δέχονται τα ίδια ορίσματα με τα τελικά σημεία REST, με τα policyId και proposalId ως ορίσματα αντί για τμήματα διαδρομής (path segments).

Ένας βοηθός πρέπει να δείξει στον χρήστη τη λίστα αλλαγών και να λάβει τη ρητή έγκρισή του στη συνομιλία πριν καλέσει το apply_policy_proposal. Για μια πρόταση ΥΨΗΛΟΥ αντικτύπου (HIGH), πρέπει να ζητήσει από τον χρήστη να πληκτρολογήσει το όνομα της πολιτικής και να διαβιβάσει ακριβώς αυτό που πληκτρολόγησε.

Σφάλματα

Μόλις επικυρωθεί το κλειδί API, τα σφάλματα χρησιμοποιούν το application/problem+json με δύο επιπλέον πεδία: το code, ένα σταθερό αναγνωριστικό για διακλάδωση, και το retryable, το οποίο δηλώνει εάν το ίδιο αίτημα μπορεί να σταλεί ξανά. Ένα κλειδί που λείπει ή δεν είναι έγκυρο λαμβάνει την κοινόχρηστη απόκριση 401, ένα μικρό αντικείμενο JSON με error, message και status. Τα εργαλεία MCP επιστρέφουν τον ίδιο κωδικό και μήνυμα ως σφάλμα εργαλείου.

Όρια ρυθμού αιτημάτων

Κάθε κλήση propose και apply προσμετράται στο όριο εγγραφής των 10 αιτημάτων ανά λεπτό για κάθε κλειδί API ή σύνδεση Sign in with Nomid, κοινόχρηστο με τα τελικά σημεία εντολών συσκευής, τους κωδικούς QR προετοιμασίας και τα εργαλεία εγγραφής MCP. Οι κλήσεις ανάγνωσης δεν προσμετρώνται σε αυτό.

Αναθεωρήσεις και επαναφορά

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