Press CTRL+K to open search

PATCH | Atualizar dispositivo

Prev Next

Descrição

Atualize campos específicos de um dispositivo cadastrado no PAM Core utilizando a API v2. O endpoint segue a semântica JSON Merge Patch (RFC 7396): apenas os campos enviados são alterados, e os campos omitidos são preservados. Para substituir o dispositivo por completo, acesse PUT | Atualizar dispositivo (v2).

Info

Este endpoint faz parte da superfície da API v2 do A2A e está disponível a partir da versão 4.2.9 do Segura®. Os dispositivos são servidos pelo caminho base /api/v2/platform, e não por /api/v2/pam como os demais recursos v2. Não há equivalente v1: a v1 não oferecia atualização parcial.

Pré-requisitos

Requisição

PATCH /api/v2/platform/devices/{id}

Parâmetros de caminho

Campo Tipo Obrigatório Descrição
id integer Sim Código de identificação único do dispositivo. Nota: este valor é atribuído pelo Segura® em POST | Criar dispositivo (v2).

Cabeçalhos

Cabeçalho Obrigatório Descrição
Content-Type Sim Precisa ser application/merge-patch+json. Qualquer outro tipo de mídia retorna 415.
If-Match Sim ETag atual do dispositivo, para controle de concorrência otimista. A ausência do cabeçalho retorna 428; um valor que não corresponde mais ao estado atual retorna 412.

Corpo da requisição

Todos os campos são opcionais. Um campo enviado substitui o valor atual; um campo enviado como null remove o valor; um campo omitido permanece inalterado. Os campos de array são substituídos por completo, e não mesclados item a item.

Campo Tipo Descrição
name string Nome que identifica o dispositivo. Bloqueado enquanto existir uma sessão ativa do dispositivo no proxy.
address string Endereço IP, hostname ou URL de gerenciamento. Bloqueado enquanto existir uma sessão ativa do dispositivo no proxy.
type string Tipo do dispositivo, por nome. Precisa ser um tipo cadastrado.
vendor string Fabricante do dispositivo, por nome. Precisa ser um fabricante cadastrado.
product string Modelo do dispositivo, por nome. Precisa ser um modelo cadastrado e vinculado ao fabricante.
site string Site onde o dispositivo está localizado, por nome. Precisa ser um site cadastrado.
domain_name string Domínio associado ao dispositivo, por nome. Envie null para removê-lo.
tags array[string] Tags associadas ao dispositivo. Substitui a lista completa.
criticality string Nível de criticidade. Valores permitidos: low, medium, high. Envie null para removê-lo.
enable_remote_app boolean Habilita o suporte a aplicação remota para o dispositivo.
network_connector_id integer Código de identificação do agent do Network Connector. Envie null para remover a associação. A resposta o expande em um objeto.
administrator_group_id integer Código de identificação do grupo administrador. Válido apenas quando o modo de política de acesso é estático por dispositivo; enviá-lo no modo de política dinâmica retorna 422. Envie null para removê-lo.
owner string Nome de usuário do usuário cadastrado responsável pelo dispositivo. Envie null para removê-lo.
connectivities array de objetos Protocolos de conectividade, no formato { protocol, port }. Substitui a lista completa. Protocolos permitidos: SSH, RDP, HTTPS, VNC, Telnet, SQL_Server.
session_settings array de objetos Configurações de automação de sessão, no formato { connectivity, expected_expression, fill_in_value }. Substitui a lista completa. O connectivity precisa corresponder a um protocolo presente em connectivities.
Atenção

Os campos id e active não podem ser alterados por este endpoint e retornam 422 (patch.field.not_allowed). Altere o estado ativo com POST | Ativar dispositivo (v2) ou POST | Desativar dispositivo (v2).

Exemplo de requisição

PATCH {{url}}/api/v2/platform/devices/55

Cabeçalhos

Content-Type: application/merge-patch+json
If-Match: "v3"

Corpo

{
    "criticality": "low",
    "tags": ["prod", "finance", "critical"],
    "domain_name": null
}

Resposta

HTTP/1.1 200 OK
ETag: "v4"

O cabeçalho ETag traz a nova versão do dispositivo. Utilize este valor no cabeçalho If-Match da próxima operação de escrita.

Exemplo de corpo da resposta

A resposta retorna o dispositivo completo, no mesmo formato de GET | Listar um dispositivo (v2), inclusive os campos que a requisição não alterou.

{
    "data": {
        "id": "55",
        "device": {
            "name": "db-prod-01",
            "address": "10.10.10.10",
            "active": true,
            "type": "Server",
            "vendor": "Oracle",
            "product": "Oracle Linux VM",
            "site": "SP-DC1",
            "domain_name": null,
            "tags": ["prod", "finance", "critical"],
            "criticality": "low",
            "owner": {
                "name": "John Doe"
            },
            "administrator_group": null,
            "enable_remote_app": true,
            "network_connector": {
                "id": "12",
                "name": "NC-SP-01",
                "port": "50001"
            },
            "connectivities": [
                {
                    "protocol": "SSH",
                    "port": 22,
                    "connectable": true
                }
            ],
            "session_settings": [
                {
                    "connectivity": "SSH",
                    "expected_expression": "$",
                    "fill_in_value": "sudo su"
                }
            ]
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/devices/55"
        },
        "actions": {
            "deactivate": "/api/v2/platform/devices/55/deactivate"
        }
    }
}

Campos do corpo da resposta

A resposta retorna o dispositivo atualizado com os mesmos campos de GET | Listar um dispositivo (v2). Acesse esse documento para as tabelas completas de campos.

Campo Tipo Descrição
data object O dispositivo atualizado.
data.id string Código de identificação único do dispositivo.
data.device object Atributos canônicos do dispositivo após a atualização.
meta object Links de navegação e ações disponíveis.
meta.links.self string URL do dispositivo.
meta.actions object Ações disponíveis para o dispositivo em seu estado atual.

Erros

Código HTTP Mensagem Causa possível Solução
400 api.request.malformed O corpo não é um JSON válido. Verifique a sintaxe do payload.
401 api.auth.token.invalid O token de acesso está ausente ou expirou. Solicite um novo token de acesso.
403 api.permission.denied A autorização não tem permissão de escrita para os recursos do PAM Core. Peça ao administrador para verificar as permissões da autorização no A2A e gere um novo token.
404 api.resource.not_found O dispositivo não existe ou pertence a outro tenant. Verifique o código de identificação enviado no caminho.
409 api.resource.conflict.active_sessions Existe uma sessão ativa do dispositivo no proxy, o que bloqueia alterações em name e address. Aguarde o encerramento da sessão, ou encerre-a, e reenvie a requisição.
409 api.resource.inactive O dispositivo está inativo, portanto operações de escrita não são permitidas. Ative o dispositivo com POST | Ativar dispositivo (v2) e reenvie a requisição.
412 api.precondition.failed O valor de If-Match não corresponde ao ETag atual: o dispositivo foi alterado depois da sua leitura. Consulte o dispositivo novamente para obter o ETag atual, reaplique suas alterações e reenvie a requisição.
415 Unsupported Media Type O cabeçalho Content-Type não é application/merge-patch+json. Envie o tipo de mídia correto.
428 api.precondition.required O cabeçalho If-Match está ausente. Envie o ETag atual no cabeçalho If-Match.
422 patch.field.not_allowed O corpo inclui id ou active. Remova o campo. Utilize as ações de ativar e desativar para alterar o estado.
422 api.validation.invalid_reference Um tipo, fabricante, modelo, site, domínio, Network Connector ou usuário referenciado não existe; um protocolo de session_settings não está declarado em connectivities; ou o administrator_group_id foi enviado com o modo de política de acesso dinâmico. Cadastre o valor antes ou remova o campo. Consulte error.details para identificar o campo.
422 api.enum.invalid_value O criticality recebeu um valor fora de low, medium, high. Envie um dos valores permitidos.
429 rate_limit_exceeded O limite de requisições foi excedido. Aguarde o número de segundos indicado no cabeçalho Retry-After e tente novamente.
500 api.internal.error Erro interno do servidor. Entre em contato com a equipe de suporte da Segura®.

Exemplo de resposta de erro

422 um campo proibido foi enviado no corpo:

{
    "error": {
        "code": "patch.field.not_allowed",
        "message": "Field 'active' cannot be modified via PATCH."
    }
}

Erros de autenticação

Mensagem Causa possível Solução
Client authentication failed. Falha na autenticação da aplicação com o servidor Segura®. Verifique os parâmetros de autenticação (Access Token URL, Client ID e Client secret) e solicite um novo token de acesso.
Invalid signature Falha no reconhecimento da URL da aplicação cliente. Verifique a URL da aplicação cliente e reenvie a requisição.
No route matched with those values. Cabeçalho de autorização ausente na requisição da API. Solicite um novo token de acesso.
Request timed out. A requisição excedeu o limite de tempo. Verifique a conectividade entre a origem da requisição e o servidor Segura®.

Documentos relacionados

A Soberania Digital é um direito fundamental para os cidadãos, instituições e sociedade. É por isso que trabalhamos todos os dias.
Conecte-se conosco
SEGURA
LEARN
EXPLORE
Copyright © Segura. Todos os direitos reservados