GET | Listar um job do IAM por [id]

Descrição

Leia o estado e o resultado de um job em segundo plano iniciado por um endpoint do IAM na plataforma Segura™. Endpoints que não conseguem responder de imediato retornam 202 Accepted com um descritor de job, e este endpoint reporta o que aconteceu com esse job.

Nesta versão, o único tipo de job é o teste de conexão de servidor LDAP iniciado por POST | Testar conexão do servidor LDAP por [id].

Pré-requisitos

Uma aplicação com a autorização Users concedida pelo administrador no A2A. 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.
O job deve ter sido iniciado pela mesma aplicação ou pelo mesmo usuário que faz esta requisição.

Requisição

GET /api/v2/iam/jobs/{id}

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Código de identificação único do job, no formato UUID. Nota: este valor é retornado no cabeçalho `Location` e em `data.job.id` pelo endpoint que iniciou o job.

Exemplo de requisição

GET {{url}}/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8

Resposta

HTTP/1.1 200 OK

Exemplo de corpo da resposta

Um job que terminou com sucesso:

{
    "data": {
        "id": "019e0a01-b7b8-7062-82dd-43a8aa0ed6f8",
        "type": "ldap.test_connection",
        "state": "succeeded",
        "retry_count": 0,
        "created_at": "2026-05-08 23:52:25",
        "started_at": "2026-05-08 23:52:25",
        "finished_at": "2026-05-08 23:52:26",
        "result": {
            "bind_ok": true,
            "base_search_ok": true,
            "elapsed_ms": 312,
            "translated_host": "ad.example.com",
            "translated_port": 389
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8" }
    }
}

Um job que falhou:

{
    "data": {
        "id": "019e0a01-b7b8-7062-82dd-43a8aa0ed6f8",
        "type": "ldap.test_connection",
        "state": "failed",
        "retry_count": 0,
        "created_at": "2026-05-08 23:52:25",
        "started_at": "2026-05-08 23:52:25",
        "finished_at": "2026-05-08 23:52:30",
        "error": {
            "code": "api.ldap.test_connection.dc_unavailable",
            "message": "LDAP bind failed: Can't contact LDAP server"
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8" }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	O job.
`data.id`	string	Código de identificação único do job, no formato UUID.
`data.type`	string	Tipo do job. Retorna `ldap.test_connection` para um teste de conexão.
`data.state`	string	Estado do job. Veja Estados do job.
`data.retry_count`	integer	Número de vezes que o job foi reexecutado.
`data.created_at`	datetime	Data e hora de criação do job.
`data.started_at`	datetime	Data e hora em que um worker começou a processar o job. Retorna `null` enquanto o job está na fila.
`data.finished_at`	datetime	Data e hora de finalização do job. Retorna `null` até então.
`data.result`	object	Resultado do job. Retornado apenas quando `state` é `succeeded`, e seus campos dependem do tipo de job.
`data.error`	object	Motivo da falha do job. Retornado apenas quando `state` é `failed`.
`data.error.code`	string	Código que identifica a falha.
`data.error.message`	string	Descrição da falha.
`meta`	object	Metadados do recurso.
`meta.links`	object	Links de navegação para o job.
`meta.links.self`	string	Caminho do job.

Estados do job

Estado	Descrição
`queued`	O job aguarda um worker.
`running`	Um worker está processando o job.
`succeeded`	O job terminou e `result` contém o resultado.
`failed`	O job terminou com um erro e `error` contém o motivo. Um job com falha pode ser reexecutado com POST \| Reexecutar um job do IAM por [id].

Atenção

Os jobs são mantidos por 24 horas após a criação. Uma requisição para um job mais antigo que isso retorna 404 api.resource.not_found, então leia o resultado antes que a janela se encerre.

Um job é visível para a aplicação que o iniciou e para o usuário que o iniciou. Uma requisição de outro usuário por meio de outra aplicação retorna 404 api.resource.not_found, e não 403 Forbidden.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`401`	`api.auth.unauthorized`	O token de acesso está ausente ou expirou.	Solicite um novo token de acesso.
`404`	`api.resource.not_found`	O job não existe, tem mais de 24 horas ou foi iniciado por outro usuário por meio de outra aplicação.	Verifique o código de identificação e envie a requisição com a aplicação ou o usuário que iniciou o job.
`429`	`api.rate_limit.exceeded`	O limite de requisições foi excedido.	Reduza a frequência de requisições e tente novamente.

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