PATCH | Atualizar parcialmente servidor LDAP por [id]

Descrição

Altere atributos selecionados de um perfil de conexão de servidor LDAP/AD na plataforma Segura™. A requisição segue o formato JSON Merge Patch descrito na RFC 7396: ela carrega apenas os campos a alterar, e todo campo ausente do corpo mantém seu valor atual.

Para substituir a configuração completa em uma única requisição, acesse PUT | Atualizar servidor LDAP por [id].

Pré-requisitos

• Uma aplicação com a autorização Users concedida pelo administrador no A2A, com a permissão do recurso definida como Leitura e escrita. Para mais informações, acesse Como gerenciar autorizações no A2A.
• Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.
• A versão atual do servidor, lida no cabeçalho ETag retornado por GET | Listar um servidor LDAP por [id].
• O servidor deve estar ativo. Acesse POST | Ativar servidor LDAP primeiro quando não estiver.

Requisição

PATCH /api/v2/iam/ldap-servers/{id}

Parâmetros de caminho

Cabeçalhos

Corpo da requisição

Todos os campos são opcionais, e cada campo enviado segue as mesmas regras que tem em POST | Criar servidor LDAP: host, port, dn_base, use_ssl, member_is_dn, bind_requires_dn, account_form, order, domain_id, bind_credential_id, network_connector_id, account_filter_format, use_credential_domain, ignore_disabled_expired, username_attribute, dn_bind, group, group_dn, group_attribute, group_scope, group_filter e member_attribute.

Enviar null em um campo opcional limpa o valor. network_connector_id: null, por exemplo, remove o agente de network connector e retorna o servidor a uma conexão direta.

Campos que não podem ser modificados

Enviar qualquer um deles retorna 422 patch.field.not.allowed.

Exemplo de requisição

PATCH {{url}}/api/v2/iam/ldap-servers/7

Cabeçalhos

Content-Type: application/merge-patch+json
If-Match: "a3f8c2e1d9b04567"

Corpo

{
    "port": 636,
    "use_ssl": true
}

Resposta

HTTP/1.1 200 OK
ETag: "b7c1e4f2a8d93016"

O cabeçalho ETag contém a nova versão do servidor. Use o valor no cabeçalho If-Match da próxima escrita.

Exemplo de corpo da resposta

A resposta carrega o servidor completo, no mesmo formato de GET | Listar um servidor LDAP por [id], já com os campos alterados aplicados.

{
    "data": {
        "id": 7,
        "ldap_server": {
            "host": "ad.example.com",
            "port": 636,
            "dn_base": "CN=Users,DC=example,DC=com",
            "active": true,
            "use_ssl": true,
            "member_is_dn": false,
            "bind_requires_dn": false,
            "account_form": "principal",
            "order": 1,
            "domain": { "id": 5, "name": "EXAMPLE.COM" },
            "bind_credential": {
                "id": 102,
                "username": "[email protected]",
                "domain": { "id": 5, "name": "EXAMPLE.COM" }
            },
            "network_connector": null,
            "account_filter_format": null,
            "use_credential_domain": false,
            "ignore_disabled_expired": false,
            "username_attribute": null,
            "dn_bind": null,
            "account_domain_name": "EXAMPLE.COM",
            "account_domain_name_short": "EXAMPLE",
            "group": null,
            "group_dn": null,
            "group_attribute": null,
            "group_scope": null,
            "group_filter": null,
            "member_attribute": null,
            "created_at": "2026-05-08T22:42:34+00:00",
            "updated_at": "2026-05-12T14:11:07+00:00"
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-servers/7" },
        "actions": {
            "test-connection": "/api/v2/iam/ldap-servers/7/test-connection",
            "deactivate": "/api/v2/iam/ldap-servers/7/deactivate"
        }
    }
}

Campos do corpo da resposta

Os campos da resposta correspondem aos de GET | Listar um servidor LDAP por [id].

Erros

Exemplo de resposta de erro

422 o corpo carrega um campo que não pode ser modificado:

{
    "code": "patch.field.not.allowed",
    "message": "Field 'active' cannot be set via the API.",
    "details": [
        { "field": "active", "code": "patch.field.not.allowed" }
    ]
}

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