Gestire il servizio di ricerca di intelligenza artificiale di Azure con PowerShell

  • Articolo

È possibile eseguire cmdlet e script di PowerShell in Windows, Linux o in Azure Cloud Shell per creare e configurare Ricerca di intelligenza artificiale di Azure.

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 un nome del 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 contenuto, ad esempio un indice, da un servizio a un altro. All'interno di un servizio, la creazione di contenuto a livello di codice è tramite l'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 script che chiamano l'API REST o una libreria client per creare e caricare indici in un nuovo servizio.

Le funzionalità di amministrazione in 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 dell'API di anteprima.

Il modulo Az.Search estende Azure PowerShell con parità completa alle versioni stabili delle API REST di gestione della ricerca.

Controllare le versioni e caricare i moduli

Gli esempi in questo articolo sono interattivi e richiedono autorizzazioni elevate. Sono necessari PowerShell locale e Azure PowerShell (modulo Az ).

Controllo della versione di PowerShell

Installare la versione più recente di PowerShell se non è disponibile.

$PSVersionTable.PSVersion

Caricare Azure PowerShell

Se non si è certi che 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 nel comando precedente, provare a caricare il modulo e, in caso di errore, tornare alle istruzioni di installazione di Azure PowerShell per verificare se non è stato eseguito un passaggio.

Import-Module -Name Az

Connessione ad Azure con un token di accesso del browser

È possibile usare le credenziali di accesso del portale per connettersi a una sottoscrizione in PowerShell. In alternativa, è possibile eseguire l'autenticazione non interattiva con un'entità servizio.

Connect-AzAccount

Se si contengono più sottoscrizioni di Azure, impostare la 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 in una sottoscrizione

I comandi seguenti provengono da Az.Resources, restituendo 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, salvando un viaggio nel portale.

Il primo comando restituisce tutti i servizi di ricerca.

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

Nell'elenco dei servizi restituire 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

Importazione Az.Search

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

Install-Module -Name Az.Search -Scope CurrentUser

Elencare tutti i Az.Search comandi

Come passaggio di verifica, restituire un elenco di 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 ha una versione precedente del pacchetto, aggiornare il modulo per ottenere le funzionalità più recenti.

Update-Module -Name Az.Search

Ottenere informazioni sul servizio di ricerca

Dopo l'importazione di Az.Search 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, specificare 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, potrebbe essere necessario creare un servizio di ricerca con un firewall IP configurato. A tale scopo, definire prima le regole IP e quindi passarle al IPRuleList parametro come illustrato 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 Ricerca intelligenza artificiale di Azure consentono a un client in una rete virtuale di accedere in modo sicuro ai dati in un indice di ricerca in un collegamento privato. L'endpoint privato usa un indirizzo IP dallo spazio di 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 nella rete backbone Microsoft, eliminando l'esposizione dalla rete Internet pubblica. Per altre informazioni, vedere Creazione di un endpoint privato per Ricerca di intelligenza artificiale di Azure.

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

Prima di tutto, 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

Creare quindi 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 questa guida introduttiva collegamento privato.

Gestire le connessioni endpoint privato

Oltre a creare una connessione endpoint privato, è anche Getpossibile , Sete Remove la connessione.

Get-AzSearchPrivateEndpoint Connessione ion viene usato per recuperare una connessione endpoint privato e visualizzarne lo stato.

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

Set-AzSearchPrivateEndpoint Connessione ion viene usato per aggiornare la connessione. Nell'esempio seguente viene impostata una connessione endpoint privato su rifiutata:

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

Remove-AzSearchPrivateEndpoint Connessione ion viene usato per eliminare la connessione all'endpoint privato.

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

Riscrivere una chiave amministratore

New-AzSearch Amministrazione Key viene usato per eseguire il rollover delle chiavi API di amministrazione. Vengono create due chiavi di amministrazione con ogni servizio 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. Esistono due chiavi in modo che sia possibile usare una durante la sostituzione dell'altra.

È possibile rigenerare solo uno alla volta, specificato 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 esecuzione.

Come previsto, se si rigenerano 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 l'utente dal 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 nuove operazioni riprenderanno di conseguenza.

I valori per le chiavi API vengono generati dal servizio. Non è possibile fornire una chiave personalizzata per Ricerca di intelligenza artificiale di Azure da usare. 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 si modifica solo una alla volta.

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

Creare o eliminare chiavi di query

New-AzSearchQueryKey viene usato per creare chiavi API di query per l'accesso in sola lettura dalle app client a un indice di Ricerca di intelligenza artificiale di Azure. Le chiavi di query vengono usate per eseguire l'autenticazione in un indice specifico per il recupero dei risultati della ricerca. Le chiavi di query non concedono l'accesso in sola lettura ad altri elementi nel servizio, ad esempio un indice, un'origine dati o un indicizzatore.

Non è possibile fornire una chiave per Ricerca di intelligenza artificiale di Azure da usare. 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 ridurre le repliche e le partizioni per riaggiungere le risorse fatturabili all'interno del servizio. L'aumento delle repliche o delle partizioni aggiunge alla fattura, con addebiti fissi e variabili. Se è necessaria una maggiore potenza di elaborazione, è possibile aumentare le repliche e le partizioni per gestire il carico di lavoro. L'area di monitoraggio nella pagina Del portale di panoramica include riquadri sulla latenza delle query, sulle query al secondo e sulla limitazione, che indica se la capacità corrente è adeguata.

L'aggiunta o la rimozione dell'origine può richiedere del tempo. Le modifiche alla capacità si verificano in background, consentendo ai carichi di lavoro esistenti di continuare. La capacità aggiuntiva viene usata per le richieste in ingresso non appena è pronta, senza alcuna configurazione aggiuntiva necessaria.

La rimozione della capacità può comportare interruzioni. È consigliabile arrestare tutti i processi di indicizzazione e indicizzatore prima di ridurre la capacità per evitare richieste eliminate. Se ciò non è fattibile, è possibile ridurre la capacità in modo incrementale, una replica e una partizione alla volta, fino al raggiungimento dei nuovi livelli di destinazione.

Dopo aver inviato il comando, non è possibile terminarlo a metà strada. È 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 Ricerca di intelligenza artificiale di Azure vengono definiti risorse di collegamento privato condiviso. Ciò è dovuto al fatto che si sta "condividendo" l'accesso a una risorsa, ad esempio un account di archiviazione integrato con il servizio collegamento privato di Azure.

Se si usa un indicizzatore per indicizzare i dati in Ricerca di intelligenza artificiale di Azure 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 Ricerca intelligenza artificiale di Azure è disponibile qui insieme ai valori di ID gruppo correlati.

New-AzSearchSharedPrivateLinkResource viene usato per creare la risorsa collegamento privato condiviso. Tenere presente che alcune configurazioni potrebbero essere necessarie 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 consente di recuperare le risorse di collegamento privato condiviso e visualizzare il relativo stato.

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

È necessario approvare la connessione con il comando seguente prima di poterla usare.

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 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 informazioni dettagliate sulla configurazione delle risorse di collegamento privato condiviso, vedere la documentazione relativa alla creazione di connessioni dell'indicizzatore tramite un endpoint privato.

Passaggi successivi

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