Delen via

Uw Azure AI-Search-service beheren met PowerShell

  • Artikel

U kunt PowerShell-cmdlets en -scripts uitvoeren in Windows, Linux of in Azure Cloud Shell om Azure AI Search te maken en configureren.

Gebruik de Az.Search-module om de volgende taken uit te voeren:

Soms worden er vragen gesteld over taken die niet in de bovenstaande lijst staan.

U kunt een servernaam, regio of laag niet programmatisch of in de portal wijzigen. Toegewezen resources worden toegewezen zodra een service wordt gemaakt. Als zodanig vereist het wijzigen van de onderliggende hardware (locatie of knooppunttype) een nieuwe service.

U kunt geen hulpprogramma's of API's gebruiken om inhoud, zoals een index, van de ene service naar de andere over te dragen. Binnen een service is het programmatisch maken van inhoud via de REST API van Search Service of een SDK zoals Azure SDK voor .NET. Hoewel er geen speciale opdrachten zijn voor inhoudsmigratie, kunt u een script schrijven dat REST API of een clientbibliotheek aanroept om indexen voor een nieuwe service te maken en te laden.

Preview-beheerfuncties zijn doorgaans niet beschikbaar in de Az.Search-module . Als u een preview-functie wilt gebruiken, gebruikt u de MANAGEMENT REST API en een preview-API-versie.

De Az.Search-module breidt Azure PowerShell met volledige pariteit uit naar de stabiele versies van de REST API's van Search Management.

Versies controleren en modules laden

De voorbeelden in dit artikel zijn interactief en vereisen verhoogde machtigingen. Lokale PowerShell en de Azure PowerShell (de Az-module ) zijn vereist.

PowerShell-versiecontrole

Installeer de nieuwste versie van PowerShell als u deze niet hebt.

$PSVersionTable.PSVersion

Azure PowerShell laden

Als u niet zeker weet of Az is geïnstalleerd, voert u de volgende opdracht uit als verificatiestap.

Get-InstalledModule -Name Az

Sommige systemen laden modules niet automatisch. Als er een fout optreedt bij de vorige opdracht, laadt u de module en als dat mislukt, gaat u terug naar de installatie-instructies van Azure PowerShell om te zien of u een stap hebt gemist.

Import-Module -Name Az

Verbinding maken met Azure met een aanmeldingstoken van een browser

U kunt uw aanmeldingsreferenties voor de portal gebruiken om verbinding te maken met een abonnement in PowerShell. U kunt ook niet-interactief verifiëren met een service-principal.

Connect-AzAccount

Als u meerdere Azure-abonnementen hebt, stelt u uw Azure-abonnement in. Voer deze opdracht uit om een lijst met uw huidige abonnementen weer te geven.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Voer de volgende opdracht uit om het abonnement op te geven. In het volgende voorbeeld is ContosoSubscriptionde naam van het abonnement.

Select-AzSubscription -SubscriptionName ContosoSubscription

Services in een abonnement vermelden

De volgende opdrachten zijn afkomstig van Az.Resources en retourneren informatie over bestaande resources en services die al in uw abonnement zijn ingericht. Als u niet weet hoeveel zoekservices er al zijn gemaakt, retourneren deze opdrachten die informatie retourneren, waardoor u een reis naar de portal opslaat.

Met de eerste opdracht worden alle zoekservices geretourneerd.

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

Geef in de lijst met services informatie over een specifieke resource op.

Get-AzResource -ResourceName <service-name>

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer.

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

Importeren Az.Search

Opdrachten van Az.Search zijn pas beschikbaar wanneer u de module laadt.

Install-Module -Name Az.Search -Scope CurrentUser

Az.Search Alle opdrachten weergeven

Als verificatiestap retourneert u een lijst met opdrachten die zijn opgegeven in de module.

Get-Command -Module Az.Search

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer.

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

Als u een oudere versie van het pakket hebt, werkt u de module bij om de nieuwste functionaliteit te verkrijgen.

Update-Module -Name Az.Search

Informatie over zoekservice ophalen

Nadat Az.Search is geïmporteerd en u weet welke resourcegroep uw zoekservice bevat, voert u Get-AzSearchService uit om de servicedefinitie te retourneren, inclusief naam, regio, laag en aantal replica's en partities. Geef voor deze opdracht de resourcegroep op die de zoekservice bevat.

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

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer.

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

Een service maken of verwijderen

New-AzSearchService wordt gebruikt om een nieuwe zoekservice te maken.

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

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer.

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 wordt gebruikt om een service en de bijbehorende gegevens te verwijderen.

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

U wordt gevraagd de actie te bevestigen.

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

Een service maken met IP-regels

Afhankelijk van uw beveiligingsvereisten wilt u mogelijk een zoekservice maken met een IP-firewall die is geconfigureerd. Hiervoor definieert u eerst de IP-regels en geeft u deze door aan de IPRuleList parameter, zoals hieronder wordt weergegeven.

$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

Een service maken met een door het systeem toegewezen beheerde identiteit

In sommige gevallen, zoals wanneer u beheerde identiteit gebruikt om verbinding te maken met een gegevensbron, moet u door het systeem toegewezen beheerde identiteit inschakelen. Dit wordt gedaan door de opdracht toe te voegen -IdentityType SystemAssigned .

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

Een S3HD-service maken

Voor het maken van een S3HD-service wordt een combinatie van -Sku en -HostingMode gebruikt. Ingesteld -Sku op Standard3 en -HostingMode op HighDensity.

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

Een service maken met een privé-eindpunt

Met privé-eindpunten voor Azure AI Search kan een client in een virtueel netwerk veilig toegang krijgen tot gegevens in een zoekindex via een Private Link. Het privé-eindpunt maakt gebruik van een IP-adres uit de adresruimte van het virtuele netwerk voor uw zoekservice. Netwerkverkeer tussen de client en de zoekservice loopt via het virtuele netwerk en een privékoppeling in het Microsoft backbone-netwerk, waardoor blootstelling van het openbare internet wordt geëlimineerd. Zie Een privé-eindpunt maken voor Azure AI Search voor meer informatie.

In het volgende voorbeeld ziet u hoe u een zoekservice maakt met een privé-eindpunt.

Implementeer eerst een zoekservice met PublicNetworkAccess de waarde .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

Maak vervolgens een virtueel netwerk, een privénetwerkverbinding en het privé-eindpunt.

# 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

Maak ten slotte een privé-DNS-zone.

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

Zie deze quickstart voor Private Link voor meer informatie over het maken van privé-eindpunten in PowerShell.

Privé-eindpuntverbindingen beheren

Naast het maken van een privé-eindpuntverbinding kunt u ook Get, Seten Remove de verbinding.

Get-AzSearchPrivateEndpointConnection wordt gebruikt om een privé-eindpuntverbinding op te halen en de status ervan te zien.

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

Set-AzSearchPrivateEndpointConnection wordt gebruikt om de verbinding bij te werken. In het volgende voorbeeld wordt een privé-eindpuntverbinding ingesteld op geweigerd:

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

Remove-AzSearchPrivateEndpointConnection wordt gebruikt om de privé-eindpuntverbinding te verwijderen.

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

Beheerderssleutels opnieuw genereren

New-AzSearchAdminKey wordt gebruikt voor het overrollen van beheerders-API-sleutels. Er worden twee beheerderssleutels gemaakt met elke service voor geverifieerde toegang. Sleutels zijn vereist voor elke aanvraag. Beide beheerderssleutels zijn functioneel gelijkwaardig, waarbij volledige schrijftoegang tot een zoekservice wordt verleend met de mogelijkheid om informatie op te halen of een object te maken en te verwijderen. Er bestaan twee sleutels, zodat u er een kunt gebruiken terwijl u de andere vervangt.

U kunt slechts één voor één opnieuw genereren, opgegeven als de primary of secondary sleutel. Voor ononderbroken service moet u alle clientcode bijwerken om een secundaire sleutel te gebruiken tijdens het rollen van de primaire sleutel. Vermijd het wijzigen van de sleutels terwijl bewerkingen actief zijn.

Zoals u zou verwachten, mislukken aanvragen met behulp van de oude sleutel als u sleutels opnieuw genereert zonder clientcode bij te werken. Door alle nieuwe sleutels opnieuw te genereren, wordt uw service niet permanent vergrendeld en hebt u nog steeds toegang tot de service via de portal. Nadat u primaire en secundaire sleutels opnieuw hebt gegenereerd, kunt u clientcode bijwerken om de nieuwe sleutels en bewerkingen dienovereenkomstig te gebruiken.

Waarden voor de API-sleutels worden gegenereerd door de service. U kunt geen aangepaste sleutel opgeven die Azure AI Search kan gebruiken. Op dezelfde manier is er geen door de gebruiker gedefinieerde naam voor beheerders-API-sleutels. Verwijzingen naar de sleutel zijn vaste tekenreeksen, ofwel primary secondary.

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

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer. Beide sleutels worden geretourneerd, zelfs als u slechts één voor één wijzigt.

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

Querysleutels maken of verwijderen

New-AzSearchQueryKey wordt gebruikt om query-API-sleutels te maken voor alleen-lezentoegang van client-apps naar een Azure AI Search-index. Querysleutels worden gebruikt om te verifiëren bij een specifieke index voor het ophalen van zoekresultaten. Querysleutels verlenen geen alleen-lezentoegang tot andere items in de service, zoals een index, gegevensbron of indexeerfunctie.

U kunt geen sleutel opgeven die Azure AI Search kan gebruiken. API-sleutels worden gegenereerd door de service.

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

Replica's en partities schalen

Set-AzSearchService wordt gebruikt om replica's en partities te vergroten of verkleinen om factureerbare resources binnen uw service aan te passen. Het verhogen van replica's of partities wordt toegevoegd aan uw factuur, met zowel vaste als variabele kosten. Als u tijdelijk meer verwerkingskracht nodig hebt, kunt u replica's en partities verhogen om de werkbelasting te verwerken. Het bewakingsgebied op de pagina Overzichtsportal bevat tegels over querylatentie, query's per seconde en beperking, waarmee wordt aangegeven of de huidige capaciteit voldoende is.

Het kan even duren voordat u bronnen toevoegt of verwijdert. Aanpassingen aan de capaciteit vinden op de achtergrond plaats, zodat bestaande workloads kunnen worden voortgezet. Extra capaciteit wordt gebruikt voor binnenkomende aanvragen zodra deze gereed is, zonder dat er extra configuratie is vereist.

Het verwijderen van capaciteit kan verstorend zijn. Het wordt aanbevolen om alle indexerings- en indexeertaken te stoppen voordat u de capaciteit verlaagt om verwijderde aanvragen te voorkomen. Als dat niet haalbaar is, kunt u overwegen om de capaciteit incrementeel te verminderen, één replica en partitie tegelijk, totdat uw nieuwe doelniveaus zijn bereikt.

Zodra u de opdracht hebt verzonden, kunt u deze niet halverwege beëindigen. U moet wachten totdat de opdracht is voltooid voordat de tellingen worden herzien.

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

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer.

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é-eindpunten van beveiligde resources die worden gemaakt via Azure AI Search-API's, worden gedeelde private link-resources genoemd. Dit komt doordat u toegang tot een resource deelt, zoals een opslagaccount dat is geïntegreerd met de Azure Private Link-service.

Als u een indexeerfunctie gebruikt om gegevens te indexeren in Azure AI Search en uw gegevensbron zich in een privénetwerk bevindt, kunt u een uitgaande privé-eindpuntverbinding maken om de gegevens te bereiken.

Hier vindt u een volledige lijst met de Azure-resources waarvoor u uitgaande privé-eindpunten kunt maken vanuit Azure AI Search, samen met de gerelateerde groeps-id-waarden.

New-AzSearchSharedPrivateLinkResource wordt gebruikt om de gedeelde private link-resource te maken. Houd er rekening mee dat sommige configuraties mogelijk vereist zijn voor de gegevensbron voordat u deze opdracht uitvoert.

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"

Met Get-AzSearchSharedPrivateLinkResource kunt u de gedeelde private link-resources ophalen en hun status bekijken.

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

U moet de verbinding met de volgende opdracht goedkeuren voordat deze kan worden gebruikt.

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

Remove-AzSearchSharedPrivateLinkResource wordt gebruikt om de gedeelde private link-resource te verwijderen.

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

$job | Get-Job

Zie de documentatie over het maken van indexeerverbindingen via een privé-eindpunt voor meer informatie over het instellen van gedeelde private link-resources.

Volgende stappen

Bouw een index, voer een query uit op een index met behulp van de portal, REST API's of de .NET SDK.