Verwalten des Azure KI Search-Diensts mit PowerShell

  • Artikel

Sie können PowerShell-Cmdlets und -Skripts unter Windows oder Linux oder in Azure Cloud Shell ausführen, um einen Azure KI Search-Dienst zu erstellen und zu konfigurieren.

Verwenden Sie das Az.Search-Modul, um die folgenden Aufgaben auszuführen:

Gelegentlich werden Fragen zu Aufgaben gestellt, die nicht in der oben stehenden Liste enthalten sind.

Servernamen, Regionen oder Ebenen können weder programmgesteuert noch im Portal geändert werden. Dedizierte Ressourcen werden beim Erstellen eines Diensts zugeordnet. Daher ist zum Ändern der zugrunde liegenden Hardware (Standort oder Knotentyp) ein neuer Dienst erforderlich.

Sie können keine Tools oder APIs zum Übertragen von Inhalten (wie z. B. Indizes) aus einem Dienst in einen anderen verwenden. Innerhalb eines Diensts erfolgt die programmgesteuerte Erstellung von Inhalten über die Suchdienst-REST-API oder ein SDK wie das Azure SDK für .NET. Es gibt zwar keine dedizierten Befehle für die Inhaltsmigration, aber Sie können ein Skript schreiben, das die REST-API oder eine Clientbibliothek aufruft, um Indizes für einen neuen Dienst zu erstellen und zu laden.

Vorschaufunktionen für die Verwaltung sind im Az.Search-Modul in der Regel nicht verfügbar. Wenn Sie eine Vorschaufunktion verwenden möchten, können Sie die Verwaltungs-REST-API und eine API-Vorschauversion verwenden.

Das Az.Search-Modul erweitert Azure PowerShell um vollständige Parität mit den stabilen Versionen für die Search Management REST APIs.

Überprüfen von Versionen und Laden von Modulen

Die Beispiele in diesem Artikel sind interaktiv und erfordern erhöhte Berechtigungen. Eine lokale PowerShell-Instanz und Azure PowerShell (das Az-Modul) sind erforderlich.

Überprüfung der PowerShell-Version

Installieren Sie die aktuelle Version von PowerShell, wenn nicht die aktuelle Version installiert ist.

$PSVersionTable.PSVersion

Laden von Azure PowerShell

Wenn Sie nicht sicher sind, ob Az installiert ist, führen Sie den folgenden Befehl als Überprüfungsschritt aus.

Get-InstalledModule -Name Az

Einige Systeme laden keine Module automatisch. Wenn Sie als Reaktion auf den vorherigen Befehl eine Fehlermeldung erhalten, versuchen Sie, das Modul zu laden. Wenn das fehlschlägt, kehren Sie zu den Installationsanweisungen für Azure PowerShell zurück, um festzustellen, ob Sie einen Schritt übersehen haben.

Import-Module -Name Az

Herstellen einer Verbindung mit Azure mit einem Browser-Anmeldetoken

Mit Ihren Anmeldeinformationen für das Portal können Sie eine Verbindung mit einem Abonnement in PowerShell herstellen. Als Alternative steht die nicht interaktive Authentifizierung mit einem Dienstprinzipal zur Verfügung.

Connect-AzAccount

Wenn Sie über mehrere Azure-Abonnements verfügen, legen Sie Ihr Azure-Abonnement fest. Führen Sie den folgenden Befehl aus, um eine Liste Ihrer aktuellen Abonnements anzuzeigen.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

Führen Sie den folgenden Befehl aus, um das Abonnement anzugeben. Im folgenden Beispiel ist der Name des Abonnements ContosoSubscription.

Select-AzSubscription -SubscriptionName ContosoSubscription

Auflisten von Diensten in einem Abonnement

Die folgenden Befehle stammen von Az.Resources und geben Informationen zu vorhandenen Ressourcen und Diensten zurück, die bereits in Ihrem Abonnement bereitgestellt sind. Wenn Sie nicht wissen, wie viele Suchdienste bereits erstellt wurden, geben die folgenden Befehle diese Information zurück und ersparen Ihnen dadurch das Aufrufen des Portals.

Der erste Befehl gibt alle Suchdienste zurück.

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

Geben Sie aus der Liste der Dienste Informationen zu einer bestimmten Ressource zurück.

Get-AzResource -ResourceName <service-name>

Die Ergebnisse sollten in etwa der folgenden Ausgabe ähneln.

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

Importieren Sie Az.Search

Befehle von Az.Search sind erst nach dem Laden des Moduls verfügbar.

Install-Module -Name Az.Search -Scope CurrentUser

Auflistung aller Az.Search Befehle

Geben Sie als Überprüfungsschritt eine Liste der im Modul bereitgestellten Befehle aus.

Get-Command -Module Az.Search

Die Ergebnisse sollten in etwa der folgenden Ausgabe ähneln.

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

Falls Sie eine ältere Version des Pakets verwenden, sollten Sie das Modul aktualisieren, um die neuesten Funktionen nutzen zu können.

Update-Module -Name Az.Search

Abrufen von Suchdienstinformationen

Nachdem Az.Search importiert wurde und Ihnen die Ressourcengruppe mit Ihrem Suchdienst bekannt ist, führen Sie Get-AzSearchService aus, um die Dienstdefinition zurückzugeben. Dazu gehören Name, Region und Tarif sowie die Anzahl von Replikaten und Partitionen. Geben Sie für diesen Befehl die Ressourcengruppe an, die den Suchdienst enthält.

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

Die Ergebnisse sollten in etwa der folgenden Ausgabe ähneln.

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

Erstellen oder Löschen eines Diensts

Mit New-AzSearchService wird ein neuer Suchdienst erstellt.

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

Die Ergebnisse sollten in etwa der folgenden Ausgabe ähneln.

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 wird verwendet, um einen Dienst und die zugehörigen Daten zu löschen.

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

Sie werden aufgefordert, die Aktion zu bestätigen.

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

Erstellen eines Diensts mit IP-Regeln

Je nach Ihren Sicherheitsanforderungen kann es ratsam sein, einen Suchdienst mit einer konfigurierten IP-Firewall zu erstellen. Definieren Sie hierfür zunächst die IP-Regeln, und übergeben Sie sie anschließend wie unten gezeigt an den Parameter IPRuleList.

$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

Erstellen eines Diensts mit einer systemseitig zugewiesenen verwalteten Identität

In einigen Fällen, z. B. beim Verwenden einer verwalteten Identität für die Verbindungsherstellung mit einer Datenquelle, müssen Sie systemseitig zugewiesene verwaltete Identitäten aktivieren. Fügen Sie dem Befehl hierfür -IdentityType SystemAssigned hinzu.

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

Erstellen eines S3HD-Diensts

Zum Erstellen eines S3HD-Diensts wird eine Kombination aus -Sku und -HostingMode verwendet. Legen Sie -Sku auf Standard3 und -HostingMode auf HighDensity fest.

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

Erstellen eines Diensts mit einem privaten Endpunkt

Private Endpunkte für Azure KI Search ermöglichen es einem Client in einem virtuellen Netzwerk, über einen privaten Link sicher auf Daten in einem Suchindex zuzugreifen. Der private Endpunkt verwendet eine IP-Adresse aus dem Adressraum des virtuellen Netzwerks für Ihren Suchdienst. Der Netzwerkdatenverkehr zwischen dem Client und dem Suchdienst wird über das virtuelle Netzwerk und eine private Verbindung im Microsoft-Backbonenetzwerk geleitet, sodass keine Offenlegung im öffentlichen Internet erfolgt. Weitere Informationen finden Sie unter Erstellen eines privaten Endpunkts für Azure KI Search.

Im folgenden Beispiel wird veranschaulicht, wie Sie einen Suchdienst mit einem privaten Endpunkt erstellen.

Stellen Sie zunächst einen Suchdienst bereit, für den PublicNetworkAccess auf Disabled festgelegt ist.

$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

Erstellen Sie als Nächstes ein virtuelles Netzwerk, eine private Netzwerkverbindung und den privaten Endpunkt.

# 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

Erstellen Sie abschließend eine private 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

Weitere Informationen zum Erstellen privater Endpunkte in PowerShell finden Sie in dieser Schnellstartanleitung zu Private Link.

Verwalten von Verbindungen mit dem privaten Endpunkt

Zusätzlich zur Erstellung einer Verbindung mit dem privaten Endpunkt können Sie auch die Vorgänge Get, Set und Remove für die Verbindung durchführen.

Get-AzSearchPrivateEndpointConnection wird verwendet, um eine Verbindung mit dem privaten Endpunkt abzurufen und den Status anzuzeigen.

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

Set-AzSearchPrivateEndpointConnection wird verwendet, um die Verbindung zu aktualisieren. Im folgenden Beispiel wird eine Verbindung mit dem privaten Endpunkt auf „Verweigert“ (Rejected) festgelegt:

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

Remove-AzSearchPrivateEndpointConnection wird verwendet, um die Verbindung mit dem privaten Endpunkt zu löschen.

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

Erneutes Generieren von Administratorschlüsseln

Mit New-AzSearchAdminKey wird ein Rollover von Administrator-API-Schlüsseln ausgeführt. Mit jedem Dienst werden zwei Administratorschlüssel für den authentifizierten Zugriff erstellt. Schlüssel sind für jede Anforderung erforderlich. Beide Administratorschlüssel sind funktionell gleichwertig und gewähren vollständigen Schreibzugriff auf einen Suchdienst mit der Möglichkeit, alle Informationen abrufen oder ein beliebiges Objekt zu erstellen und zu löschen. Es sind zwei Schlüssel vorhanden, sodass Sie den einen verwenden können, während der andere ersetzt wird.

Sie können immer nur jeweils einen Schlüssel erneut generieren, der entweder als primary- oder secondary-Schlüssel angegeben ist. Um einen ununterbrochenen Dienst zu gewährleisten, denken Sie daran, den gesamten Clientcode so zu aktualisieren, dass während des Rollovers des primären Schlüssels ein sekundärer Schlüssel verwendet wird. Vermeiden Sie das Ändern der Schlüssel, während Vorgänge ausgeführt werden.

Wenn Sie Schlüssel ohne Aktualisierung des Clientcodes erneut generieren, treten bei Anforderungen, bei denen der alte Schlüssel verwendet wird, Fehler auf. Durch das erneute Generieren aller neuen Schlüssel werden Sie nicht dauerhaft vom Dienst ausgesperrt, und Sie können weiterhin über das Portal auf den Dienst zugreifen. Nachdem Sie primäre und sekundäre Schlüssel erneut generiert haben, können Sie den Clientcode zur Verwendung der neuen Schlüssel aktualisieren, und die Vorgänge werden entsprechend fortgesetzt.

Werte für die API-Schlüssel werden vom Dienst generiert. Sie können keinen benutzerdefinierten Schlüssel für Azure KI Search bereitstellen. Ebenso ist kein benutzerdefinierter Name für Administrator-API-Schlüssel vorhanden. Verweise auf den Schlüssel sind feste Zeichenfolgen, entweder primary oder secondary.

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

Die Ergebnisse sollten in etwa der folgenden Ausgabe ähneln. Es werden beide Schlüssel zurückgegeben, obwohl Sie immer nur jeweils einen ändern.

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

Erstellen oder Löschen von Abfrageschlüsseln

Mit New-AzSearchQueryKey werden Abfrage-API-Schlüssel für den schreibgeschützten Zugriff von Client-Apps auf einen Azure KI Search-Index erstellt. Abfrageschlüssel werden zum Authentifizieren bei einem bestimmten Index für das Abrufen von Suchergebnissen verwendet. Abfrageschlüssel gewähren keinen schreibgeschützten Zugriff auf andere Elemente im Dienst, z.B. Index, Datenquelle oder Indexer.

Sie können keinen Schlüssel für Azure KI Search bereitstellen. API-Schlüssel werden vom Dienst generiert.

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

Skalieren von Replikaten und Partitionen

Mit Set-AzSearchService wird die Anzahl von Replikaten und Partitionen erhöht oder verringert, um abrechenbare Ressourcen innerhalb des Diensts anzupassen. Durch eine erhöhte Anzahl von Replikaten oder Partitionen erhöht sich auch Ihre Rechnung, die sowohl feste als auch variable Gebühren umfasst. Wenn Sie vorübergehend zusätzliche Verarbeitungsleistung benötigen, können Sie die Anzahl der Replikate und Partitionen zum Bewältigen der Workload erhöhen. Der Überwachungsbereich auf der Übersichtsseite des Portals weist Kacheln für die Abfragewartezeit, Abfragen pro Sekunde und Drosselung auf, die angeben, ob die aktuelle Kapazität ausreichend ist.

Das Hinzufügen oder Entfernen von Ressourcen kann eine Weile dauern. Anpassungen der Kapazität finden im Hintergrund statt, damit bestehende Workloads fortgesetzt werden können. Zusätzliche Kapazität wird für eingehende Anforderungen verwendet, sobald sie bereitsteht, und erfordert keine zusätzliche Konfiguration.

Das Entfernen von Kapazität kann zu einer Unterbrechung führen. Es wird empfohlen, vor dem Verringern der Kapazität alle Indizierungs- und Indexeraufträge anzuhalten, um verworfene Anforderungen zu vermeiden. Wenn das nicht möglich ist, sollten Sie die Kapazität schrittweise verringern, jeweils ein Replikat und eine Partition nach der anderen, bis das neue Zielniveau erreicht ist.

Nachdem Sie den Befehl gesendet haben, gibt es keine Möglichkeit, ihn während der Ausführung zu beenden. Sie müssen warten, bis der Befehl abgeschlossen ist, bevor Sie die jeweilige Anzahl überarbeiten können.

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

Die Ergebnisse sollten in etwa der folgenden Ausgabe ähneln.

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

Private Endpunkte von gesicherten Ressourcen, die über Azure KI Search-APIs erstellt wurden, werden als freigegebene private Link-Ressourcen bezeichnet. Der Grund: Der Zugriff auf eine Ressource (z. B. ein Speicherkonto), die in den Azure Private Link-Dienst integriert wurde, wird von Ihnen „freigegeben“.

Wenn Sie einen Indexer zum Indizieren von Daten in Azure KI Search verwenden und sich Ihre Datenquelle in einem privaten Netzwerk befindet, können Sie eine ausgehende private Endpunktverbindung erstellen, um die Daten zu erreichen.

Eine vollständige Liste der Azure-Ressourcen, für die Sie ausgehende private Endpunkte für Azure KI Search erstellen können, und die zugehörigen Werte für die Gruppen-ID finden Sie hier.

New-AzSearchSharedPrivateLinkResource wird verwendet, um die gemeinsam genutzte Private Link-Ressource zu erstellen. Beachten Sie hierbei, dass für die Datenquelle ggf. einige Konfigurationsschritte ausgeführt werden müssen, bevor dieser Befehl ausgeführt wird.

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"

Mit Get-AzSearchSharedPrivateLinkResource können Sie die gemeinsam genutzten Private Link-Ressourcen abrufen und ihren Status anzeigen.

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

Sie müssen die Verbindung mit dem folgenden Befehl genehmigen, bevor sie verwendet werden kann.

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

Remove-AzSearchSharedPrivateLinkResource wird verwendet, um die gemeinsam genutzte Private Link-Ressource zu löschen.

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

$job | Get-Job

Ausführliche Informationen zum Einrichten von gemeinsam genutzten Private Link-Ressourcen finden Sie unter Erstellen von Indexerverbindungen über einen privaten Endpunkt.

Nächste Schritte

Erstellen Sie einen Index, verwenden Sie das Portal, REST-APIs oder das .NET SDK zum Abfragen eines Index.