Správa služby Azure Cognitive Search pomocí Azure CLI

Příkazy a skripty Azure CLI můžete spouštět ve Windows, macOS, Linuxu nebo v Azure Cloud Shell a vytvářet a konfigurovat Azure Cognitive Search. Modul az search rozšiřuje Azure CLI o úplnou paritu na rozhraní REST API služby Search Management a schopnost provádět následující úlohy:

Občas se můžete ptát na úkoly , které nejsou na výše uvedeném seznamu.

Název serveru, oblast nebo vrstvu nemůžete změnit programově ani na portálu. 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.

K přenosu obsahu, jako je index, z jedné služby do druhé nemůžete použít nástroje ani rozhraní API. Programové vytváření obsahu ve službě je prostřednictvím rozhraní REST API vyhledávací služby nebo sady SDK, jako je Azure SDK pro .NET. I když pro migraci obsahu neexistují žádné vyhrazené příkazy, 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 dostupné v modulu az search . Pokud chcete použít funkci Preview, použijte rozhraní REST API pro správu a verzi preview rozhraní API.

Požadavky

  • Použijte prostředí Bash v Azure Cloud Shell. Další informace najdete v tématu Rychlý start k Azure Cloud Shell – Bash. Spuštění služby Cloud Shell v novém okně

  • Pokud dáváte přednost místnímu spuštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Dockeru. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

    • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.

    • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.

    • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

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

Následující příkazy pocházejí z az resource a vracejí informace o existujících prostředcích a službách, které jsou již 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

Můžete zobrazit informace o podskupinách a příkazech dostupných v az search 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"
}

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 předáte veřejné IP adresy (v4) nebo rozsahy CIDR argumentu ip-rules , 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, budete muset 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 Cognitive Search umožňují klientovi ve virtuální síti zabezpečený přístup k datům v indexu hledá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ší podrobnosti najdete v dokumentaci k vytvoření privátního koncového bodu pro Azure Cognitive 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 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é showa updatedelete 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 show \
    --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> 

Znovu vygenerujte klíče 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, abyste mohli použít jeden, zatímco druhý nahradíte.

Můžete znovu vygenerovat pouze jeden po druhém, zadaný jako primary klíč nebo secondary klíč. Pro nepřerušenou službu nezapomeňte aktualizovat veškerý klientský kód tak, aby používal sekundární klíč při přechálení primárního klíče. Vyhněte se změně klíčů během provozu.

Jak můžete očekávat, pokud znovu vygenerujete klíče 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 prostřednictvím portálu. Jakmile znovu vygenerujete primární a sekundární klíče, můžete aktualizovat kód klienta tak, aby používal nové klíče a operace se odpovídajícím způsobem obnoví.

Hodnoty klíčů rozhraní API jsou generovány službou. Nemůžete zadat vlastní klíč, který Azure Cognitive Search 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 dotazy pro přístup jen pro čtení z klientských aplikací do indexu Azure Cognitive Search, použijte příkaz az search query-key create. Klíče dotazu slouží k ověření v určitém indexu pro účely 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ý Azure Cognitive Search použít. Klíče rozhraní API jsou generovány službou.

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 zmenšit repliky a oddíly , použijte příkaz az search service update. Zvýšení počtu replik nebo oddílů se přidá na fakturu, která má pevné i proměnlivé poplatky. Pokud máte dočasnou potřebu dalšího výpočetního výkonu, můžete zvýšit počet replik a oddílů pro zpracování úloh. 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é značí, jestli je aktuální kapacita odpovídající.

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. Další kapacita se použije pro příchozí požadavky, jakmile je připravená, bez nutnosti další konfigurace.

Odstranění kapacity může být rušivé. Pokud chcete zabránit vyřazeným požadavkům, doporučujeme zastavit všechny úlohy indexování a indexeru před snížením kapacity. 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 uprostřed ukončit. Před revizí počtu budete muset 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 aoddílůch ip-rulespublic-accessidentity-type

Privátní koncové body zabezpečených prostředků vytvořených prostřednictvím rozhraní API Azure Cognitive 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 účet úložiště, který je integrovaný se službou Azure Private Link.

Pokud k indexování dat v Azure Cognitive Search používáte indexer a 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 z Azure Cognitive Search najdete tady spolu s hodnotami SOUVISEJÍCÍCH ID skupiny.

Pokud chcete vytvořit prostředek sdíleného 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, budete muset připojení schválit pomocí následujícího příkazu. ID připojení privátního koncového bodu bude potřeba načíst 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> 

Úplné podrobnosti o nastavení sdílených prostředků privátního propojení najdete v dokumentaci k 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.