Hantera din Azure AI-tjänsten Search med PowerShell

  • Artikel

Du kan köra PowerShell-cmdletar och skript i Windows, Linux eller i Azure Cloud Shell för att skapa och konfigurera Azure AI Search.

Använd az.search-modulen för att utföra följande uppgifter:

Ibland kan frågor ställas om uppgifter som inte finns med i listan ovan.

Du kan inte ändra ett servernamn, en region eller en nivå programmatiskt eller i portalen. Dedikerade resurser allokeras när du skapar en tjänst. Därför krävs en ny tjänst för att ändra den underliggande maskinvaran (plats eller nodtyp).

Du kan inte använda verktyg eller API:er för att överföra innehåll, till exempel ett index, från en tjänst till en annan. Inom en tjänst är programmatiskt skapande av innehåll via Search Service REST API eller ett SDK, till exempel Azure SDK för .NET. Det finns inga dedikerade kommandon för innehållsmigrering, men du kan skriva skript som anropar REST API eller ett klientbibliotek för att skapa och läsa in index på en ny tjänst.

Administrationsfunktioner för förhandsversioner är vanligtvis inte tillgängliga i Az.Search-modulen . Om du vill använda en förhandsversionsfunktion använder du REST API för hantering och en förhandsversion av API:et.

Az.Search-modulen utökar Azure PowerShell med fullständig paritet till de stabila versionerna av REST-API:erna för sökhantering.

Kontrollera versioner och läsa in moduler

Exemplen i den här artikeln är interaktiva och kräver utökade behörigheter. Lokal PowerShell och Azure PowerShell (Az-modulen) krävs.

Kontroll av PowerShell-version

Installera den senaste versionen av PowerShell om du inte har den.

$PSVersionTable.PSVersion

Läs in Azure PowerShell

Om du inte är säker på om Az är installerat kör du följande kommando som ett verifieringssteg.

Get-InstalledModule -Name Az

Vissa system läser inte in moduler automatiskt. Om du får ett fel på föregående kommando kan du prova att läsa in modulen, och om det misslyckas går du tillbaka till installationsanvisningarna för Azure PowerShell-installationen för att se om du missade ett steg.

Import-Module -Name Az

Anslut till Azure med en webbläsarinloggningstoken

Du kan använda dina inloggningsuppgifter för portalen för att ansluta till en prenumeration i PowerShell. Du kan också autentisera icke-interaktivt med ett huvudnamn för tjänsten.

Connect-AzAccount

Om du har flera Azure-prenumerationer anger du din Azure-prenumeration. Om du vill se en lista över dina aktuella prenumerationer kör du det här kommandot.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Om du vill ange prenumerationen kör du följande kommando. I följande exempel är ContosoSubscriptionprenumerationsnamnet .

Select-AzSubscription -SubscriptionName ContosoSubscription

Visa en lista över tjänster i en prenumeration

Följande kommandon kommer från Az.Resources och returnerar information om befintliga resurser och tjänster som redan har etablerats i din prenumeration. Om du inte vet hur många söktjänster som redan har skapats returnerar dessa kommandon den informationen, vilket sparar en resa till portalen.

Det första kommandot returnerar alla söktjänster.

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

I listan över tjänster returnerar du information om en specifik resurs.

Get-AzResource -ResourceName <service-name>

Resultaten bör se ut ungefär som följande utdata.

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

Importera Az.Search

Kommandon från Az.Search är inte tillgängliga förrän du har läst in modulen.

Install-Module -Name Az.Search -Scope CurrentUser

Visa en lista över alla Az.Search kommandon

Som ett verifieringssteg returnerar du en lista över kommandon som tillhandahålls i modulen.

Get-Command -Module Az.Search

Resultaten bör se ut ungefär som följande utdata.

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

Om du har en äldre version av paketet uppdaterar du modulen för att få de senaste funktionerna.

Update-Module -Name Az.Search

Hämta söktjänstinformation

När Az.Search har importerats och du känner till resursgruppen som innehåller söktjänsten kör du Get-AzSearchService för att returnera tjänstdefinitionen, inklusive namn, region, nivå och antal repliker och partitioner. För det här kommandot anger du den resursgrupp som innehåller söktjänsten.

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

Resultaten bör se ut ungefär som följande utdata.

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

Skapa eller ta bort en tjänst

New-AzSearchService används för att skapa en ny söktjänst.

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

Resultaten bör se ut ungefär som följande utdata.

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 används för att ta bort en tjänst och dess data.

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

Du uppmanas att bekräfta åtgärden.

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

Skapa en tjänst med IP-regler

Beroende på dina säkerhetskrav kanske du vill skapa en söktjänst med en konfigurerad IP-brandvägg. Det gör du genom att först definiera IP-reglerna och sedan skicka dem till parametern IPRuleList enligt nedan.

$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

Skapa en tjänst med en systemtilldelad hanterad identitet

I vissa fall, till exempel när du använder hanterad identitet för att ansluta till en datakälla, måste du aktivera systemtilldelad hanterad identitet. Detta görs genom att lägga -IdentityType SystemAssigned till i kommandot.

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

Skapa en S3HD-tjänst

För att skapa en S3HD-tjänst används en kombination av -Sku och -HostingMode . Ange -Sku till Standard3 och -HostingMode till HighDensity.

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

Skapa en tjänst med en privat slutpunkt

Privata slutpunkter för Azure AI Search gör det möjligt för en klient i ett virtuellt nätverk att på ett säkert sätt komma åt data i ett sökindex via en Private Link. Den privata slutpunkten använder en IP-adress från det virtuella nätverkets adressutrymme för söktjänsten. Nätverkstrafiken mellan klienten och söktjänsten passerar över det virtuella nätverket och en privat länk i Microsofts stamnätverk, vilket eliminerar exponeringen från det offentliga Internet. Mer information finns i Skapa en privat slutpunkt för Azure AI Search.

I följande exempel visas hur du skapar en söktjänst med en privat slutpunkt.

Distribuera först en söktjänst med PublicNetworkAccess inställd på 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

Skapa sedan ett virtuellt nätverk, en privat nätverksanslutning och en privat slutpunkt.

# 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

Skapa slutligen en privat DNS-zon.

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

Mer information om hur du skapar privata slutpunkter i PowerShell finns i den här snabbstarten för Private Link.

Hantera privata slutpunktsanslutningar

Förutom att skapa en privat slutpunktsanslutning kan du även Get, Setoch Remove anslutningen.

Get-AzSearchPrivateEndpoint Anslut ion används för att hämta en privat slutpunktsanslutning och för att se dess status.

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

Set-AzSearchPrivateEndpoint Anslut ion används för att uppdatera anslutningen. I följande exempel anges en privat slutpunktsanslutning till avvisad:

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

Remove-AzSearchPrivateEndpoint Anslut ion används för att ta bort den privata slutpunktsanslutningen.

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

Återskapa administratörsnycklar

New-AzSearchAdminKey används för att rulla över administratörs-API-nycklar. Två administratörsnycklar skapas med varje tjänst för autentiserad åtkomst. Nycklar krävs för varje begäran. Båda administratörsnycklarna är funktionellt likvärdiga, vilket ger fullständig skrivåtkomst till en söktjänst med möjlighet att hämta all information eller skapa och ta bort alla objekt. Det finns två nycklar så att du kan använda en när du ersätter den andra.

Du kan bara återskapa en i taget, som anges som antingen primary eller-nyckeln secondary . Kom ihåg att uppdatera all klientkod för att använda en sekundär nyckel när du rullar över den primära nyckeln för oavbruten tjänst. Undvik att ändra nycklarna under drift.

Om du återskapar nycklar utan att uppdatera klientkoden misslyckas begäranden som använder den gamla nyckeln som du kan förvänta dig. Att återskapa alla nya nycklar låser dig inte permanent från tjänsten och du kan fortfarande komma åt tjänsten via portalen. När du har återskapat primära och sekundära nycklar kan du uppdatera klientkoden för att använda de nya nycklarna och åtgärderna återupptas i enlighet med detta.

Värden för API-nycklarna genereras av tjänsten. Du kan inte ange en anpassad nyckel för Azure AI Search att använda. På samma sätt finns det inget användardefinierat namn för administratörs-API-nycklar. Referenser till nyckeln är fasta strängar, antingen primary eller secondary.

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

Resultaten bör se ut ungefär som följande utdata. Båda nycklarna returneras även om du bara ändrar en i taget.

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

Skapa eller ta bort frågenycklar

New-AzSearchQueryKey används för att skapa fråge-API-nycklar för skrivskyddad åtkomst från klientappar till ett Azure AI Search-index. Frågenycklar används för att autentisera till ett specifikt index för att hämta sökresultat. Frågenycklar ger inte skrivskyddad åtkomst till andra objekt i tjänsten, till exempel index, datakälla eller indexerare.

Du kan inte ange en nyckel som Azure AI Search kan använda. API-nycklar genereras av tjänsten.

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

Skala repliker och partitioner

Set-AzSearchService används för att öka eller minska repliker och partitioner för att justera fakturerbara resurser i din tjänst. Att öka repliker eller partitioner lägger till din faktura, som har både fasta och variabla avgifter. Om du har ett tillfälligt behov av mer bearbetningskraft kan du öka repliker och partitioner för att hantera arbetsbelastningen. Övervakningsområdet på översiktsportalsidan innehåller paneler om frågesvarstid, frågor per sekund och begränsning som anger om den aktuella kapaciteten är tillräcklig.

Det kan ta en stund att lägga till eller ta bort resursen. Kapacitetsjusteringar sker i bakgrunden, vilket gör att befintliga arbetsbelastningar kan fortsätta. Extra kapacitet används för inkommande begäranden så snart den är klar, utan att någon extra konfiguration krävs.

Det kan vara störande att ta bort kapacitet. Vi rekommenderar att du stoppar alla indexerings- och indexeringsjobb innan du minskar kapaciteten för att undvika borttagna begäranden. Om det inte är möjligt kan du överväga att minska kapaciteten stegvis, en replik och partition i taget tills de nya målnivåerna har nåtts.

När du har skickat kommandot går det inte att avsluta det halvvägs. Du måste vänta tills kommandot är klart innan du ändrar antalet.

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

Resultaten bör se ut ungefär som följande utdata.

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

Privata slutpunkter för skyddade resurser som skapas via Api:er för Azure AI Search kallas delade privata länkresurser. Det beror på att du "delar" åtkomsten till en resurs, till exempel ett lagringskonto som har integrerats med Azure Private Link-tjänsten.

Om du använder en indexerare för att indexera data i Azure AI Search och din datakälla finns i ett privat nätverk kan du skapa en utgående privat slutpunktsanslutning för att nå data.

En fullständig lista över De Azure-resurser som du kan skapa utgående privata slutpunkter för från Azure AI Search finns här tillsammans med relaterade grupp-ID-värden .

New-AzSearchSharedPrivateLinkResource används för att skapa resursen för delad privat länk. Tänk på att viss konfiguration kan krävas för datakällan innan du kör det här kommandot.

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"

Med Get-AzSearchSharedPrivateLinkResource kan du hämta resurserna för delade privata länkar och visa deras status.

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

Du måste godkänna anslutningen med följande kommando innan den kan användas.

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

Remove-AzSearchSharedPrivateLinkResource används för att ta bort resursen för delad privat länk.

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

$job | Get-Job

Fullständig information om hur du konfigurerar delade privata länkresurser finns i dokumentationen om hur du skapar indexerareanslutningar via en privat slutpunkt.

Nästa steg

Skapa ett index, fråga ett index med hjälp av portalen, REST-API:er eller .NET SDK.