PATCH | Atualizar agente do Network Connector

Descrição

Atualize parcialmente um agente ativo do Network Connector. Envie apenas os campos que vão mudar; o nome é o único campo editável.

O corpo segue o JSON Merge Patch (RFC 7396). Atualizar não altera o id, a porta nem o fingerprint do agente. Para substituir todos os dados editáveis, use PUT | 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

PATCH /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/merge-patch+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	Não	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. Não aceita `null`.

Um corpo vazio ou {} não altera nada e retorna o agente atual. Enviar id, port, active ou fingerprint retorna 422.

Exemplo de requisição

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

Content-Type: application/merge-patch+json
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

A resposta tem os mesmos campos de PUT | Atualizar agente do Network Connector.

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	Nome do agente depois da atualização.
`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/merge-patch+json`.	Envie `Content-Type: application/merge-patch+json`.
`422`	`api.validation.invalid_type`	`name` não é uma string ou é `null`.	Envie `name` como string.
`422`	`api.validation.required_field`	`name` está vazio ou contém apenas espaços.	Envie um nome para o agente.
`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`. Para mudar o status do agente, use POST \| Ativar agente do Network Connector ou POST \| Desativar agente do Network Connector.
`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

415 a requisição usou application/json:

{
    "code": "api.request.unsupported_media_type",
    "message": "Content-Type must be 'application/merge-patch+json' for PATCH requests.",
    "details": null
}