Správa Search Azure AI pomocí Azure CLI

  • Článek

Příkazy a skripty Azure CLI můžete spouštět ve Windows, macOS, Linuxu nebo v Azure Cloud Shellu a vytvářet a konfigurovat Azure AI Search.

Pomocí modulu az search proveďte následující úlohy:

V některých případech jsou otázky týkající se úkolů , které nejsou na výše uvedeném seznamu.

Název serveru, oblast nebo vrstvu nemůžete programově ani na portálu změnit. Při vytvoření služby se přidělí vyhrazené prostředky. Změna základního hardwaru (umístění nebo typu uzlu) proto vyžaduje novou službu.

Pomocí nástrojů nebo rozhraní API nemůžete přenášet obsah, jako je index, z jedné služby do jiné. Programové vytváření obsahu ve službě je prostřednictvím rozhraní REST API vyhledávací služby nebo sady SDK, jako je Sada Azure SDK pro .NET. I když neexistují žádné vyhrazené příkazy pro migraci obsahu, můžete napsat skript, který volá rozhraní REST API nebo klientskou knihovnu pro vytváření a načítání indexů v nové službě.

Funkce správy ve verzi Preview obvykle nejsou v modulu az search k dispozici. Pokud chcete použít funkci Preview, použijte rozhraní REST API pro správu a verzi rozhraní API ve verzi Preview.

Požadavky

Verze Azure CLI jsou uvedené na GitHubu.

Modul az search rozšiřuje Azure CLI o úplnou paritu na stabilní verze rozhraní REST API pro správu vyhledávání.

Výpis služeb v předplatném

Následující příkazy pocházejí z příkazu az resource a vracejí informace o existujících prostředcích a službách, které už jsou ve vašem předplatném zřízené. Pokud nevíte, kolik vyhledávacích služeb už je vytvořených, vrátí tyto příkazy tyto informace a uloží vám cestu na portál.

První příkaz vrátí všechny vyhledávací služby.

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

Ze seznamu služeb vrátíte informace o konkrétním prostředku.

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

Výpis všech příkazů az search

Informace o podskupinách a příkazech dostupných v az search můžete zobrazit z rozhraní příkazového řádku. Případně si můžete projít dokumentaci.

Pokud chcete zobrazit podskupiny dostupné v rámci az search, spusťte následující příkaz.

az search --help

Odpověď by měla vypadat podobně jako v následujícím výstupu.

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"

V rámci každé podskupiny je k dispozici více příkazů. Dostupné příkazy pro podskupinu service můžete zobrazit spuštěním následujícího řádku.

az search service --help

Můžete také zobrazit argumenty dostupné pro konkrétní příkaz.

az search service create --help

Získání informací o vyhledávací službě

Pokud znáte skupinu prostředků obsahující vaši vyhledávací službu, spusťte příkaz az search service show a vraťte definici služby, včetně názvu, oblasti, úrovně a počtu replik a oddílů. Pro tento příkaz zadejte skupinu prostředků, která obsahuje vyhledávací službu.

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

Vytvoření nebo odstranění služby

Pokud chcete vytvořit novou vyhledávací službu, použijte příkaz 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

Výsledky by měly vypadat podobně jako v následujícím výstupu:

{
  "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 odebere službu a její data.

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

Vytvoření služby s pravidly PROTOKOLU IP

V závislosti na požadavcích na zabezpečení můžete chtít vytvořit vyhledávací službu s nakonfigurovanou bránou firewall protokolu IP. Uděláte to tak, že do argumentu předáte adresy veřejné IP adresy (v4) nebo rozsahy ip-rules CIDR, jak je znázorněno níže. Pravidla by měla být oddělena čárkou (,) nebo středníkem (;).

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"

Vytvoření služby se spravovanou identitou přiřazenou systémem

V některých případech, například při použití spravované identity pro připojení ke zdroji dat, je potřeba zapnout spravovanou identitu přiřazenou systémem. To se provádí přidáním --identity-type SystemAssigned do příkazu.

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

Vytvoření služby s privátním koncovým bodem

Privátní koncové body pro Azure AI Search umožňují klientovi ve virtuální síti zabezpečený přístup k datům v indexu vyhledávání přes Private Link. Privátní koncový bod používá IP adresu z adresního prostoru virtuální sítě pro vaši vyhledávací službu. Síťový provoz mezi klientem a vyhledávací službou prochází přes virtuální síť a privátní propojení v páteřní síti Microsoftu, čímž se eliminuje vystavení z veřejného internetu. Další informace najdete v dokumentaci k vytvoření privátního koncového bodu pro Azure AI Search.

Následující příklad ukazuje, jak vytvořit vyhledávací službu s privátním koncovým bodem.

Nejprve nasaďte vyhledávací službu s nastavenou PublicNetworkAccess na Disabledhodnotu .

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

Dále vytvořte virtuální síť a privátní koncový bod.

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

Nakonec vytvořte privátní zónu DNS.

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

Další informace o vytváření privátních koncových bodů v Azure CLI najdete v tomto rychlém startu služby Private Link.

Správa připojení privátních koncových bodů

Kromě vytváření připojení privátního koncového bodu můžete také show, updatea delete připojení.

Pokud chcete načíst připojení privátního koncového bodu a zobrazit jeho stav, použijte příkaz az search private-endpoint-connection show.

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

Pokud chcete připojení aktualizovat, použijte příkaz az search private-endpoint-connection update. Následující příklad nastaví připojení privátního koncového bodu na odmítnuté:

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"

Pokud chcete odstranit připojení privátního koncového bodu, použijte příkaz az search private-endpoint-connection delete.

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

Opětovné generování klíčů správce

Pokud chcete převést klíče rozhraní API pro správu, použijte příkaz az search admin-key renew. Vytvoří se dva klíče správce s každou službou pro ověřený přístup. Klíče jsou vyžadovány v každém požadavku. Oba klíče správce jsou funkčně ekvivalentní a udělují vyhledávací službě úplný přístup k zápisu s možností načíst jakékoli informace nebo vytvořit a odstranit jakýkoli objekt. Existují dva klíče, takže můžete použít jeden a nahradit druhý.

Můžete znovu vygenerovat pouze jednu po druhé, určenou buď jako primary klíč, nebo secondary klíč. V případě nepřerušované služby nezapomeňte aktualizovat veškerý klientský kód tak, aby používal sekundární klíč při vrácení primárního klíče. Vyhýbejte se změnám klíčů během provozu.

Jak můžete očekávat, pokud klíče znovu vygenerujete bez aktualizace kódu klienta, požadavky používající starý klíč selžou. Opětovné vygenerování všech nových klíčů vás trvale nezamkne z vaší služby a stále se k této službě dostanete přes portál. Jakmile znovu vygenerujete primární a sekundární klíče, můžete aktualizovat klientský kód tak, aby používal nové klíče a operace se odpovídajícím způsobem obnoví.

Služba generuje hodnoty klíčů rozhraní API. Nemůžete zadat vlastní klíč, který by služba Azure AI Search mohla použít. Podobně neexistuje žádný uživatelsky definovaný název pro klíče rozhraní API pro správu. Odkazy na klíč jsou pevné řetězce, buď primary nebo secondary.

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

Výsledky by měly vypadat podobně jako v následujícím výstupu. Oba klíče se vrátí, i když změníte jenom jeden po druhém.

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

Vytvoření nebo odstranění klíčů dotazu

Pokud chcete vytvořit klíče rozhraní API pro dotazování pro přístup z klientských aplikací do indexu Azure AI Search, použijte příkaz az search query-key create. Klíče dotazů se používají k ověření v určitém indexu pro načítání výsledků hledání. Klíče dotazů neudělují přístup jen pro čtení jiným položkám ve službě, jako je index, zdroj dat nebo indexer.

Nemůžete zadat klíč, který by služba Azure AI Search mohla použít. Služba generuje klíče rozhraní API.

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

Škálování replik a oddílů

Pokud chcete zvýšit nebo snížit počet replik a oddílů, použijte příkaz az search service update. Zvýšení replik nebo oddílů se přidá na fakturu, která má pevné i proměnlivé poplatky. Pokud potřebujete dočasný výkon pro zpracování, můžete zvýšit počet replik a oddílů pro zpracování úlohy. Oblast monitorování na stránce portálu Přehled obsahuje dlaždice týkající se latence dotazů, dotazů za sekundu a omezování, které indikuje, jestli je aktuální kapacita adekvátní.

Přidání nebo odebrání prostředků může chvíli trvat. Úpravy kapacity probíhají na pozadí, což umožňuje pokračovat v existujících úlohách. Kapacita navíc se používá pro příchozí požadavky hned, jak je připravená, a nevyžaduje se žádná další konfigurace.

Odebrání kapacity může být rušivé. Před snížením kapacity se doporučuje zastavit všechny úlohy indexování a indexeru, abyste se vyhnuli vyřazeným požadavkům. Pokud to není možné, můžete zvážit postupné snížení kapacity, jedné repliky a oddílu najednou, dokud nedosáhnete nových cílových úrovní.

Jakmile příkaz odešlete, neexistuje způsob, jak ho ukončit uprostřed cesty. Před revizí počtů musíte počkat na dokončení příkazu.

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

Kromě aktualizace počtu replik a oddílů můžete také aktualizovat ip-rules, public-accessa identity-type.

Privátní koncové body zabezpečených prostředků vytvořených prostřednictvím rozhraní API služby Azure AI Search se označují jako sdílené prostředky privátního propojení. Důvodem je to, že sdílíte přístup k prostředku, jako je například účet úložiště, který je integrovaný se službou Azure Private Link.

Pokud k indexování dat ve službě Azure AI Search používáte indexer a váš zdroj dat je v privátní síti, můžete vytvořit odchozí připojení privátního koncového bodu pro přístup k datům.

Úplný seznam prostředků Azure, pro které můžete vytvořit odchozí privátní koncové body ze služby Azure AI Search, najdete tady společně se souvisejícími hodnotami ID skupiny.

Pokud chcete vytvořit sdílený prostředek privátního propojení, použijte příkaz az search shared-private-link-resource create. Mějte na paměti, že před spuštěním tohoto příkazu může být pro zdroj dat vyžadována určitá konfigurace.

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"

Pokud chcete načíst prostředky sdíleného privátního propojení a zobrazit jejich stav, použijte příkaz az search shared-private-link-resource list.

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

Abyste ho mohli použít, musíte připojení schválit pomocí následujícího příkazu. ID připojení privátního koncového bodu musí být načteno z podřízeného prostředku. V tomto případě získáme ID připojení z az storage.

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

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

Pokud chcete odstranit prostředek sdíleného privátního propojení, použijte příkaz az search shared-private-link-resource delete.

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

Další informace o nastavení prostředků sdíleného privátního propojení najdete v tématu Vytváření připojení indexeru prostřednictvím privátního koncového bodu.

Další kroky

Vytvořte index, dotazujte se na index pomocí portálu, rozhraní REST API nebo sady .NET SDK.