Verwalten Ihres Azure KI Search-Diensts mit der Azure CLI

  • Artikel

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

Verwenden Sie 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.

Voraussetzungen

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Azure CLI-Versionen werden auf GitHub aufgeführt.

Das az search-Modul erweitert die Azure CLI um vollständige Parität mit den stabilen Versionen für die Suchverwaltungs-REST-APIs.

Auflisten von Diensten in einem Abonnement

Die folgenden Befehle stammen von az resource 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.

az resource list --resource-type Microsoft.Search/searchServices --output table

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

az resource list --name <search-service-name>

Auflisten aller Befehle für „az search“

Sie können Informationen zu den in az search verfügbaren Untergruppen und Befehlen innerhalb der CLI anzeigen. Alternativ können Sie sich die Dokumentation ansehen.

Führen Sie den folgenden Befehl aus, um die in az search verfügbaren Untergruppen anzuzeigen:

az search --help

Die Antwort sollte in etwa wie die folgende Ausgabe aussehen:

Group
    az search : Manage Azure Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

In den einzelnen Untergruppen sind jeweils mehrere Befehle verfügbar. Die verfügbaren Befehle für die Untergruppe service können durch Ausführen der folgenden Zeile angezeigt werden:

az search service --help

Sie können auch die für einen bestimmten Befehl verfügbaren Argumente anzeigen:

az search service create --help

Abrufen von Suchdienstinformationen

Wenn Sie die Ressourcengruppe kennen, die Ihren Suchdienst enthält, können Sie az search service show ausführen, um die Dienstdefinition mit Name, Region und Tarif sowie mit der Anzahl von Replikaten und Partitionen zurückzugeben. Geben Sie für diesen Befehl die Ressourcengruppe an, die den Suchdienst enthält.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

Erstellen oder Löschen eines Diensts

Verwenden Sie zum Erstellen eines neuen Suchdiensts den Befehl az search service create:

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

Die Ergebnisse sollten in etwa wie in der folgenden Ausgabe aussehen:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete entfernt den Dienst und löscht die dazugehörigen Daten.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

Erstellen eines Diensts mit IP-Regeln

Je nach Ihren Sicherheitsanforderungen kann es ratsam sein, einen Suchdienst mit einer konfigurierten IP-Firewall zu erstellen. Übergeben Sie hierzu die öffentlichen IP-Adressen (v4) oder die CIDR-Bereiche wie unten gezeigt an das Argument ip-rules. Regeln müssen durch ein Komma (,) oder Semikolon (;) getrennt werden.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

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 --identity-type SystemAssigned hinzu.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

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. Ausführlichere Informationen finden Sie in der Dokumentation zum Erstellen eines privaten Endpunkts für die Azure KI-Suche.

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.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

Erstellen Sie als Nächstes ein virtuelles Netzwerk und den privaten Endpunkt.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>

Erstellen Sie abschließend eine private DNS-Zone.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

Weitere Informationen zum Erstellen von privaten Endpunkten in Azure CLI finden Sie in diesem Schnellstart für 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 show, update und delete für die Verbindung durchführen.

Verwenden Sie az search private-endpoint-connection show, um eine Verbindung mit einem privaten Endpunkt abzurufen und den Status anzuzeigen.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Zum Aktualisieren der Verbindung können Sie az search private-endpoint-connection update verwenden. Im folgenden Beispiel wird eine Verbindung mit dem privaten Endpunkt auf „Verweigert“ (Rejected) festgelegt:

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

Zum Löschen der Verbindung mit dem privaten Endpunkt können Sie az search private-endpoint-connection delete verwenden.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Erneutes Generieren von Administratorschlüsseln

Verwenden Sie az search admin-key renew, um ein Rollover für administratorbezogene API-Schlüssel durchzuführen. 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 die Azure KI-Suche 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.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

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

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

Erstellen oder Löschen von Abfrageschlüsseln

Mit az search query-key create können abfragebezogene API-Schlüssel für schreibgeschützten Zugriff von Client-Apps auf einen Azure KI Search-Index erstellt werden. 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 die Azure KI-Suche bereitstellen. API-Schlüssel werden vom Dienst generiert.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

Skalieren von Replikaten und Partitionen

Zum Erhöhen oder Verringern der Anzahl von Replikaten und Partitionen kann az search service update verwendet werden. 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.

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

Neben der Replikat- und Partitionsanzahl können Sie auch ip-rules, public-access und identity-type aktualisieren.

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.

Verwenden Sie az search shared-private-link-resource create, 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.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve"

Verwenden Sie az search shared-private-link-resource list, um die gemeinsam genutzten Private Link-Ressourcen abzurufen und den Status anzuzeigen.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Sie müssen die Verbindung mit dem folgenden Befehl genehmigen, bevor sie verwendet werden kann. Die ID der Verbindung mit dem privaten Endpunkt muss von der untergeordneten Ressource aus abgerufen werden. In diesem Fall wird die Verbindungs-ID über „az storage“ abgerufen.

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

Verwenden Sie az search shared-private-link-resource delete, um die gemeinsam genutzte Private Link-Ressource zu löschen.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

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.