GET | Listar todos os agentes do Network Connector

Descrição

Liste os agentes do Network Connector com os códigos de identificação, os nomes, as portas, o status e os fingerprints. Retorna uma lista paginada e filtrável.

Use o id de um agente no campo network_connector_id para vincular um dispositivo a esse agente.

Por padrão, a lista inclui apenas agentes ativos. Para listar os agentes desativados, use o filtro active.

Sem o filtro active, todo id retornado é aceito pelo campo network_connector_id de um dispositivo. Um dispositivo não aceita um agente desativado. Na requisição do dispositivo, envie o id como número inteiro.

Pré-requisitos

Uma aplicação com a Permissão do recurso PAM definida como Apenas leitura ou Leitura e escrita, concedida pelo administrador no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A API v2.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.

Requisição

GET /api/v2/platform/network-connector/agents

Parâmetros de query

Todos os parâmetros de query são opcionais. Sem parâmetros, o endpoint retorna os 50 primeiros agentes ativos, ordenados por nome.

Filtros

Campo	Tipo	Descrição
`name`	string	Filtra pelo nome do agente. Corresponde ao nome exato. Acrescente o sufixo `_contains`, `_starts_with` ou `_ends_with` para uma correspondência parcial. Exemplo: `name_contains=sp`.
`port`	string	Filtra pela porta do agente. Corresponde à porta exata. Aceita os mesmos sufixos de `name`.
`search`	string	Busca um trecho de texto em `name` e em `port`. Quando você envia vários termos separados por espaço, cada termo precisa aparecer.
`active`	boolean	Filtra pelo status do agente. `true` retorna os agentes ativos e `false` retorna os agentes desativados. Padrão: `true`. Para obter todos os agentes, envie uma requisição com `active=true` e outra com `active=false`.

Em um filtro, valores separados por vírgula funcionam como OU. Exemplo: port=30001,30002. Parâmetros diferentes funcionam como E.

Ordenação

Campo	Tipo	Descrição
`sort_by`	string	Ordena o conjunto de resultados no formato `campo:asc` ou `campo:desc`. Campos aceitos: `id`, `name` e `port`. Padrão: `name:asc`, depois `id:asc`.

Para as regras completas de ordenação, acesse API v2 - Convenções e comportamentos compartilhados.

Paginação

Campo	Tipo	Descrição
`page`	integer	Número da página. Mínimo: `1`. Padrão: `1`.
`limit`	integer	Resultados por página. Mínimo: `1`. Máximo: `200`. Padrão: `50`.

Este endpoint aceita apenas a paginação por página. Ele não aceita cursor.

Projeção de campos

Campo	Tipo	Descrição
`fields`	string	Restringe a resposta aos campos listados. Aceita `id`, `network_connector_agent.name`, `network_connector_agent.port`, `network_connector_agent.active` e `network_connector_agent.fingerprint`. O campo `id` é sempre retornado.

Peça cada campo pelo caminho completo. Pedir o objeto inteiro com fields=network_connector_agent retorna 422.

Para a sintaxe completa de projeção de campos, acesse API v2 - Convenções e comportamentos compartilhados.

Exemplo de requisição

GET {{url}}/api/v2/platform/network-connector/agents

Resposta

HTTP/1.1 200 OK

A listagem não retorna o cabeçalho ETag.

Exemplo de corpo da resposta

{
    "data": [
        {
            "id": "2",
            "network_connector_agent": {
                "name": "agent-rj-01",
                "port": "30001",
                "active": true,
                "fingerprint": "EXAMPLE-FINGERPRINT-0001"
            }
        },
        {
            "id": "5",
            "network_connector_agent": {
                "name": "agent-sp-01",
                "port": "30002",
                "active": true,
                "fingerprint": "EXAMPLE-FINGERPRINT-0002"
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 50,
            "total_items": 2,
            "total_pages": 1
        },
        "links": {
            "self": "/api/v2/platform/network-connector/agents"
        }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	array de objetos	Agentes que correspondem aos filtros da requisição. Sem o filtro `active`, retorna apenas agentes ativos. Retorna um array vazio quando nenhum agente corresponde.
`data[].id`	string	Código de identificação único do agente, retornado como string. Use este valor no campo `network_connector_id` de um dispositivo.
`data[].network_connector_agent`	object	Atributos do agente.
`data[].network_connector_agent.name`	string	Nome do agente.
`data[].network_connector_agent.port`	string	Porta do agente, retornada como string. Pode ser `null`.
`data[].network_connector_agent.active`	boolean	`true` quando o agente está ativo, `false` quando está desativado.
`data[].network_connector_agent.fingerprint`	string	Valor usado para instalar o agente. Guarde-o com segurança e compartilhe-o apenas com quem vai instalar o agente. Pode ser `null`.
`meta`	object	Metadados de paginação e links de navegação.
`meta.pagination`	object	Detalhes de paginação do conjunto de resultados atual.
`meta.pagination.page`	integer	Número da página atual.
`meta.pagination.limit`	integer	Número máximo de resultados por página.
`meta.pagination.total_items`	integer	Total de agentes que correspondem aos filtros.
`meta.pagination.total_pages`	integer	Total de páginas.
`meta.links`	object	Links de navegação do conjunto de resultados.
`meta.links.self`	string	URL da página atual.
`meta.links.next`	string	URL da próxima página. Retornado apenas quando existe uma próxima página.
`meta.links.prev`	string	URL da página anterior. Retornado apenas a partir da página 2.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`400`	`api.request.bad_request`	A requisição enviou um parâmetro de query desconhecido.	Confira os nomes dos parâmetros em Parâmetros de query.
`404`	Sem código específico	O Network Connector não existe no ambiente.	Verifique se o Network Connector está configurado no Segura®.
`422`	`api.fields.invalid`	O parâmetro `fields` pediu um campo que não existe.	Confira os nomes dos campos em Projeção de campos.
`422`	Sem código específico	O parâmetro `fields` pediu o objeto `network_connector_agent` inteiro.	Peça cada campo pelo caminho completo, como `network_connector_agent.name`.
`422`	`api.enum.invalid_value`	O filtro `active` recebeu um valor diferente de `true` ou `false`.	Envie `active=true` ou `active=false`.
`422`	`api.pagination.limit.exceeded`	O valor de `limit` é maior que `200`.	Envie um `limit` entre `1` e `200`.
`422`	`api.sort.invalid_field`	O parâmetro `sort_by` usou um campo diferente de `id`, `name` ou `port`.	Ordene por `id`, `name` ou `port`.
`422`	`api.sort.invalid_direction`	O parâmetro `sort_by` usou uma direção diferente de `asc` ou `desc`.	Use `:asc` ou `:desc`.
`422`	Sem código específico	O valor de `page` ou de `limit` é menor que `1` ou não é um número.	Envie um número inteiro positivo.

Para erros de autenticação e de permissão e a política de 403 versus 404, acesse API v2 - Convenções e comportamentos compartilhados.