Správa Search Azure AI pomocí PowerShellu

  • Článek

K vytvoření a konfiguraci služby Azure AI Search můžete spustit rutiny a skripty PowerShellu ve Windows, Linuxu nebo v Azure Cloud Shellu.

Pomocí modulu Az.Search proveďte následující úlohy:

V některých případech jsou otázky týkající se úkolů , které nejsou na výše uvedeném seznamu.

Název serveru, oblast nebo vrstvu nemůžete programově ani na portálu změnit. Při vytvoření služby se přidělí vyhrazené prostředky. Změna základního hardwaru (umístění nebo typu uzlu) proto vyžaduje novou službu.

Pomocí nástrojů nebo rozhraní API nemůžete přenášet obsah, jako je index, z jedné služby do jiné. Programové vytváření obsahu ve službě je prostřednictvím rozhraní REST API vyhledávací služby nebo sady SDK, jako je Sada Azure SDK pro .NET. I když neexistují žádné vyhrazené příkazy pro migraci obsahu, můžete napsat skript, který volá rozhraní REST API nebo klientskou knihovnu pro vytváření a načítání indexů v nové službě.

Funkce pro správu ve verzi Preview nejsou obvykle dostupné v modulu Az.Search . Pokud chcete použít funkci Preview, použijte rozhraní REST API pro správu a verzi rozhraní API ve verzi Preview.

Modul Az.Search rozšiřuje Azure PowerShell o úplnou paritu na stabilní verze rozhraní REST API správy vyhledávání.

Kontrola verzí a načtení modulů

Příklady v tomto článku jsou interaktivní a vyžadují zvýšená oprávnění. Vyžaduje se místní PowerShell a Azure PowerShell ( modul Az ).

Kontrola verze PowerShellu

Pokud ho nemáte, nainstalujte si nejnovější verzi PowerShellu .

$PSVersionTable.PSVersion

Načtení Azure PowerShellu

Pokud si nejste jistí, jestli je Az nainstalovaný, spusťte jako ověřovací krok následující příkaz.

Get-InstalledModule -Name Az

Některé systémy automaticky nenačtou moduly. Pokud se vám v předchozím příkazu zobrazila chyba, zkuste modul načíst a pokud se to nezdaří, vraťte se k instalačním pokynům Azure PowerShellu, abyste zjistili, jestli jste neprošli nějaký krok.

Import-Module -Name Az

Připojení do Azure pomocí přihlašovacího tokenu prohlížeče

Přihlašovací údaje portálu můžete použít k připojení k předplatnému v PowerShellu. Případně můžete ověřit neinteraktivně pomocí instančního objektu.

Connect-AzAccount

Pokud máte více předplatných Azure, nastavte své předplatné Azure. Pokud chcete zobrazit seznam aktuálních předplatných, spusťte tento příkaz.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Pokud chcete zadat předplatné, spusťte následující příkaz. V následujícím příkladu je ContosoSubscriptionnázev předplatného .

Select-AzSubscription -SubscriptionName ContosoSubscription

Výpis služeb v předplatném

Následující příkazy pocházejí z Az.Resources a vracejí informace o existujících prostředcích a službách, které už jsou ve vašem předplatném zřízené. Pokud nevíte, kolik vyhledávacích služeb už je vytvořených, vrátí tyto příkazy tyto informace a uloží vám cestu na portál.

První příkaz vrátí všechny vyhledávací služby.

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

Ze seznamu služeb vrátíte informace o konkrétním prostředku.

Get-AzResource -ResourceName <service-name>

Výsledky by měly vypadat podobně jako v následujícím výstupu.

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

Import Az.Search

Příkazy z Az.Search nejsou dostupné, dokud modul nenačtete.

Install-Module -Name Az.Search -Scope CurrentUser

Výpis všech Az.Search příkazů

Jako krok ověření vraťte seznam příkazů zadaných v modulu.

Get-Command -Module Az.Search

Výsledky by měly vypadat podobně jako v následujícím výstupu.

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

Pokud máte starší verzi balíčku, aktualizujte modul, abyste získali nejnovější funkce.

Update-Module -Name Az.Search

Získání informací o vyhledávací službě

Po importu Az.Search a znáte skupinu prostředků obsahující vaši vyhledávací službu, spusťte Get-AzSearchService a vraťte definici služby, včetně názvu, oblasti, vrstvy a počtu replik a oddílů. Pro tento příkaz zadejte skupinu prostředků, která obsahuje vyhledávací službu.

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

Výsledky by měly vypadat podobně jako v následujícím výstupu.

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

Vytvoření nebo odstranění služby

New-AzSearchService slouží k vytvoření nové vyhledávací služby.

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

Výsledky by měly vypadat podobně jako v následujícím výstupu.

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 slouží k odstranění služby a jejích dat.

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

Zobrazí se výzva k potvrzení akce.

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

Vytvoření služby s pravidly PROTOKOLU IP

V závislosti na požadavcích na zabezpečení můžete chtít vytvořit vyhledávací službu s nakonfigurovanou bránou firewall protokolu IP. Uděláte to tak, že nejprve definujete pravidla PROTOKOLU IP a pak je předáte parametru IPRuleList , jak je znázorněno níže.

$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

Vytvoření služby se spravovanou identitou přiřazenou systémem

V některých případech, například při použití spravované identity pro připojení ke zdroji dat, je potřeba zapnout spravovanou identitu přiřazenou systémem. To se provádí přidáním -IdentityType SystemAssigned do příkazu.

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

Vytvoření služby S3HD

K vytvoření služby S3HD se použije kombinace -Sku a -HostingMode použití. Nastavte -Sku na Standard3 a -HostingMode na HighDensityhodnotu .

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

Vytvoření služby s privátním koncovým bodem

Privátní koncové body pro Azure AI Search umožňují klientovi ve virtuální síti zabezpečený přístup k datům v indexu vyhledávání přes Private Link. Privátní koncový bod používá IP adresu z adresního prostoru virtuální sítě pro vaši vyhledávací službu. Síťový provoz mezi klientem a vyhledávací službou prochází přes virtuální síť a privátní propojení v páteřní síti Microsoftu, čímž se eliminuje vystavení z veřejného internetu. Další informace najdete v tématu Vytvoření privátního koncového bodu pro Azure AI Search.

Následující příklad ukazuje, jak vytvořit vyhledávací službu s privátním koncovým bodem.

Nejprve nasaďte vyhledávací službu s nastavenou PublicNetworkAccess na Disabledhodnotu .

$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

Dále vytvořte virtuální síť, připojení k privátní síti a privátní koncový bod.

# 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

Nakonec vytvořte privátní zónu DNS.

## 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

Další informace o vytváření privátních koncových bodů v PowerShellu najdete v tomto rychlém startu služby Private Link.

Správa připojení privátních koncových bodů

Kromě vytváření připojení privátního koncového bodu můžete také Get, Seta Remove připojení.

Get-AzSearchPrivateEndpoint Připojení ion se používá k načtení připojení privátního koncového bodu a k zobrazení jeho stavu.

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

Set-AzSearchPrivateEndpoint Připojení ion se používá k aktualizaci připojení. Následující příklad nastaví připojení privátního koncového bodu na odmítnuté:

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

Remove-AzSearchPrivateEndpoint Připojení ion slouží k odstranění připojení privátního koncového bodu.

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

Opětovné generování klíčů správce

New-AzSearch Správa Key se používá k vrácení klíčů rozhraní API pro správu. Vytvoří se dva klíče správce s každou službou pro ověřený přístup. Klíče jsou vyžadovány v každém požadavku. Oba klíče správce jsou funkčně ekvivalentní a udělují vyhledávací službě úplný přístup k zápisu s možností načíst jakékoli informace nebo vytvořit a odstranit jakýkoli objekt. Existují dva klíče, takže můžete použít jeden a nahradit druhý.

Můžete znovu vygenerovat pouze jednu po druhé, určenou buď jako primary klíč, nebo secondary klíč. V případě nepřerušované služby nezapomeňte aktualizovat veškerý klientský kód tak, aby používal sekundární klíč při vrácení primárního klíče. Vyhýbejte se změnám klíčů během provozu.

Jak můžete očekávat, pokud klíče znovu vygenerujete bez aktualizace kódu klienta, požadavky používající starý klíč selžou. Opětovné vygenerování všech nových klíčů vás trvale nezamkne z vaší služby a stále se k této službě dostanete přes portál. Jakmile znovu vygenerujete primární a sekundární klíče, můžete aktualizovat klientský kód tak, aby používal nové klíče a operace se odpovídajícím způsobem obnoví.

Služba generuje hodnoty klíčů rozhraní API. Nemůžete zadat vlastní klíč, který by služba Azure AI Search mohla použít. Podobně neexistuje žádný uživatelsky definovaný název pro klíče rozhraní API pro správu. Odkazy na klíč jsou pevné řetězce, buď primary nebo secondary.

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

Výsledky by měly vypadat podobně jako v následujícím výstupu. Oba klíče se vrátí, i když změníte jenom jeden po druhém.

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

Vytvoření nebo odstranění klíčů dotazu

New-AzSearchQueryKey slouží k vytvoření klíčů rozhraní API pro dotazování pro přístup jen pro čtení z klientských aplikací do indexu Azure AI Search. Klíče dotazů se používají k ověření v určitém indexu pro načítání výsledků hledání. Klíče dotazů neudělují přístup jen pro čtení jiným položkám ve službě, jako je index, zdroj dat nebo indexer.

Nemůžete zadat klíč, který by služba Azure AI Search mohla použít. Služba generuje klíče rozhraní API.

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

Škálování replik a oddílů

Set-AzSearchService se používá ke zvýšení nebo snížení replik a oddílů pro čtení fakturovatelných prostředků ve vaší službě. Zvýšení replik nebo oddílů se přidá na fakturu, která má pevné i proměnlivé poplatky. Pokud potřebujete dočasný výkon pro zpracování, můžete zvýšit počet replik a oddílů pro zpracování úlohy. Oblast monitorování na stránce portálu Přehled obsahuje dlaždice týkající se latence dotazů, dotazů za sekundu a omezování, které indikuje, jestli je aktuální kapacita adekvátní.

Přidání nebo odebrání prostředků může chvíli trvat. Úpravy kapacity probíhají na pozadí, což umožňuje pokračovat v existujících úlohách. Kapacita navíc se používá pro příchozí požadavky hned, jak je připravená, a nevyžaduje se žádná další konfigurace.

Odebrání kapacity může být rušivé. Před snížením kapacity se doporučuje zastavit všechny úlohy indexování a indexeru, abyste se vyhnuli vyřazeným požadavkům. Pokud to není možné, můžete zvážit postupné snížení kapacity, jedné repliky a oddílu najednou, dokud nedosáhnete nových cílových úrovní.

Jakmile příkaz odešlete, neexistuje způsob, jak ho ukončit uprostřed cesty. Před revizí počtů musíte počkat na dokončení příkazu.

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

Výsledky by měly vypadat podobně jako v následujícím výstupu.

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

Privátní koncové body zabezpečených prostředků vytvořených prostřednictvím rozhraní API služby Azure AI Search se označují jako sdílené prostředky privátního propojení. Důvodem je to, že sdílíte přístup k prostředku, jako je například účet úložiště, který je integrovaný se službou Azure Private Link.

Pokud k indexování dat ve službě Azure AI Search používáte indexer a váš zdroj dat je v privátní síti, můžete vytvořit odchozí připojení privátního koncového bodu pro přístup k datům.

Úplný seznam prostředků Azure, pro které můžete vytvořit odchozí privátní koncové body ze služby Azure AI Search, najdete tady společně se souvisejícími hodnotami ID skupiny.

New-AzSearchSharedPrivateLinkResource slouží k vytvoření prostředku sdíleného privátního propojení. Mějte na paměti, že před spuštěním tohoto příkazu může být pro zdroj dat vyžadována určitá konfigurace.

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 umožňuje načíst sdílené prostředky privátního propojení a zobrazit jejich stav.

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

Abyste ho mohli použít, musíte připojení schválit pomocí následujícího příkazu.

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

Remove-AzSearchSharedPrivateLinkResource slouží k odstranění prostředku sdíleného privátního propojení.

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

$job | Get-Job

Úplné podrobnosti o nastavení sdílených prostředků privátního propojení najdete v dokumentaci k vytváření připojení indexeru prostřednictvím privátního koncového bodu.

Další kroky

Vytvořte index, dotazujte se na index pomocí portálu, rozhraní REST API nebo sady .NET SDK.