Creare un alias di indice in Azure AI Search

In Azure AI Search, un alias di indice è un nome secondario per un indice di ricerca. È possibile creare un alias mappato a un indice di ricerca e sostituire il nome dell'alias nelle posizioni in cui altrimenti si fa riferimento a un nome di indice. Questa funzionalità offre flessibilità se è necessario modificare l'indice in cui punta l'applicazione. Anziché aggiornare i riferimenti al nome dell'indice nel codice di produzione, è sufficiente aggiornare il mapping degli alias.

È possibile creare e gestire alias in un servizio di ricerca tramite richieste HTTP (POST, GET, PUT o DELETE) su una determinata risorsa alias. Gli alias sono risorse a livello di servizio gestite in modo indipendente dagli indici di ricerca. Dopo aver creato un indice di ricerca, è possibile creare un alias che lo mappa.

Prima di usare un alias, l'applicazione invia le richieste direttamente a 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
}

Dopo aver usato un alias, l'applicazione invia richieste a my-alias, che esegue il mapping a 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
}

Prerequisiti

• Un servizio Azure AI Search in qualsiasi area e piano tariffario.
• Indice di ricerca esistente a cui si vuole eseguire il mapping dell'alias.
• Autorizzazioni per creare un alias:
  • Per l'autenticazione basata su chiave, una chiave API amministratore per il servizio di ricerca.
  • Per l'autenticazione basata sui ruoli, il ruolo di Collaboratore del servizio di ricerca.

Limitazioni e considerazioni

• È possibile usare un alias solo con operazioni sui documenti o per ottenere e aggiornare una definizione di indice.
• Non è possibile usare un alias per eliminare un indice o testare la tokenizzazione del testo.
• Non è possibile fare riferimento a un alias come il targetIndexName su un indicizzatore o un sorgente di conoscenza.

Creare un alias di indice

La creazione di un alias stabilisce una mappatura tra un nome alias e un nome di indice. Se la richiesta ha esito positivo, è possibile usare l'alias per l'indicizzazione, l'esecuzione di query e altre operazioni.

È possibile creare un alias usando l'API REST, Azure SDK o il portale di Azure. Un alias è costituito dal name dell'alias e dal nome dell'indice di ricerca a cui l'alias è mappato. È possibile specificare un solo nome di indice nella indexes matrice.

Il numero massimo di alias che è possibile creare varia in base al piano tariffario. Per altre informazioni, vedere Limiti alias di indice.

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);

Inviare richieste a un alias di indice

È possibile usare un alias per tutte le operazioni sui documenti, tra cui query, indicizzazione, suggerimenti e completamento automatico.

La query seguente invia la richiesta a my-alias, che viene associata a un indice effettivo nel servizio di ricerca.

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
}

Ottenere una definizione di alias

Usare Alias - Elenco (API REST) per restituire un elenco di oggetti alias esistenti in base al nome.

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

Usare alias - Get (API REST) per restituire la definizione di un alias specifico.

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

Aggiornare un alias

L'aggiornamento più comune a un alias è la modifica del nome dell'indice quando l'indice sottostante viene sostituito con una versione più recente.

Usare alias : creare o aggiornare (API REST) per aggiornare un alias. Nell'esempio seguente viene illustrato come eseguire l'aggiornamento my-alias in modo che punti a hotel-samples-index2 anziché hotel-samples-indexa .

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

Un aggiornamento di un alias potrebbe richiedere fino a 10 secondi per propagarsi nel sistema, quindi attendere almeno 10 secondi prima di eliminare l'indice a cui è stato eseguito il mapping dell'alias in precedenza.

Se si tenta di eliminare un indice attualmente mappato a un alias, l'operazione non riesce con 400 (richiesta non valida) e un messaggio di errore che indica che gli alias mappati a tale indice devono essere eliminati o mappati a un indice diverso prima che l'indice possa essere eliminato.

Contenuto correlato

• Eliminare e ricostruire un indice in Azure AI Search