Condividi tramite

Gestire il servizio Azure AI Search con PowerShell

  • Articolo

Per creare e configurare Azure AI Search, è possibile eseguire i cmdlet e gli script di PowerShell in Windows, Linux o Azure Cloud Shell.

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 programmatica di contenuti 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.

Il modulo AZ.Search estende Azure PowerShell mantenendo la piena parità rispetto alle versioni stabili delle API REST di gestione della ricerca.

Controllare le versioni e caricare i moduli

Gli esempi riportati in questo articolo sono interattivi e richiedono autorizzazioni elevate. In questo caso vengono richiesti PowerShell locale e il modulo Az di Azure PowerShell.

Controllo della versione di PowerShell

Installare la versione più recente di PowerShell, se non è già presente.

$PSVersionTable.PSVersion

Caricare Azure PowerShell

Se non si è sicuri che il modulo Az sia installato, eseguire il comando seguente come passaggio di verifica.

Get-InstalledModule -Name Az

Alcuni sistemi non caricano automaticamente i moduli. Se si è verificato un errore con il comando precedente, provare a caricare il modulo e, se l'operazione non riesce, tornare alle istruzioni per l'installazione di Azure PowerShell per verificare se si è saltato un passaggio.

Import-Module -Name Az

Connettersi ad Azure con un token di accesso al browser

È possibile usare le credenziali di accesso al portale per connettersi a una sottoscrizione di PowerShell. In alternativa, è possibile autenticarsi in modo non interattivo con un'entità servizio.

Connect-AzAccount

Se si dispone di più sottoscrizioni di Azure, impostare la propria sottoscrizione di Azure. Per visualizzare un elenco di sottoscrizioni correnti, eseguire questo comando.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Per specificare la sottoscrizione, eseguire il comando seguente. Nell'esempio seguente, il nome della sottoscrizione è ContosoSubscription.

Select-AzSubscription -SubscriptionName ContosoSubscription

Elencare i servizi di una sottoscrizione

I comandi seguenti provengono da AZ.Resources 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.

Get-AzResource -ResourceType Microsoft.Search/searchServices | ft

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

Get-AzResource -ResourceName <service-name>

I risultati dovrebbero essere simili all'output seguente.

Name              : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType      : Microsoft.Search/searchServices
Location          : westus
ResourceId        : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

Importare Az.Search

I comandi provenienti da Az.Search non sono disponibili fino a quando non si carica il modulo.

Install-Module -Name Az.Search -Scope CurrentUser

Elencare tutti i comandi Az.Search

Come passaggio di verifica, restituire un elenco dei comandi forniti nel modulo.

Get-Command -Module Az.Search

I risultati dovrebbero essere simili all'output seguente.

CommandType     Name                                               Version     Source                                                                
-----------     ----                                               -------     ------                                                                
Cmdlet          Get-AzSearchAdminKeyPair                           0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchPrivateEndpointConnection              0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchPrivateLinkResource                    0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchQueryKey                               0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchService                                0.10.0      Az.Search                                                             
Cmdlet          Get-AzSearchSharedPrivateLinkResource              0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchAdminKey                               0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchQueryKey                               0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchService                                0.10.0      Az.Search                                                             
Cmdlet          New-AzSearchSharedPrivateLinkResource              0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchPrivateEndpointConnection           0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchQueryKey                            0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchService                             0.10.0      Az.Search                                                             
Cmdlet          Remove-AzSearchSharedPrivateLinkResource           0.10.0      Az.Search                                                             
Cmdlet          Set-AzSearchPrivateEndpointConnection              0.10.0      Az.Search                                                             
Cmdlet          Set-AzSearchService                                0.10.0      Az.Search                                                             
Cmdlet          Set-AzSearchSharedPrivateLinkResource              0.10.0      Az.Search

Se si dispone di una versione del pacchetto meno recente, aggiornare il modulo per ottenere le funzionalità più recenti.

Update-Module -Name Az.Search

Ottenere informazioni sul servizio di ricerca

Dopo che Az.Search è stato importato e si conosce il gruppo di risorse contenente il servizio di ricerca, eseguire Get-AzSearchService 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.

Get-AzSearchService -ResourceGroupName <resource-group-name>

I risultati dovrebbero essere simili all'output seguente.

Name              : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType      : Microsoft.Search/searchServices
Location          : West US
Sku               : Standard
ReplicaCount      : 1
PartitionCount    : 1
HostingMode       : Default
ResourceId        : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

Creare o eliminare un servizio

New-AzSearchService viene usato per creare un nuovo servizio di ricerca.

New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default

I risultati dovrebbero essere simili all'output seguente.

ResourceGroupName : demo-westus
Name              : my-demo-searchapp
Id                : /subscriptions/<alphanumeric-subscription-ID>/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location          : West US
Sku               : Standard
ReplicaCount      : 3
PartitionCount    : 3
HostingMode       : Default
Tags

Remove-AzSearchService viene usato per eliminare un servizio e i relativi dati.

Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>

Viene chiesto di confermare l'azione.

Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Creare un servizio con regole IP

A seconda dei requisiti di sicurezza, si potrebbe voler creare un servizio di ricerca con un firewall IP configurato. Per farlo, è prima necessario definire le regole IP e quindi passarle al parametro IPRuleList, come mostrato di seguito.

$ipRules = @([pscustomobject]@{Value="55.5.63.73"},
		[pscustomobject]@{Value="52.228.215.197"},
		[pscustomobject]@{Value="101.37.221.205"})

 New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard `
                      -Location "West US" `
                      -PartitionCount 3 -ReplicaCount 3 `
                      -HostingMode Default `
                      -IPRuleList $ipRules

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 -IdentityType SystemAssigned al comando.

New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard `
                      -Location "West US" `
                      -PartitionCount 3 -ReplicaCount 3 `
                      -HostingMode Default `
                      -IdentityType SystemAssigned

Creare un servizio S3HD

Per creare un servizio S3HD viene usata una combinazione di -Sku e -HostingMode. Impostare -Sku su Standard3 e -HostingMode su HighDensity.

New-AzSearchService -ResourceGroupName <resource-group-name> `
                      -Name <search-service-name> `
                      -Sku Standard3 `
                      -Location "West US" `
                      -PartitionCount 1 -ReplicaCount 3 `
                      -HostingMode HighDensity

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 dello 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 Creare 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.

$searchService = New-AzSearchService `
    -ResourceGroupName <search-service-resource-group-name> `
    -Name <search-service-name> `
    -Sku Standard `
    -Location "West US" `
    -PartitionCount 1 -ReplicaCount 1 `
    -HostingMode Default `
    -PublicNetworkAccess Disabled

Quindi, creare una rete virtuale, una connessione di rete privata e l'endpoint privato.

# Create the subnet
$subnetConfig = New-AzVirtualNetworkSubnetConfig `
    -Name <subnet-name> `
    -AddressPrefix 10.1.0.0/24 `
    -PrivateEndpointNetworkPolicies Disabled 

# Create the virtual network
$virtualNetwork = New-AzVirtualNetwork `
    -ResourceGroupName <vm-resource-group-name> `
    -Location "West US" `
    -Name <virtual-network-name> `
    -AddressPrefix 10.1.0.0/16 `
    -Subnet $subnetConfig

# Create the private network connection
$privateLinkConnection = New-AzPrivateLinkServiceConnection `
    -Name <private-link-name> `
    -PrivateLinkServiceId $searchService.Id `
    -GroupId searchService

# Create the private endpoint
$privateEndpoint = New-AzPrivateEndpoint `
    -Name <private-endpoint-name> `
    -ResourceGroupName <private-endpoint-resource-group-name> `
    -Location "West US" `
    -Subnet $virtualNetwork.subnets[0] `
    -PrivateLinkServiceConnection $privateLinkConnection

Infine, creare una zona DNS privata.

## Create private dns zone
$zone = New-AzPrivateDnsZone `
    -ResourceGroupName <private-dns-resource-group-name> `
    -Name "privatelink.search.windows.net"

## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
    -ResourceGroupName <private-dns-link-resource-group-name> `
    -ZoneName "privatelink.search.windows.net" `
    -Name "myLink" `
    -VirtualNetworkId $virtualNetwork.Id

## Create DNS configuration 
$config = New-AzPrivateDnsZoneConfig `
    -Name "privatelink.search.windows.net" `
    -PrivateDnsZoneId $zone.ResourceId

## Create DNS zone group
New-AzPrivateDnsZoneGroup `
    -ResourceGroupName <private-dns-zone-resource-group-name> `
    -PrivateEndpointName <private-endpoint-name> `
    -Name 'myZoneGroup' `
    -PrivateDnsZoneConfig $config

Per altre informazioni sulla creazione di endpoint privati in PowerShell, vedere Avvio rapido del collegamento privato.

Gestire le connessioni endpoint privato

Oltre a creare una connessione all'endpoint privato, è anche possibile Get, Set, e Remove la connessione.

Get-AzSearchPrivateEndpointConnection viene usato per recuperare una connessione a un endpoint privato e visualizzarne lo stato.

Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>

Set-AzSearchPrivateEndpointConnection viene usato per aggiornare la connessione. Nell'esempio seguente viene impostata una connessione a un endpoint privato come rifiutata:

Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected  -Description "Rejected"

Remove-AzSearchPrivateEndpointConnection viene usato per eliminare la connessione a un endpoint privato.

 Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>

Riscrivere una chiave amministratore

New-AzSearchAdminKey viene usato per rinnovare le chiavi APIdi amministrazione. 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 accedervi tramite il portale. Dopo aver rigenerato le chiavi primaria e secondaria, è 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.

New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary

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

Primary                    Secondary
-------                    ---------
<alphanumeric-guid>        <alphanumeric-guid>

Creare o eliminare chiavi di query

New-AzSearchQueryKey viene usato pe creare chiavi di query per l'accesso in sola lettura dalle app client a un indice di Azure AI Search. 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.

New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>

Ridimensionare repliche e partizioni

Set-AzSearchService viene usato per aumentare o diminuire le repliche e le partizioni in modo da riadattare le risorse fatturabili all'interno del servizio. 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.

Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6

I risultati dovrebbero essere simili all'output seguente.

ResourceGroupName : demo-westus
Name              : my-demo-searchapp
Location          : West US
Sku               : Standard
ReplicaCount      : 6
PartitionCount    : 6
HostingMode       : Default
Id                : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp

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 a un 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.

New-AzSearchSharedPrivateLinkResource viene usato per creare la risorsa di collegamento privato condiviso. Tenere presente che potrebbero essere necessarie alcune configurazioni per l’origine dati prima di eseguire questo comando.

New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-serviceresource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId <group-id> -RequestMessage "Please approve"

Get-AzSearchSharedPrivateLinkResource viene usato per recuperare le risorse di collegamento privato condiviso e visualizzarne lo stato.

Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>

Prima di poterlo usare, è necessario approvare la connessione con il comando seguente.

Approve-AzPrivateEndpointConnection `
    -Name <spl-name> `
    -ServiceName <search-service-name> `
    -ResourceGroupName <search-service-resource-group-name> `
    -Description = "Approved"

Remove-AzSearchSharedPrivateLinkResource viene usato per eliminare la risorsa di collegamento privato condiviso.

$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob

$job | Get-Job

Per i dettagli completi sulla configurazione delle risorse di collegamento privato condiviso, vedere la documentazione sulla creazione di 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.