Gestire il servizio Azure AI Search con l'interfaccia della riga di comando di Azure

  • Articolo

È possibile eseguire comandi e script dell'interfaccia della riga di comando di Azure in Windows, macOS, Linux o in Azure Cloud Shell per creare e configurare Azure AI Search.

Usare il modulo az search per eseguire le attività seguenti:

In alcuni casi, vengono poste domande sulle attività non presenti nell'elenco precedente.

Non è possibile modificare il nome di un server, un'area o un livello a livello di codice o nel portale. Le risorse dedicate vengono allocate quando viene creato un servizio. Di conseguenza, la modifica dell'hardware sottostante (posizione o tipo di nodo) richiede un nuovo servizio.

Non è possibile usare strumenti o API per trasferire contenuti, ad esempio un indice, da un servizio all'altro. All'interno di un servizio, la creazione di contenuto a livello di codice avviene tramite API REST del servizio di ricerca o un SDK, ad esempio Azure SDK per .NET. Anche se non sono disponibili comandi dedicati per la migrazione del contenuto, è possibile scrivere uno script che chiami l'API REST o una libreria client per creare e caricare indici in un nuovo servizio.

Le funzionalità di amministrazione dell'anteprima non sono in genere disponibili nel modulo az search. Se si vuole usare una funzionalità di anteprima, usare l'API REST di gestione e una versione di anteprima dell'API.

Prerequisiti

Le versioni dell'interfaccia della riga di comando di Azure sono elencate in GitHub.

Il modulo az search estende l'interfaccia della riga di comando di Azure con piena parità con le versioni stabili delle API REST di gestione della ricerca.

Elencare i servizi in una sottoscrizione

I comandi seguenti provengono da az resource e restituiscono informazioni sulle risorse e i servizi esistenti di cui è già stato effettuato il provisioning nella sottoscrizione. Se non si conosce il numero di servizi di ricerca già creati, questi comandi restituiscono tali informazioni, evitando di dover consultare il portale.

Il primo comando restituisce tutti i servizi di ricerca.

az resource list --resource-type Microsoft.Search/searchServices --output table

Dall'elenco dei servizi, restituire le informazioni su una risorsa specifica.

az resource list --name <search-service-name>

Elencare tutti i comandi az search

È possibile visualizzare informazioni sui sottogruppi e i comandi disponibili in az search dall'interfaccia della riga di comando. In alternativa, è possibile esaminare la documentazione.

Per visualizzare i sottogruppi disponibili in az search, eseguire il comando seguente.

az search --help

La risposta dovrebbe essere simile all'output seguente.

Group
    az search : Manage Azure Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

All'interno di ogni sottogruppo sono disponibili più comandi. È possibile visualizzare i comandi disponibili per il sottogruppo service eseguendo la riga seguente.

az search service --help

È anche possibile visualizzare gli argomenti disponibili per un comando specifico.

az search service create --help

Ottenere informazioni sul servizio di ricerca

Se si conosce il gruppo di risorse contenente il servizio di ricerca, eseguire az search service show per restituire la definizione del servizio, tra cui nome, area, livello e numero di repliche e partizioni. Per questo comando, fornire il gruppo di risorse che contiene il servizio di ricerca.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

Creare o eliminare un servizio

Per creare un nuovo servizio di ricerca, usare il comando az search service create.

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

I risultati dovrebbero essere simili all'output seguente:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete rimuove il servizio e i relativi dati.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

Creare un servizio con regole IP

A seconda dei requisiti di sicurezza, potrebbe essere necessario creare un servizio di ricerca con un firewall IP configurato. A tale scopo, passare gli indirizzi IP pubblici (v4) o gli intervalli CIDR all'argomento ip-rules, come illustrato di seguito. Le regole devono essere separate da una virgola (,) o da un punto e virgola (;).

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

Creare un servizio con un'identità gestita assegnata dal sistema

In alcuni casi, ad esempio quando si usa l'identità gestita per connettersi a un'origine dati, è necessario attivare l'identità gestita assegnata dal sistema. A tale scopo, aggiungere --identity-type SystemAssigned al comando.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

Creare un servizio con un endpoint privato

Gli endpoint privati per Azure AI Search consentono a un client in una rete virtuale di accedere in modo sicuro ai dati in un indice di ricerca tramite un collegamento privato. L'endpoint privato usa un indirizzo IP dallo spazio indirizzi della rete virtuale per il servizio di ricerca. Il traffico di rete tra il client e il servizio di ricerca attraversa la rete virtuale e un collegamento privato sulla rete backbone Microsoft, eliminando l'esposizione alla rete Internet pubblica. Per altre informazioni, vedere la documentazione sulla creazione di un endpoint privato per Azure AI Search.

Nell'esempio seguente viene illustrato come creare un servizio di ricerca con un endpoint privato.

Per prima cosa, distribuire un servizio di ricerca con PublicNetworkAccess impostato su Disabled.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

Successivamente, creare una rete virtuale e l'endpoint privato.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>

Infine, creare una zona DNS privato.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

Per altre informazioni sulla creazione di endpoint privati nell'interfaccia della riga di comando di Azure, vedere Avvio rapido dei collegamento privati.

Gestire le connessioni endpoint privato

Oltre a creare una connessione endpoint privato, è anche possibile show, updatee delete la connessione.

Per recuperare una connessione a un endpoint privato e visualizzarne lo stato, usare az search private-endpoint-connection show.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Per aggiornare la connessione, usare az search private-endpoint-connection update. Nell'esempio seguente viene impostata una connessione a un endpoint privato come rifiutata:

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

Per eliminare la connessione all'endpoint privato, usare az search private-endpoint-connection delete.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Riscrivere una chiave amministratore

Per eseguire il rollover delle chiavi API di amministrazione, usare az search admin-key renew. Per ogni servizio vengono create due chiavi di amministrazione per l'accesso autenticato. Le chiavi sono necessarie per ogni richiesta. Entrambe le chiavi di amministrazione sono equivalenti a livello funzionale, concedendo l'accesso in scrittura completo a un servizio di ricerca con la possibilità di recuperare qualsiasi informazione o creare ed eliminare qualsiasi oggetto. Sono disponibili due chiavi in modo che sia possibile usarne una durante la sostituzione dell'altra.

È possibile rigenerarne solo una alla volta, specificandola come chiave primary o secondary. Per un servizio senza interruzioni, ricordarsi di aggiornare tutto il codice client per usare una chiave secondaria durante il rollover della chiave primaria. Evitare di modificare le chiavi mentre le operazioni sono in versione di anteprima.

Come prevedibile, se si rigenerano le chiavi senza aggiornare il codice client, le richieste che usano la chiave precedente avranno esito negativo. La rigenerazione di tutte le nuove chiavi non blocca definitivamente il servizio ed è comunque possibile accedere al servizio tramite il portale. Dopo aver rigenerato le chiavi primarie e secondarie, è possibile aggiornare il codice client per usare le nuove chiavi e le operazioni riprenderanno di conseguenza.

I valori per le chiavi API vengono generati dal servizio. Non è possibile fornire una chiave personalizzata da usare per Azure AI Search. Analogamente, non esiste un nome definito dall'utente per le chiavi API di amministrazione. I riferimenti alla chiave sono stringhe fisse, primary o secondary.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

I risultati dovrebbero essere simili all'output seguente. Entrambe le chiavi vengono restituite anche se ne viene modificata solo una alla volta.

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

Creare o eliminare chiavi di query

Per creare chiavi APIdi query per l'accesso in sola lettura dalle app client a un indice di Azure AI Search, usare az search query-key create. Le chiavi di query vengono usate per eseguire l'autenticazione a un indice specifico per il recupero dei risultati della ricerca. Le chiavi di query non concedono l'accesso in sola lettura ad altri elementi del servizio, ad esempio un indice, un'origine dati o un indicizzatore.

Non è possibile fornire una chiave da usare per Azure AI Search. Le chiavi API vengono generate dal servizio.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

Ridimensionare repliche e partizioni

Per aumentare o ridurre le repliche e le partizioni usare az search service update. L'aumento delle repliche o delle partizioni comporta un aumento della fattura, con addebiti fissi e variabili. Se si ha una necessità temporanea di maggiore potenza di elaborazione, è possibile aumentare le repliche e le partizioni per gestire il carico di lavoro. L'area di monitoraggio nella pagina Panoramica del portale contiene riquadri sulla latenza delle query, sulle query al secondo e sulla limitazione delle richieste, che indicano se la capacità corrente è adeguata.

L'aggiunta o la rimozione delle risorse potrebbe richiedere del tempo. Le modifiche alla capacità avvengono in background, consentendo la prosecuzione dei carichi di lavoro esistenti. La capacità aggiuntiva viene usata per le richieste in ingresso non appena è pronta, senza necessità di configurazioni aggiuntive.

La rimozione della capacità può essere dannosa. È consigliabile arrestare tutti i processi di indicizzazione e l'indicizzatore prima di ridurre la capacità per evitare la rimozione delle richieste. Se ciò non è fattibile, è possibile ridurre la capacità in modo incrementale, una replica e una partizione alla volta, fino a raggiungere i nuovi livelli di destinazione.

Dopo avere inviato il comando, non è più possibile interromperlo a metà. È necessario attendere il completamento del comando prima di rivedere i conteggi.

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

Oltre ad aggiornare i conteggi delle repliche e delle partizioni, è anche possibile aggiornare ip-rules, public-accesse identity-type.

Gli endpoint privati delle risorse protette create tramite le API di Azure AI Search vengono definiti risorse di collegamento privato condiviso. Questo perché si sta "condividendo" l'accesso a una risorsa, ad esempio un account di archiviazione che è stato integrato con il servizio collegamento privato di Azure.

Se si usa un indicizzatore per indicizzare i dati in Azure AI Search e l'origine dati si trova in una rete privata, è possibile creare una connessione endpoint privato in uscita per raggiungere i dati.

Un elenco completo delle risorse di Azure per cui è possibile creare endpoint privati in uscita da Azure AI Search è disponibile qui insieme ai relativi valori di ID gruppo.

Per creare la risorsa collegamento privato condiviso, usare az search shared-private-link-resource create. Tenere presente che alcune configurazioni potrebbero essere necessarie per l'origine dati prima di eseguire questo comando.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve"

Per recuperare le risorse collegamento privato condiviso e visualizzare il relativo stato, usare az search shared-private-link-resource list.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

È necessario approvare la connessione con il seguente comando prima di poterla usare. L'ID della connessione all'endpoint privato deve essere recuperato dalla risorsa figlio. In questo caso, si ottiene l'ID connessione da az storage.

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

Per eliminare la risorsa di collegamento privato condiviso, usare az search shared-private-link-resource delete.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Per altre informazioni sulla configurazione delle risorse collegamento privato condiviso, vedere Creare connessioni dell'indicizzatore tramite un endpoint privato.

Passaggi successivi

Compilare un indice, eseguire una query su un indice usando il portale, le API REST o .NET SDK.