GET | Listar todos os dispositivos

Descrição

Liste os dispositivos associados à sua autorização no PAM Core, utilizando o modelo canônico v2. Retorna uma projeção paginada e filtrável da entidade DeviceV2.

Pré-requisitos

• Autorização com permissão de leitura para o PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A API v2.

Requisição

GET /api/v2/platform/devices

Parâmetros de query

Todos os parâmetros de query são opcionais. Quando nenhum é informado, o endpoint retorna a primeira página de todos os dispositivos acessíveis à autorização, utilizando a projeção de listagem definida no schema de resposta.

Filtros

Os filtros são combinados com lógica AND: o dispositivo precisa atender a todos os filtros informados.

Ordenação

sort_by aceita um ou mais campos no formato campo:asc ou campo:desc. Múltiplos campos são separados por vírgula e processados da esquerda para a direita. A direção padrão é asc. Exemplo: sort_by=name:asc,type:desc.

Campos ordenáveis: name, type, vendor, product, site.

Um campo não suportado retorna 422 (api.sort.invalid_field), com uma indicação dos campos permitidos; uma direção não suportada retorna 422 (api.sort.invalid_direction). Para as regras completas de ordenação, consulte API v2 - Convenções e comportamentos compartilhados.

Projeção de campos

fields restringe a resposta aos campos informados, utilizando caminhos com namespace. Exemplo: fields=id,device.name,device.address.

O campo data[].id é sempre retornado, mesmo que a projeção não o solicite. Um caminho que não existe na projeção de listagem retorna 422 (api.fields.invalid).

Paginação

Um limit acima de 200 retorna 422 (api.pagination.limit.exceeded), e page=0 retorna 422 (api.request.invalid_param). Uma página além da última retorna 200 com o array data vazio e metadados de paginação coerentes.

Exemplo de requisição

GET {{url}}/api/v2/platform/devices?vendor=Oracle&active=true&sort_by=name:asc&limit=50

Resposta

HTTP/1.1 200 OK

Toda resposta traz o cabeçalho X-Request-Id, que correlaciona a requisição nos logs do Segura®.

Exemplo de corpo da resposta

{
    "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"]
            }
        },
        {
            "id": "56",
            "device": {
                "name": "ws-dev-04",
                "address": "10.20.30.40",
                "active": false,
                "type": "Workstation",
                "vendor": "Microsoft",
                "product": "Windows Server 2022",
                "site": "NY-DC2",
                "domain_name": null,
                "tags": []
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 50,
            "total_items": 340,
            "total_pages": 7
        },
        "links": {
            "self": "/api/v2/platform/devices?page=1&limit=50",
            "first": "/api/v2/platform/devices?page=1&limit=50",
            "next": "/api/v2/platform/devices?page=2&limit=50",
            "last": "/api/v2/platform/devices?page=7&limit=50"
        }
    }
}

Campos do corpo da resposta

Erros

Exemplo de resposta de erro

422 um campo solicitado na projeção não existe:

{
    "error": {
        "code": "api.fields.invalid",
        "message": "One or more requested fields do not exist in the resource schema."
    }
}

Erros de autenticação

Para a política de 403 versus 404 aplicada a recursos fora do escopo da sua autorização, consulte API v2 - Convenções e comportamentos compartilhados.

Documentos relacionados

• API v2 - Convenções e comportamentos compartilhados
• GET | Listar um dispositivo (v2)
• POST | Criar dispositivo (v2)
• GET | Listar status de conexão do dispositivo (v2)
• Como gerenciar autorizações no A2A API v2
• Cadastro de dispositivo