Criar um alias de índice no Pesquisa de IA do Azure

No Pesquisa de IA do Azure, um alias de índice é um nome secundário para um índice de pesquisa. Podes criar um alias que corresponda a um índice de pesquisa e substituir o nome do alias em locais onde, de outra forma, referenciarias um nome de índice. Esta funcionalidade oferece flexibilidade caso necessite alterar o índice ao qual a sua aplicação está associada. Em vez de atualizar referências ao nome do índice no seu código de produção, pode simplesmente atualizar o mapeamento do alias.

Pode criar e gerir aliases num serviço de pesquisa através de pedidos HTTP (POST, GET, PUT ou DELETE) contra um determinado recurso de alias. Os pseudónimos são recursos de nível de serviço que são mantidos independentemente dos índices de pesquisa. Depois de criares um índice de pesquisa, podes criar um alias que se mapeia para ele.

Antes de usar um alias, a sua aplicação envia pedidos diretamente para hotel-samples-index.

POST /indexes/hotel-samples-index/docs/search?api-version=2026-04-01
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Depois de usar um pseudónimo, a sua aplicação envia pedidos para my-alias, que mapeia para hotel-samples-index.

POST /indexes/my-alias/docs/search?api-version=2026-04-01
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Pré-requisitos

• Um serviço Pesquisa de IA do Azure em qualquer região e faixa de preços.
• Um índice de pesquisa existente para o qual queres mapear o pseudónimo.
• Permissões para criar um alias:
  • Para autenticação baseada em chaves, uma chave API de administrador para o seu serviço de pesquisa.
  • Para a autenticação baseada em funções, a função Contribuidor do Serviço de Pesquisa.

Limitações e considerações

• Só pode usar um alias com operações de documento ou para obter e atualizar uma definição de índice.
• Não podes usar um alias para apagar um índice ou testar a tokenização de texto.
• Não podes referenciar um alias como targetIndexName num indexador ou fonte de conhecimento.

Criar um alias de índice

Criar um alias estabelece um mapeamento entre um nome de alias e um nome de índice. Se o pedido for bem-sucedido, pode usar o alias para indexação, consulta e outras operações.

Pode criar um alias usando a API REST, SDKs do Azure ou o portal Azure. Um alias consiste no name do alias e no nome do índice de pesquisa ao qual ele mapeia. Pode especificar apenas um nome de índice no indexes array.

O número máximo de pseudónimos que pode criar varia consoante o escalão de preço. Para mais informações, consulte Limites de aliases de índice.

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

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

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

Enviar pedidos para um alias de índice

Pode usar um alias para todas as operações do documento, incluindo consultas, indexação, sugestões e autocompletamento.

A consulta a seguir envia o pedido para my-alias, que é associado a um índice real no seu serviço de pesquisa.

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

Obtenha uma definição de alias

Use Aliases - List (API REST) para devolver uma lista de objetos alias existentes por nome.

GET /aliases?api-version=2026-04-01&$select=name

Use Aliases - Obtenha (REST API) para devolver a definição de um alias específico.

GET /aliases/my-alias?api-version=2026-04-01

Atualizar um pseudónimo

A atualização mais comum de um alias é alterar o nome do índice quando o índice subjacente é substituído por uma versão mais recente.

Use Aliases - Criar ou Atualizar (API REST) para atualizar um alias. O exemplo seguinte mostra como atualizar my-alias para apontar para hotel-samples-index2 em vez de hotel-samples-index.

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

Uma atualização de um alias pode demorar até 10 segundos a propagar-se pelo sistema, por isso espere pelo menos 10 segundos antes de apagar o índice para o qual o alias estava previamente mapeado.

Se tentares eliminar um índice que está atualmente mapeado para um alias, a operação falha com 400 (Pedido Mau) e uma mensagem de erro a indicar que o(s) alias(es) mapeado(s) para esse índice devem ser eliminados ou mapeados para outro índice antes de o índice poder ser eliminado.

Conteúdo relacionado

• Eliminar e reconstruir um índice no Azure Cognitive Search