Alterações de políticas

Como funciona

Cada alteração tem dois passos. Primeiro propõe-na: a API regista uma proposta e devolve a respetiva lista de alterações, com o valor atual e novo de cada definição, o impacto e a data/hora em que a proposta expira. Nada é alterado na política ainda. Em seguida, aplica a proposta através do seu proposalId, após a pessoa responsável ter revisto a lista de alterações.

Apenas a chave de API que criou uma proposta a pode ler ou aplicar. Para uma ligação OAuth, apenas a mesma ligação e o mesmo utilizador o podem fazer. Uma proposta expira 10 minutos após ser criada; o campo expiresAt indica a hora exata.

Apenas as políticas Android podem ser alteradas desta forma. As políticas geridas pelo Nomid não o podem ser. Criar uma política também exige que a empresa esteja ligada ao Android Enterprise.

Requisitos

• Uma chave de API com a permissão POLICIES_WRITE (Alterações de políticas), combinada com POLICIES_READ. Apenas um utilizador do portal com permissão para editar políticas pode criar uma chave com POLICIES_WRITE. Necessária para os quatro endpoints POST e as ferramentas de alteração de políticas do MCP.
• A definição da empresa Alterações de políticas, em Acesso do agente de IA no portal, tem de estar ativada. Está desativada por predefinição. Enquanto estiver desativada, todas as chamadas de proposta e aplicação devolvem 403. Ler definições, revisões e propostas apenas requer POLICIES_READ.
• Os clientes MCP que se ligam com Iniciar sessão com a Nomid em vez de uma chave de API necessitam do âmbito mcp:policies:write.

Endpoints

Todos os caminhos são relativos ao URL base da API e necessitam do cabeçalho X-API-Key. Os corpos dos pedidos são em formato JSON.

Corpos de pedido

A proposta

Todos os endpoints propose e os endpoints get e apply devolvem a proposta. Os campos mais úteis:

Impacto e confirmação

Uma proposta tem impacto HIGH quando a política tem pelo menos um dispositivo e qualquer uma destas condições for verdadeira:

• É uma reversão.
• Altera uma definição de alto impacto: aplicações de fontes desconhecidas, Google Play Protect, reposição de fábrica, opções de programador, transferência de dados por USB ou encriptação de armazenamento.
• A política tem 50 ou mais dispositivos, independentemente da alteração.

Tudo o resto é NORMAL, incluindo qualquer nova política, uma vez que ainda nenhum dispositivo a utiliza.

As propostas estão fixadas a uma versão da política

Uma proposta regista a versão da política sobre a qual a sua lista de alterações foi criada. Se a política for guardada novamente antes de aplicar a proposta, por qualquer pessoa e a partir de qualquer lugar, a aplicação falha com 409 e o código stale_proposal, e nada é alterado. Leia a política novamente, proponha de novo e reveja a nova lista de alterações.

Exemplo: propor e aplicar

Leia primeiro as definições atuais da política, para obter os IDs das definições e os valores permitidos:

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

Propor o bloqueio da câmara e da transferência de dados por 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
}

Resposta abreviada. A transferência de dados por USB é uma definição de alto impacto e a política tem dispositivos, pelo que a proposta tem impacto HIGH e requer confirmação. Mostre a lista de alterações à pessoa responsável antes de a aplicar.

Assim que aprovarem e escreverem o nome da política, aplique a proposta com o que foi escrito:

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

Resposta abreviada. Os dispositivos na política aplicam as novas definições na sua próxima sincronização.

Quando a política foi entretanto alterada

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
}

Definições editáveis

Estes são os IDs de definição aceites em alterações, com os respetivos valores permitidos. A etiqueta é o nome que a API devolve na lista de alterações.

Ao ler definições, um valor também pode ser NOT_SET (deixado para o dispositivo ou para a predefinição da Google) ou CUSTOM (um valor definido no portal que estes valores não conseguem expressar). Nenhum pode ser enviado, mas ambos podem ser substituídos por um valor permitido.

Ferramentas MCP

O servidor MCP expõe as mesmas operações como ferramentas. Aceitam os mesmos argumentos que os endpoints REST, com policyId e proposalId como argumentos em vez de segmentos de caminho.

Um assistente tem de mostrar a lista de alterações ao utilizador e obter a sua aprovação explícita na conversa antes de chamar apply_policy_proposal. Para uma proposta de impacto HIGH, tem de pedir ao utilizador que escreva o nome da política e transmitir exatamente o que este escreveu.

Erros

Assim que a chave de API é autenticada, os erros usam application/problem+json com dois campos adicionais: code, um identificador estável para bifurcação condicional, e retryable, que indica se o mesmo pedido pode ser enviado novamente. Uma chave em falta ou inválida recebe a resposta 401 partilhada, um pequeno objeto JSON com error, message e status. As ferramentas MCP devolvem o mesmo code e message como um erro da ferramenta.

Limites de taxa

Cada chamada de propose e apply conta para o limite de escrita de 10 pedidos por minuto para cada chave de API ou ligação "Iniciar sessão com o Nomid", partilhado com os endpoints de comandos de dispositivos, códigos QR de aprovisionamento e as ferramentas de escrita MCP. As chamadas de leitura não contam para este limite.

Revisões e reversão

Cada alteração aplicada guarda uma nova revisão da política. Liste as revisões para ver quem alterou a política e quando, e proponha uma reversão para anular uma alteração.