Todos os produtos
Search

Este produto

    Elasticsearch:API overview

    Central de documentação

    Elasticsearch:API overview

    Última atualização: Sep 21, 2026

    Esta página lista as APIs mais utilizadas do Elasticsearch Agent Engine Edition. As páginas das operações vinculadas a este documento detalham os parâmetros de requisição, os campos de resposta e os limites. As APIs e os exemplos baseiam-se no Agent Engine Edition 9.99.0. Esta página não é uma lista completa das APIs do Elasticsearch.

    Localize APIs por operação

    Para conhecer os recursos do Agent Engine Edition e seguir o guia completo de primeiros passos, consulte Visão geral dos recursos.

    Operação

    Referências

    Crie, atualize e exclua Collections; gerencie Slices, Backings e Aliases

    Gerenciar Collections e Slices

    Leia e grave documentos, processe dados em lotes e execute consultas

    Operações de gravação, leitura e consulta de documentos

    Configure campos vetoriais e execute consultas KNN

    Campos vetoriais e KNN

    Aqueça caches de Slice e consulte tarefas de aquecimento

    Aquecimento de caches de Slice

    Copie dados de Slice e gerencie tarefas de Copy Slice

    Cópia de Slice

    Crie e use Branch Slices graváveis

    Branch Slice (Beta)

    Configure clusters vetoriais e selecione automaticamente Slices candidatos

    Modo de recall de cluster vetorial

    Visualize o status de execução de Collections, Backings e Slices

    Observação CAT

    Há mais dois pontos de entrada fora da tabela. Para monitoramento de instâncias e configuração de permissões, consulte Operações da instância. Para limites de quantidade e restrições de recursos, consulte Limites do Agent Engine Edition.

    Selecione um destino de requisição

    Acesse um índice regular pelo nome do índice. Ao usar uma Collection, acesse os dados pelo nome da Collection ou por um Alias da Collection. Forneça _slice na URL da requisição sempre que a API exigir. Para endpoints, redes e autenticação da instância, consulte Criar e conectar-se a uma instância do Agent Engine Edition.

    As respostas do Agent Engine Edition também expõem nomes e identificadores gerenciados pelo sistema. Diferencie-os dos nomes de negócio fornecidos pela sua aplicação:

    Informações da resposta

    Significado e uso

    O campo _index em respostas de gravação, leitura ou consulta, e o campo backing_index na resposta de registro

    Pode ser um nome de índice subjacente .sc-*. Use-o apenas para solução de problemas. As aplicações devem continuar acessando os dados pelo nome da Collection ou pelo Alias.

    O valor _routing retornado

    Pode ser um identificador interno de Slice atribuído pelo sistema (slice_uid), que difere do nome de negócio do Slice. Não o analise nem o use como valor de _slice ou routing em requisições subsequentes. Continue usando o nome do Slice que sua aplicação forneceu originalmente.

    Os campos de resposta de gerenciamento de Slice slice e slice_id

    O nome de negócio do Slice, como tenant-a. Difere do slice_uid interno.

    O campo de resposta da Branch target_uid

    A identidade interna do Slice de destino, usada para verificar o resultado de requisições de criação repetidas. Para acessar o destino, continue usando o nome target_slice.

    Se você excluir um Slice e, em seguida, registrar um Slice com o mesmo nome, a identidade interna do Slice recém-registrado poderá diferir da do Slice excluído. As aplicações não devem derivar nomes de negócio a partir de identificadores internos nem tratar o novo Slice como uma continuação do ciclo de vida do Slice excluído.

    Avalie requisições e resultados

    • Tipo de conteúdo da requisição — Use Content-Type: application/json para requisições JSON. Use Content-Type: application/x-ndjson para requisições Bulk e Multi Search e mantenha a quebra de linha no final do corpo da requisição.

    • Falhas no nível do item — As APIs de Bulk, Multi Search, gerenciamento em lote, registro de Slice único e registro de Slices em lote podem relatar falhas no nível do item em uma resposta HTTP 200. Não confie apenas no código de status HTTP. Trate as respostas não 2xx e, em respostas de sucesso, verifique os campos de nível superior errors e items[].result.

    • HTTP 429 — O servidor está rejeitando a requisição atualmente. Use backoff exponencial com limite máximo e repita apenas operações que sejam idempotentes ou cujo resultado você já tenha confirmado.

    • Timeouts de conexão e HTTP 5xx — Um timeout de conexão ou uma resposta HTTP 5xx não significa que a gravação não ocorreu. Antes de tentar novamente, verifique o resultado usando um ID de documento estável ou outro mecanismo de idempotência. Você também pode recuperar o documento por meio de um dos endpoints de leitura na tabela de referência rápida da API de Collection e Slice.

    • Comprimento da URL — Ao passar um grande número de valores _slice na URL, a requisição também está sujeita ao limite de comprimento da linha de requisição HTTP (4096 bytes por padrão, controlado por http.max_initial_line_length). Se os nomes dos Slices forem longos, a exceção too_long_http_line_exception poderá ocorrer antes que o limite de quantidade de Slices seja atingido.

    • Timeouts de gerenciamento — As APIs de gerenciamento de Collection geralmente usam master_timeout (o tempo de espera para o nó mestre processar a requisição; padrão: 30s) e timeout (o tempo de espera por uma confirmação ou pelo resultado atual; padrão: 30s). Se uma requisição de gerenciamento retornar acknowledged=false ou expirar, a operação no lado do servidor não foi necessariamente revertida. Consulte o estado atual do recurso antes de tentar novamente.

    Referência rápida da API de Collection e Slice

    A tabela a seguir resume as APIs públicas para cenários de Collection e Slice, agrupadas por finalidade, e exclui as APIs internas de manutenção da plataforma. Os endpoints para Collections, Slices, Backings, Copy Slice, Branch Slice e aquecimento de Slice são extensões do Agent Engine Edition. Os endpoints de monitoramento de Collection, Backing e Slice também são extensões. Os endpoints restantes são APIs padrão do Elasticsearch. Na coluna API, os colchetes indicam um segmento de caminho opcional, enquanto as chaves indicam um espaço reservado que você deve substituir pelo seu valor. Use esta tabela para localizar o endpoint de uma tarefa conhecida e consulte a tabela de operações em Localize APIs por operação para acessar a página de detalhes dessa tarefa.

    Finalidade

    API

    Crie uma Collection

    PUT /_slice_collection/{collection}

    Obtenha uma Collection

    GET /_slice_collection[/{collection}]

    Atualize uma Collection

    POST /_slice_collection/{collection}/_update

    Exclua uma Collection

    DELETE /_slice_collection/{collection}

    Registre um Slice

    PUT /_slice_collection/{collection}/slices/{slice}

    Registre Slices em lote

    PUT /_slice_collection/{collection}/slices

    Consulte um único Slice

    GET /_slice_collection/{collection}/slices/{slice}

    Liste Slices com paginação

    GET /_slice_collection/{collection}/slices

    Exclua um Slice

    DELETE /_slice_collection/{collection}/slices/{slice}

    Pré-crie Backings

    PUT /_slice_collection/{collection}/backings?count={count}

    Leia e grave um único documento

    /{collection}/_doc/{id}, /{collection}/_create/{id}, /{collection}/_update/{id}, /{collection}/_source/{id}. Para gerar um ID automaticamente, use POST /{collection}/_doc. Para verificar se um documento existe, use HEAD /{collection}/_doc/{id}

    Grave e leia em lotes

    POST /_bulk, POST /{collection}/_bulk, POST /{collection}/_mget

    Pesquise e conte

    POST /{collection}/_search, POST /{collection}/_count, POST /_msearch, POST /{collection}/_msearch

    Execute modelos de pesquisa, gerencie pesquisas assíncronas e inspecione ou valide consultas

    POST /{collection}/_search/template, POST /{collection}/_async_search, GET /_async_search/{id}, DELETE /_async_search/{id}, POST /{collection}/_validate/query, GET /{collection}/_search_shards, POST /{collection}/_explain/{id}

    Atualize ou exclua por consulta

    POST /{collection}/_update_by_query, POST /{collection}/_delete_by_query

    Reindexe

    POST /_reindex

    Atualize mapeamentos

    PUT /{collection}/_mapping

    Atualize configurações dinâmicas

    PUT /{collection}/_settings

    Refresh explícito

    POST /{collection}/_refresh

    Aqueça caches de Slice

    POST /{collection}/_warm_slice?_slice={slice}

    Consulte uma tarefa de aquecimento

    GET /_tasks/{taskId}

    Gerencie Aliases de Collection

    POST /_aliases, GET /_alias[/{alias}]

    Inicie o Copy Slice

    POST /_slice_collection/{collection}/slices/{source}/_copy/{target}

    Consulte o status do Copy Slice

    GET /_slice_collection/{collection}/_copy/{copy_id}

    Cancele o Copy Slice

    POST /_slice_collection/{collection}/_copy/{copy_id}/_cancel

    Crie um Branch Slice (Beta)

    PUT /_slice_collection/{collection}/slices/{source}/_branch/{target}

    Visualize o status de execução da Collection

    GET /_cat/slice_collection[/{name}]

    Visualize o status de execução do Backing

    GET /_cat/slice_collection/{collection}/backings[/{backing}]

    Visualize o status de execução do Slice

    GET /_cat/slice_collection/{collection}/slices[/{slice}]

    Monitore o cluster e os nós

    GET /_cluster/health, GET /_nodes/stats, GET /_tasks