Zarządzanie usługą Azure AI usługa wyszukiwania przy użyciu programu PowerShell

  • Artykuł

Możesz uruchamiać polecenia cmdlet i skrypty programu PowerShell w systemie Windows, Linux lub w usłudze Azure Cloud Shell, aby utworzyć i skonfigurować usługę Azure AI Search.

Użyj modułu Az.Search, aby wykonać następujące zadania:

Od czasu do czasu są zadawane pytania dotyczące zadań , które nie znajdują się na powyższej liście.

Nie można programowo ani programowo zmienić nazwy serwera, regionu ani warstwy. Dedykowane zasoby są przydzielane podczas tworzenia usługi. W związku z tym zmiana podstawowego sprzętu (lokalizacji lub typu węzła) wymaga nowej usługi.

Nie można użyć narzędzi ani interfejsów API do transferu zawartości, takiej jak indeks, z jednej usługi do innej. W ramach usługi programowe tworzenie zawartości odbywa się za pomocą interfejsu API REST usługi wyszukiwania lub zestawu SDK, takiego jak zestaw Azure SDK dla platformy .NET. Chociaż nie ma dedykowanych poleceń migracji zawartości, możesz napisać skrypt wywołujący interfejs API REST lub bibliotekę klienta w celu tworzenia i ładowania indeksów w nowej usłudze.

Funkcje administracji w wersji zapoznawczej są zwykle niedostępne w module Az.Search . Jeśli chcesz użyć funkcji w wersji zapoznawczej, użyj interfejsu API REST zarządzania i wersji zapoznawczej interfejsu API .

Moduł Az.Search rozszerza program Azure PowerShell z pełną parzystością na stabilne wersje interfejsów API REST zarządzania wyszukiwaniem.

Sprawdzanie wersji i ładowanie modułów

Przykłady w tym artykule są interaktywne i wymagają podwyższonych uprawnień. Wymagany jest lokalny program PowerShell i program Azure PowerShell ( moduł Az ).

Sprawdzanie wersji programu PowerShell

Zainstaluj najnowszą wersję programu PowerShell , jeśli jej nie masz.

$PSVersionTable.PSVersion

Ładowanie programu Azure PowerShell

Jeśli nie masz pewności, czy moduł Az jest zainstalowany, uruchom następujące polecenie jako krok weryfikacji.

Get-InstalledModule -Name Az

Niektóre systemy nie ładują automatycznie modułów. Jeśli w poprzednim poleceniu wystąpił błąd, spróbuj załadować moduł i jeśli to się nie powiedzie, wróć do instrukcji instalacji programu Azure PowerShell, aby sprawdzić, czy nie wykonano kroku.

Import-Module -Name Az

Połączenie na platformę Azure przy użyciu tokenu logowania przeglądarki

Możesz użyć poświadczeń logowania portalu, aby nawiązać połączenie z subskrypcją w programie PowerShell. Alternatywnie możesz uwierzytelnić się nieinterakcyjne za pomocą jednostki usługi.

Connect-AzAccount

Jeśli przechowujesz wiele subskrypcji platformy Azure, ustaw subskrypcję platformy Azure. Aby wyświetlić listę bieżących subskrypcji, uruchom to polecenie.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Aby określić subskrypcję, uruchom następujące polecenie. W poniższym przykładzie nazwa subskrypcji to ContosoSubscription.

Select-AzSubscription -SubscriptionName ContosoSubscription

Wyświetlanie listy usług w subskrypcji

Następujące polecenia pochodzą z modułu Az.Resources, zwracając informacje o istniejących zasobach i usługach już aprowizowania w ramach subskrypcji. Jeśli nie wiesz, ile usług wyszukiwania zostało już utworzonych, te polecenia zwracają te informacje, zapisując podróż do portalu.

Pierwsze polecenie zwraca wszystkie usługi wyszukiwania.

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

Z listy usług zwróć informacje o określonym zasobie.

Get-AzResource -ResourceName <service-name>

Wyniki powinny wyglądać podobnie do poniższych danych wyjściowych.

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

Importu Az.Search

Polecenia z narzędzia Az.Search nie są dostępne do momentu załadowania modułu.

Install-Module -Name Az.Search -Scope CurrentUser

Wyświetl listę wszystkich Az.Search poleceń

W ramach kroku weryfikacji zwróć listę poleceń podanych w module.

Get-Command -Module Az.Search

Wyniki powinny wyglądać podobnie do poniższych danych wyjściowych.

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

Jeśli masz starszą wersję pakietu, zaktualizuj moduł, aby uzyskać najnowsze funkcje.

Update-Module -Name Az.Search

Pobieranie informacji o usłudze wyszukiwania

Po zaimportowaniu polecenia Az.Search i zapoznaniu się z grupą zasobów zawierającą usługę wyszukiwania uruchom polecenie Get-AzSearchService , aby zwrócić definicję usługi, w tym nazwę, region, warstwę oraz liczbę replik i partycji. W tym poleceniu podaj grupę zasobów zawierającą usługę wyszukiwania.

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

Wyniki powinny wyglądać podobnie do poniższych danych wyjściowych.

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

Tworzenie lub usuwanie usługi

Usługa New-AzSearchService służy do tworzenia nowej usługi wyszukiwania.

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

Wyniki powinny wyglądać podobnie do poniższych danych wyjściowych.

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 służy do usuwania usługi i jej danych.

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

Zostanie wyświetlona prośba o potwierdzenie akcji.

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

Tworzenie usługi z regułami adresów IP

W zależności od wymagań dotyczących zabezpieczeń możesz utworzyć usługę wyszukiwania z skonfigurowaną zaporą IP. W tym celu najpierw zdefiniuj reguły adresów IP, a następnie przekaż je do parametru IPRuleList , jak pokazano poniżej.

$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

Tworzenie usługi z tożsamością zarządzaną przypisaną przez system

W niektórych przypadkach, takich jak w przypadku używania tożsamości zarządzanej do nawiązywania połączenia ze źródłem danych, należy włączyć tożsamość zarządzaną przypisaną przez system. Odbywa się to przez dodanie -IdentityType SystemAssigned do polecenia .

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

Tworzenie usługi S3HD

Aby utworzyć usługę S3HD , używana jest kombinacja -Sku i -HostingMode . Ustaw -Sku wartość Standard3 na i -HostingMode na HighDensity.

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

Tworzenie usługi z prywatnym punktem końcowym

Prywatne punkty końcowe usługi Azure AI Search umożliwiają klientowi w sieci wirtualnej bezpieczny dostęp do danych w indeksie wyszukiwania za pośrednictwem usługi Private Link. Prywatny punkt końcowy używa adresu IP z przestrzeni adresowej sieci wirtualnej dla usługi wyszukiwania. Ruch sieciowy między klientem a usługą wyszukiwania przechodzi przez sieć wirtualną i łącze prywatne w sieci szkieletowej firmy Microsoft, eliminując narażenie z publicznego Internetu. Aby uzyskać więcej informacji, zobacz Tworzenie prywatnego punktu końcowego dla usługi Azure AI Search.

W poniższym przykładzie pokazano, jak utworzyć usługę wyszukiwania z prywatnym punktem końcowym.

Najpierw wdróż usługę wyszukiwania z ustawioną PublicNetworkAccess wartością 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

Następnie utwórz sieć wirtualną, połączenie z siecią prywatną i prywatny punkt końcowy.

# 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

Na koniec utwórz prywatną strefę 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

Aby uzyskać więcej informacji na temat tworzenia prywatnych punktów końcowych w programie PowerShell, zobacz ten przewodnik Szybki start dotyczący usługi Private Link.

Zarządzanie połączeniami z prywatnymi punktami końcowymi

Oprócz tworzenia połączenia prywatnego punktu końcowego można również Get, Seti Remove połączenia.

Polecenie Get-AzSearchPrivateEndpoint Połączenie ion służy do pobierania połączenia prywatnego punktu końcowego i wyświetlenia jego stanu.

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

Polecenie Set-AzSearchPrivateEndpoint Połączenie ion służy do aktualizowania połączenia. W poniższym przykładzie ustawiono połączenie prywatnego punktu końcowego na odrzucone:

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

Remove-AzSearchPrivateEndpoint Połączenie ion służy do usuwania połączenia prywatnego punktu końcowego.

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

Ponowne generowanie kluczy administratora

Polecenie New-AzSearch Administracja Key służy do przerzucania kluczy interfejsu API administratora. Dwa klucze administratora są tworzone z każdą usługą w celu uwierzytelnienia dostępu. Klucze są wymagane na każdym żądaniu. Oba klucze administratora są funkcjonalnie równoważne, udzielając pełnego dostępu do zapisu w usłudze wyszukiwania z możliwością pobierania wszelkich informacji lub tworzenia i usuwania dowolnego obiektu. Istnieją dwa klucze, dzięki czemu można użyć jednego podczas zastępowania drugiego.

Można ponownie wygenerować tylko jeden raz, określony jako primary klucz lub secondary . Aby zapewnić nieprzerwaną obsługę, pamiętaj, aby zaktualizować cały kod klienta do używania klucza pomocniczego podczas przewracania klucza podstawowego. Unikaj zmieniania kluczy podczas wykonywania operacji.

Jak można się spodziewać, w przypadku ponownego generowania kluczy bez aktualizowania kodu klienta żądania używające starego klucza nie powiedzie się. Ponowne generowanie wszystkich nowych kluczy nie powoduje trwałej blokady usługi i nadal możesz uzyskać dostęp do usługi za pośrednictwem portalu. Po ponownej wygenerowaniu kluczy podstawowych i pomocniczych można odpowiednio zaktualizować kod klienta, aby używać nowych kluczy i operacji.

Wartości kluczy interfejsu API są generowane przez usługę. Nie można podać klucza niestandardowego dla usługi Azure AI Search do użycia. Podobnie nie ma zdefiniowanej przez użytkownika nazwy dla kluczy interfejsu API administratora. Odwołania do klucza są stałymi ciągami albo primarysecondary.

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

Wyniki powinny wyglądać podobnie do poniższych danych wyjściowych. Oba klucze są zwracane, mimo że zmieniasz tylko jeden naraz.

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

Tworzenie lub usuwanie kluczy zapytań

Polecenie New-AzSearchQueryKey służy do tworzenia kluczy interfejsu API zapytań na potrzeby dostępu tylko do odczytu z aplikacji klienckich do indeksu usługi Azure AI Search. Klucze zapytań służą do uwierzytelniania w określonym indeksie w celu pobierania wyników wyszukiwania. Klucze zapytań nie udzielają dostępu tylko do odczytu innym elementom usługi, takim jak indeks, źródło danych lub indeksator.

Nie można podać klucza do użycia przez usługę Azure AI Search. Klucze interfejsu API są generowane przez usługę.

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

Skalowanie replik i partycji

Polecenie Set-AzSearchService służy do zwiększania lub zmniejszania liczby replik i partycji w celu wyczytania rozliczanych zasobów w ramach usługi. Zwiększenie liczby replik lub partycji powoduje dodanie rachunku, który ma zarówno stałe, jak i zmienne opłaty. Jeśli potrzebujesz tymczasowej mocy obliczeniowej, możesz zwiększyć liczbę replik i partycji w celu obsługi obciążenia. Obszar monitorowania na stronie Portalu Przegląd zawiera kafelki dotyczące opóźnienia zapytań, zapytań na sekundę i ograniczania przepustowości wskazujących, czy bieżąca pojemność jest odpowiednia.

Może upłynąć trochę czasu, aby dodać lub usunąć zasoby. Korekty pojemności występują w tle, co umożliwia kontynuowanie istniejących obciążeń. Dodatkowa pojemność jest używana w przypadku żądań przychodzących, gdy tylko będzie gotowa, bez konieczności dodatkowej konfiguracji.

Usuwanie pojemności może być destrukcyjne. Zaleca się zatrzymanie wszystkich zadań indeksowania i indeksatora przed zmniejszeniem pojemności, aby uniknąć porzuconych żądań. Jeśli nie jest to możliwe, możesz rozważyć przyrostowe zmniejszenie pojemności, jednej repliki i partycji naraz, dopóki nie zostaną osiągnięte nowe poziomy docelowe.

Po przesłaniu polecenia nie ma możliwości zakończenia go w połowie. Przed zmianą liczby trzeba poczekać, aż polecenie zostanie zakończone.

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

Wyniki powinny wyglądać podobnie do poniższych danych wyjściowych.

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

Prywatne punkty końcowe zabezpieczonych zasobów, które są tworzone za pośrednictwem interfejsów API usługi Azure AI Search, są nazywane udostępnionymi zasobami łącza prywatnego. Dzieje się tak, ponieważ dostęp do zasobu jest "udostępnianie", taki jak konto magazynu zintegrowane z usługą Azure Private Link.

Jeśli używasz indeksatora do indeksowania danych w usłudze Azure AI Search, a źródło danych znajduje się w sieci prywatnej, możesz utworzyć wychodzące połączenie prywatnego punktu końcowego, aby uzyskać dostęp do danych.

Pełną listę zasobów platformy Azure, dla których można tworzyć wychodzące prywatne punkty końcowe z usługi Azure AI Search, można znaleźć tutaj wraz z powiązanymi wartościami identyfikatorów grupy.

Polecenie New-AzSearchSharedPrivateLinkResource służy do tworzenia udostępnionego zasobu łącza prywatnego. Pamiętaj, że niektóre konfiguracje mogą być wymagane dla źródła danych przed uruchomieniem tego polecenia.

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"

Polecenie Get-AzSearchSharedPrivateLinkResource umożliwia pobranie udostępnionych zasobów łącza prywatnego i wyświetlenie ich stanu.

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

Aby można było go użyć, musisz zatwierdzić połączenie za pomocą następującego polecenia.

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

Polecenie Remove-AzSearchSharedPrivateLinkResource służy do usuwania udostępnionego zasobu łącza prywatnego.

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

$job | Get-Job

Aby uzyskać szczegółowe informacje na temat konfigurowania udostępnionych zasobów łącza prywatnego, zobacz dokumentację dotyczącą nawiązywania połączeń indeksatora za pośrednictwem prywatnego punktu końcowego.

Następne kroki

Tworzenie indeksu, wykonywanie zapytań względem indeksu przy użyciu portalu, interfejsów API REST lub zestawu SDK platformy .NET.