POST | Criar agente do Network Connector

Descrição

Crie um agente do Network Connector enviando apenas o nome. O Segura® define a porta e retorna o fingerprint usado para instalar o agente.

O novo agente é criado ativo. Use o id dele no campo network_connector_id para vincular um dispositivo ao agente.

Cada requisição cria um novo agente. O endpoint não aceita o cabeçalho Idempotency-Key, então reenviar a mesma requisição cria outro agente.

Pré-requisitos

Uma aplicação com a Permissão do recurso PAM definida como 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

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

Cabeçalhos

Cabeçalho	Obrigatório	Valor
`Content-Type`	Sim	`application/json`

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do agente. Os espaços no início e no fim são removidos. Máximo: 255 caracteres. Precisa ser único entre os agentes do Network Connector, incluindo os desativados.

Envie apenas name. O Segura® define id, port, active e fingerprint: enviar qualquer um deles retorna 422.

Exemplo de requisição

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

{
    "name": "agent-rj-02"
}

Resposta

HTTP/1.1 201 Created

A resposta inclui estes cabeçalhos:

Location: caminho do novo agente.
ETag: versão do estado atual do agente. Envie-o no cabeçalho If-Match de PUT | Atualizar agente do Network Connector ou de PATCH | Atualizar agente do Network Connector.

Exemplo de corpo da resposta

{
    "data": {
        "id": "12",
        "network_connector_agent": {
            "name": "agent-rj-02",
            "port": "30003",
            "active": true,
            "fingerprint": "EXAMPLE-FINGERPRINT-0003"
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/network-connector/agents/12"
        },
        "actions": {
            "deactivate": "/api/v2/platform/network-connector/agents/12/deactivate"
        }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	O agente criado.
`data.id`	string	Código de identificação único do agente, retornado como string. Use-o no caminho dos outros endpoints de agente. Para vincular um dispositivo, envie-o como número inteiro no campo `network_connector_id` do dispositivo.
`data.network_connector_agent`	object	Atributos do agente.
`data.network_connector_agent.name`	string	Nome do agente, sem os espaços no início e no fim.
`data.network_connector_agent.port`	string	Porta definida pelo Segura® para o agente, retornada como string.
`data.network_connector_agent.active`	boolean	Sempre `true` para um novo agente.
`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.
`meta`	object	Links de navegação e ações disponíveis.
`meta.links.self`	string	Caminho do agente criado.
`meta.actions.deactivate`	string	Caminho para desativar o agente. Para mais informações, acesse POST \| Desativar agente do Network Connector.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`400`	`api.request.bad_request`	O corpo não é um JSON válido.	Confira a sintaxe do payload.
`403`	`api.auth.insufficient_permission`	A Permissão do recurso PAM da aplicação é Apenas leitura.	Peça ao administrador para definir a Permissão do recurso PAM como Leitura e escrita no A2A.
`404`	`api.resource.not_found`	O Network Connector não existe no ambiente.	Verifique se o Network Connector está configurado no Segura®.
`415`	`api.request.unsupported_media_type`	O cabeçalho `Content-Type` não é `application/json`.	Envie `Content-Type: application/json`.
`422`	`api.validation.required_field`	`name` está ausente, vazio ou contém apenas espaços.	Envie um nome para o agente.
`422`	`api.validation.invalid_type`	`name` não é uma string.	Envie `name` como string.
`422`	`api.validation.invalid_value`	`name` tem mais de 255 caracteres.	Envie um nome com até 255 caracteres.
`422`	`api.validation.duplicate`	Outro agente, ativo ou desativado, já usa o nome.	Escolha outro nome. Para ver os nomes em uso, acesse GET \| Listar todos os agentes do Network Connector com `active=true` e com `active=false`.
`422`	`patch.field.not_allowed`	O corpo contém `id`, `port`, `active` ou `fingerprint`.	Envie apenas `name`.
`422`	`api.validation.unknown_field`	O corpo contém um campo que não faz parte do contrato.	Envie apenas `name`.
`503`	`network_connector.port_allocation_failed`	O Segura® não conseguiu definir uma porta para o agente. O agente não é criado.	Aguarde o número de segundos indicado no cabeçalho `Retry-After` e reenvie a requisição.
`503`	`network_connector.broker_unavailable`	O serviço do Network Connector está temporariamente indisponível. O agente não é criado.	Aguarde o número de segundos indicado no cabeçalho `Retry-After` e reenvie a requisição. Se o erro persistir, entre em contato com o time de suporte do Segura®.
`503`	`network_connector.credential_unavailable`	O Segura® não conseguiu concluir a criação. O agente não é criado.	Aguarde o número de segundos indicado no cabeçalho `Retry-After` e reenvie a requisição. Se o erro persistir, entre em contato com o time de suporte do Segura®.

Para erros de autenticação, limites de requisição e o formato da resposta de erro, acesse API v2 - Convenções e comportamentos compartilhados.

Exemplo de resposta de erro

422 outro agente já usa o nome:

{
    "code": "api.validation.duplicate",
    "message": "A network connector agent with this name already exists.",
    "details": [
        {
            "field": "name",
            "code": "api.validation.duplicate"
        }
    ]
}