Criar um alias de índice no Azure AI Search

Importante

Os aliases de índice estão atualmente em versão prévia pública e disponíveis nos termos de uso complementares.

No Azure AI Search, um alias de índice é um nome secundário que pode ser usado para fazer referência a um índice para consulta, indexação e outras operações. Você pode criar um alias que é mapeado para um índice de pesquisa e substituir o nome do alias em locais em que, de outra forma, você referenciaria um nome de índice. Um alias agrega flexibilidade se você precisar alterar o índice ao qual aplicativo está apontando. Em vez de atualizar as referências no aplicativo, você pode apenas atualizar o mapeamento para o alias.

A principal meta dos aliases de índice é facilitar o gerenciamento dos índices de produção. Por exemplo, se você precisar fazer uma alteração na definição de índice, como editar um campo ou adicionar um novo analisador, terá que criar um índice de pesquisa, pois todos os índices de pesquisa são imutáveis. Isso significa que você precisa descartar e recompilar o índice ou criar um índice do zero e, depois, migrar seu aplicativo para esse índice.

Em vez de descartar e recompilar o índice, você pode usar aliases de índice. Um fluxo de trabalho típico seria para:

1. Criar o seu índice de pesquisa
2. Criar um alias que mapeia para o índice de pesquisa
3. Fazer com que seu aplicativo envie solicitações de consulta/indexação para o alias em vez do nome do índice
4. Quando você precisar fazer uma alteração no índice que exija uma recompilação, criar um índice de pesquisa
5. Quando o novo índice estiver pronto para ser usado, atualize o alias a ser mapeado para o novo índice e as solicitações serão automaticamente roteadas para o novo índice

Criar um índice de alias

Você pode criar um alias usando a API REST em versão prévia, os SDKs em versão prévia ou por meio do portal do Azure. Um alias consiste no name do alias e no nome do índice de pesquisa para o qual o alias é mapeado. Somente um nome de índice pode ser especificado na matriz indexes.

REST API

Você pode usar o Criar ou atualizar alias (versão prévia de REST) para criar um alias de índice.

POST /aliases?api-version=2024-05-01-preview
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index"]
}

Portal do Azure

Siga as etapas abaixo para criar um alias de índice no portal do Azure.

1. Navegue até o serviço de pesquisa no portal do Azure.
2. Localize e selecione Aliases.
3. Selecione + Adicionar Alias.
4. Dê um nome ao alias de índice e selecione o índice de pesquisa para o qual você quer mapear o alias. Em seguida, selecione Salvar.

SDK .NET

Usando um dos pacotes beta do SDK do Azure para .NET, você pode usar a sintaxe a seguir para criar um alias de índice.

// Create a SearchIndexClient
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

// Create an index alias
SearchAlias myAlias = new SearchAlias("my-alias", "hotel-quickstart-index");
adminClient.CreateAlias(myAlias);

Também há suporte para aliases de índice nos SDKs em versão prévia mais recentes para Java, Python e JavaScript.

Enviar solicitações para um alias de índice

Depois de criar seu alias, você estará pronto para começar a usá-lo. Os aliases podem ser usados para todas as operações de documento, incluindo consulta, indexação, sugestões e preenchimento automático.

Na consulta abaixo, em vez de enviar a solicitação para hotel-samples-index, você pode enviar a solicitação para my-alias e ela será roteada de acordo.

POST /indexes/my-alias/docs/search?api-version=2024-05-01-preview
{
    "search": "pool spa +airport",
    "searchMode": any,
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Se você espera fazer atualizações em um índice de produção, especifique um alias em vez do nome do índice em seu aplicativo do lado do cliente. Cenários que exigem uma recompilação de índice são descritos em Remover e recompilar um índice.

Observação

Você só pode usar um alias com operações de documento ou para obter e atualizar uma definição de índice. Os aliases não podem ser usados para excluir um índice, nem podem ser usados com a API de Análise de Texto e tampouco como o targetIndexName em um indexador.

Uma atualização para um alias pode levar até 10 segundos para ser propagada pelo sistema, portanto, você deve aguardar pelo menos 10 segundos antes de executar qualquer operação no índice mapeado ou recentemente mapeado para o alias.

Trocar índices

Agora, sempre que você precisar atualizar seu aplicativo para apontar para um novo índice, tudo o que você precisa fazer é atualizar o mapeamento em seu alias. PUT é necessário para atualizações, conforme descrito em Criar ou atualizar alias (versão prévia de REST).

PUT /aliases/my-alias?api-version=2024-05-01-preview
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index2"]
}

Depois de fazer a atualização para o alias, as solicitações começarão automaticamente a ser roteadas para o novo índice.

Observação

Uma atualização para um alias pode levar até dez segundos para se propagar pelo sistema, de modo que você deve aguardar pelo menos dez segundos antes de excluir o índice para o qual o alias foi mapeado anteriormente.

Confira também

• Remover e recompilar um índice no Azure AI Search