Správa služby Azure AI Vyhledávač pomocí PowerShellu

Poznámka:

Azure AI Vyhledávač je k dispozici prostřednictvím portálu Azure, rozhraní REST API a Sady Azure SDK. Podporuje také Foundry IQ, spravovanou znalostní vrstvu, která transformuje podnikový obsah na opakovaně použitelné znalostní báze s podporou oprávnění pro agenty na portálu Microsoft Foundry.

K vytvoření a konfiguraci služby Azure AI Vyhledávač 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:

Následující informace odpovídají na běžné otázky týkající se úkolů, které nejsou v předchozím seznamu.

Název nebo oblast služby nemůžete programově ani na webu Azure Portal změnit. Vyhrazené prostředky se při vytváření služby přidělují, takže změna základního hardwaru (umístění nebo typu uzlu) vyžaduje novou službu.

Poznámka:

Rozhraní REST API služby Search Management a Azure Portal podporují změnu cenové úrovně. V současné době můžete přepínat pouze mezi úrovněmi Basic a Standard (S1, S2 a S3).

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 REST API vyhledávací služby nebo sady SDK, jako je 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čítání 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í k 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 neinteraktivně ověřit pomocí služebního principálu.

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, tyto příkazy vrátí tyto informace, takže nemusíte navštěvovat portál Azure.

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 zdroji.

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

Dovoz 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ě

Jakmile naimportujete Az.Search a máte informace o skupině prostředků obsahující vaši vyhledávací službu, spusťte Get-AzSearchService, abyste získali definici služby, včetně názvu, oblasti, úrovně 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 vašich požadavcích na zabezpečení můžete chtít vytvořit vyhledávací službu s nakonfigurovaným IP firewallem . 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. Nastavte -Sku na Standard3 a -HostingMode na HighDensity.

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 Vyhledávač 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 Vyhledávač.

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 PublicNetworkAccess nastaveným na 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

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, Set a Remove připojení.

Get-AzSearchPrivateEndpointConnection 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-AzSearchPrivateEndpointConnection slouží k aktualizaci připojení. Následující příklad nastaví privátní připojení koncového bodu na zamítnuto.

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

Remove-AzSearchPrivateEndpointConnection 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-AzSearchAdminKey se používá k obnovení správcovských klíčů rozhraní API. 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 najednou, určenou buď jako primary, nebo secondary klíč. Aby byla zajištěna nepřerušovaná služba, nezapomeňte aktualizovat veškerý klientský kód k použití sekundárního klíče při přechodu z 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 prostřednictvím webu Azure Portal. 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 Vyhledávač 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 pouze jeden z nich najednou.

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 Vyhledávač. Klíče dotazů se používají k ověření přístupu k určitému indexu pro získá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 Vyhledávač 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>

Repliky v měřítku a oddíly

Set-AzSearchService se používá ke zvýšení nebo snížení počtu replik a oddílů, aby bylo možné upravit využití fakturovatelných prostředků ve vaší službě. Zvýšení replik nebo oddílů bude přidáno k vaší faktuře, obsahující jak pevné, tak 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é snižování kapacity, vždy po jedné replice a jednom oddílu, 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 Vyhledávač 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 Vyhledávač 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 Vyhledávač, 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í webu Azure Portal, rozhraní REST API nebo sady .NET SDK.

  • Poslední aktualizace v