PUT | Atualizar dispositivo

Descrição

Substitua a representação completa de um dispositivo cadastrado no PAM Core utilizando a API v2. Este endpoint sobrescreve todos os campos mutáveis do dispositivo: os campos opcionais omitidos na requisição são redefinidos para o valor padrão ou esvaziados. Para alterar apenas alguns campos, acesse PATCH | Atualizar dispositivo (v2).

Pré-requisitos

• Autorização com permissão de escrita para o PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A API v2.
• O ETag atual do dispositivo, obrigatório no cabeçalho If-Match. Obtenha-o em GET | Listar um dispositivo (v2).
• O dispositivo precisa estar ativo. Operações de escrita em um dispositivo inativo retornam 409. Para ativá-lo, acesse POST | Ativar dispositivo (v2).

Requisição

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

Parâmetros de caminho

Cabeçalhos

Corpo da requisição

O corpo tem o mesmo formato e os mesmos campos obrigatórios de POST | Criar dispositivo (v2): name, address, type, vendor, product e site são obrigatórios, e os campos opcionais são domain_name, tags, criticality, enable_remote_app, network_connector_id, administrator_group_id, owner, connectivities e session_settings. Acesse esse documento para a tabela completa de campos.

Os campos somente leitura são ignorados quando enviados: id, active e connectable. O estado ativo é alterado apenas por POST | Ativar dispositivo (v2) e POST | Desativar dispositivo (v2).

A alteração de name ou address é bloqueada enquanto existir uma sessão ativa do dispositivo no proxy, retornando 409.

Exemplo de requisição

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

Cabeçalhos

Content-Type: application/json
If-Match: "v3"

Corpo

{
    "name": "db-prod-01",
    "address": "10.10.10.10",
    "type": "Server",
    "vendor": "Oracle",
    "product": "Oracle Linux VM",
    "site": "SP-DC1",
    "domain_name": "CORP",
    "tags": ["prod", "database"],
    "criticality": "medium",
    "enable_remote_app": true,
    "network_connector_id": 12,
    "owner": "jdoe",
    "connectivities": [
        {
            "protocol": "SSH",
            "port": 22
        }
    ]
}

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). No exemplo a seguir, session_settings foi omitido na requisição e, por isso, foi redefinido para um array vazio.

{
    "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": "CORP",
            "tags": ["prod", "database"],
            "criticality": "medium",
            "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": []
        }
    },
    "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.

Erros

Exemplo de resposta de erro

412 o dispositivo foi alterado depois da leitura:

{
    "error": {
        "code": "api.precondition.failed",
        "message": "The If-Match header does not match the current ETag."
    }
}

Erros de autenticação

Documentos relacionados

• API v2 - Convenções e comportamentos compartilhados
• PATCH | Atualizar dispositivo (v2)
• GET | Listar um dispositivo (v2)
• POST | Criar dispositivo (v2)
• Como gerenciar autorizações no A2A API v2