PUT | Atualizar agente do Network Connector

Descrição

Substitua os dados editáveis de um agente ativo do Network Connector. O nome é o único campo editável, então este endpoint renomeia o agente.

Renomear não altera o id, a porta nem o fingerprint do agente. Para alterar apenas alguns campos, use PATCH | Atualizar agente do Network Connector.

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.
Um agente ativo. Um agente desativado retorna 409. Para ativá-lo, acesse POST | Ativar agente do Network Connector.

Requisição

PUT /api/v2/platform/network-connector/agents/{agent_id}

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`agent_id`	integer	Sim	Código de identificação único do agente. Aceita apenas dígitos. Para encontrá-lo, acesse GET \| Listar todos os agentes do Network Connector.

Cabeçalhos

Cabeçalho	Obrigatório	Valor
`Content-Type`	Sim	`application/json`
`If-Match`	Sim	Valor de `ETag` do estado atual do agente.

Para obter o ETag atual, consulte o agente com GET | Listar um agente do Network Connector por [id] e copie o cabeçalho ETag da resposta.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Novo 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. O nome atual do agente é aceito.

Envie apenas name. Enviar id, port, active ou fingerprint retorna 422.

Exemplo de requisição

PUT {{url}}/api/v2/platform/network-connector/agents/12

If-Match: "9b2f6c0d4e8a1f3b7c5d2e9a0b4c6d8e"

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

Resposta

HTTP/1.1 200 OK

A resposta inclui o cabeçalho ETag com o novo estado do agente. Use-o na próxima atualização.

Exemplo de corpo da resposta

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

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	O agente atualizado.
`data.id`	string	Código de identificação único do agente, retornado como string.
`data.network_connector_agent`	object	Atributos do agente.
`data.network_connector_agent.name`	string	Novo nome do agente.
`data.network_connector_agent.port`	string	Porta do agente, retornada como string. Não muda.
`data.network_connector_agent.active`	boolean	Sempre `true`, porque apenas agentes ativos podem ser atualizados.
`data.network_connector_agent.fingerprint`	string	Valor usado para instalar o agente. Não muda. Guarde-o com segurança e compartilhe-o apenas com quem vai instalar o agente. Pode ser `null`.
`meta`	object	Links de navegação.
`meta.links.self`	string	Caminho do agente.

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 agente não existe.	Verifique o código de identificação enviado no caminho.
`404`	`api.route.not_found`	O valor de `agent_id` não é formado apenas por dígitos.	Envie o código de identificação do agente usando apenas dígitos.
`409`	`api.resource.inactive`	O agente está desativado.	Ative o agente com POST \| Ativar agente do Network Connector e reenvie a requisição.
`412`	`api.precondition.failed`	O valor de `If-Match` não corresponde ao estado atual do agente. O agente mudou depois que você o consultou.	Consulte o agente de novo e reenvie a requisição com o novo `ETag`.
`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.
`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`.
`428`	`api.precondition.required`	A requisição não tem o cabeçalho `If-Match`.	Envie o `ETag` atual do agente no cabeçalho `If-Match`.

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

412 o agente mudou depois que você o consultou:

{
    "code": "api.precondition.failed",
    "message": "Precondition failed.",
    "details": null
}