Atualizar índice (API REST do Azure AI Search)

  • Artigo

A modificação de um índice existente normalmente requer uma remoção e recompilação de índice, exceto pelas seguintes alterações de esquema:

  • Adicionar novos campos a uma coleção de campos

  • Adicionar campos recém-criados a um sugestor

  • Adicionar ou alterar perfis de pontuação

  • Adicionar ou alterar chaves de criptografia

  • Adicionar novos analisadores personalizados

  • Alterar as opções do CORS

  • Altere os campos existentes com qualquer uma dessas três modificações:

    • Alteração retrievable (os valores são verdadeiros ou falsos)
    • Alteração searchAnalyzer (usada no momento da consulta)
    • Adicionar ou alterar synonymMaps (usado no momento da consulta)

Para adicionar essas atualizações, coloque o nome do índice no URI da solicitação. No corpo da solicitação, inclua uma definição de índice totalmente especificada com suas modificações.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

Os campos existentes e a maioria dos atributos de campo não podem ser excluídos ou alterados, nem os campos podem ser adicionados aos sugestores. Somente campos recém-criados podem ser adicionados a um suggester.

Quando um novo campo é adicionado, todos os documentos existentes obtêm automaticamente um valor nulo para esse campo. Nenhum outro espaço de armazenamento é consumido até que uma das duas coisas ocorra: um valor é fornecido para o novo campo (usando mesclagem) ou novos documentos são adicionados.

Analisadores, tokenizadores, filtros de token e filtros char existentes não podem ser alterados. A adição de novos a um índice já existente só é possível quando o allowIndexDowntime sinalizador é ativado na solicitação de atualização de índice. A mesma regra se aplica ao adicionar um campo de vetor inicial a um índice pré-existente que foi estabelecido usando uma API que não dá suporte à pesquisa de vetor, especificamente antes da Versão prévia da API REST 2023-07-01.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

Essa operação coloca o índice offline por alguns segundos. As solicitações de indexação e consulta falham enquanto o índice está offline. As operações de desempenho e gravação podem ser temporariamente prejudicadas por vários minutos depois que o índice estiver online novamente.

Parâmetros de URI

Parâmetro Descrição
nome do serviço Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa.
nome do índice Obrigatórios. O URI da solicitação especifica o nome do índice a ser atualizado.
api-version Obrigatórios. Confira Versões de API para obter uma lista de versões com suporte.
allowIndexDowntime Opcional. Falso por padrão. Defina como true para determinadas atualizações, como adicionar ou modificar um analisador, um criador de tokens, um filtro de token, um filtro char ou uma propriedade de similaridade. O índice é colocado offline durante a atualização, geralmente não mais do que vários segundos.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Campos Descrição
Tipo de conteúdo Obrigatórios. Defina-o como application/json
chave de API Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. As solicitações de atualização devem incluir um api-key cabeçalho definido como sua chave de administrador (em vez de uma chave de consulta). Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

Corpo da solicitação

A sintaxe do corpo da solicitação é a mesma de Criar Índice.

Quando você atualiza um índice existente, o corpo deve incluir a definição de esquema completa, incluindo quaisquer definições originais que você deseja preservar. Em geral, o melhor padrão para atualizações é recuperar a definição de índice com um GET, modificá-la e atualizá-la com PUT.

Resposta

Para uma solicitação bem-sucedida, você deverá ver “204 Sem Conteúdo”.

Por padrão, o corpo da resposta está vazio. No entanto, se o cabeçalho da Prefer solicitação estiver definido como return=representation, o corpo da resposta conterá o JSON do índice atualizado. Nesse caso, o código de status de sucesso é "200 OK".

Confira também