Uw Azure AI-Search-service beheren met de Azure CLI

  • Artikel

U kunt Azure CLI-opdrachten en -scripts uitvoeren op Windows, macOS, Linux of in Azure Cloud Shell om Azure AI Search te maken en configureren.

Gebruik de az search-module om de volgende taken uit te voeren:

Soms worden er vragen gesteld over taken die niet in de bovenstaande lijst staan.

U kunt een servernaam, regio of laag niet programmatisch of in de portal wijzigen. Toegewezen resources worden toegewezen zodra een service wordt gemaakt. Als zodanig vereist het wijzigen van de onderliggende hardware (locatie of knooppunttype) een nieuwe service.

U kunt geen hulpprogramma's of API's gebruiken om inhoud, zoals een index, van de ene service naar de andere over te dragen. Binnen een service is het programmatisch maken van inhoud via de REST API van Search Service of een SDK zoals Azure SDK voor .NET. Hoewel er geen speciale opdrachten zijn voor inhoudsmigratie, kunt u een script schrijven dat REST API of een clientbibliotheek aanroept om indexen voor een nieuwe service te maken en te laden.

Preview-beheerfuncties zijn doorgaans niet beschikbaar in de az search-module . Als u een preview-functie wilt gebruiken, gebruikt u de MANAGEMENT REST API en een preview-API-versie.

Vereisten

Azure CLI-versies worden vermeld op GitHub.

De az search-module breidt de Azure CLI met volledige pariteit uit naar de stabiele versies van de REST API's van Search Management.

Services in een abonnement vermelden

De volgende opdrachten zijn afkomstig van az resource en retourneren informatie over bestaande resources en services die al in uw abonnement zijn ingericht. Als u niet weet hoeveel zoekservices er al zijn gemaakt, retourneren deze opdrachten die informatie retourneren, waardoor u een reis naar de portal opslaat.

Met de eerste opdracht worden alle zoekservices geretourneerd.

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

Geef in de lijst met services informatie over een specifieke resource op.

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

Alle az search-opdrachten weergeven

U kunt informatie bekijken over de subgroepen en opdrachten die beschikbaar zijn in az search vanuit de CLI. U kunt de documentatie ook bekijken.

Als u de beschikbare subgroepen wilt az searchweergeven, voert u de volgende opdracht uit.

az search --help

Het antwoord moet er ongeveer uitzien als in de volgende uitvoer.

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"

Binnen elke subgroep zijn meerdere opdrachten beschikbaar. U kunt de beschikbare opdrachten voor de service subgroep zien door de volgende regel uit te voeren.

az search service --help

U kunt ook de argumenten zien die beschikbaar zijn voor een bepaalde opdracht.

az search service create --help

Informatie over zoekservice ophalen

Als u de resourcegroep met uw zoekservice kent, voert u az search service show uit om de servicedefinitie te retourneren, inclusief naam, regio, laag en aantal replica's en partities. Geef voor deze opdracht de resourcegroep op die de zoekservice bevat.

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

Een service maken of verwijderen

Als u een nieuwe zoekservice wilt maken, gebruikt u de opdracht 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

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer:

{
  "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 verwijdert de service en de bijbehorende gegevens.

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

Een service maken met IP-regels

Afhankelijk van uw beveiligingsvereisten wilt u mogelijk een zoekservice maken met een IP-firewall die is geconfigureerd. Hiervoor geeft u de openbare IP-adressen (v4) of CIDR-bereiken door aan het ip-rules argument, zoals hieronder wordt weergegeven. Regels moeten worden gescheiden door een komma (,) of puntkomma (;).

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"

Een service maken met een door het systeem toegewezen beheerde identiteit

In sommige gevallen, zoals wanneer u beheerde identiteit gebruikt om verbinding te maken met een gegevensbron, moet u door het systeem toegewezen beheerde identiteit inschakelen. Dit wordt gedaan door de opdracht toe te voegen --identity-type SystemAssigned .

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

Een service maken met een privé-eindpunt

Met privé-eindpunten voor Azure AI Search kan een client in een virtueel netwerk veilig toegang krijgen tot gegevens in een zoekindex via een Private Link. Het privé-eindpunt maakt gebruik van een IP-adres uit de adresruimte van het virtuele netwerk voor uw zoekservice. Netwerkverkeer tussen de client en de zoekservice loopt via het virtuele netwerk en een privékoppeling in het Microsoft backbone-netwerk, waardoor blootstelling van het openbare internet wordt geëlimineerd. Raadpleeg de documentatie over het maken van een privé-eindpunt voor Azure AI Search voor meer informatie.

In het volgende voorbeeld ziet u hoe u een zoekservice maakt met een privé-eindpunt.

Implementeer eerst een zoekservice met PublicNetworkAccess de waarde .Disabled

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

Maak vervolgens een virtueel netwerk en het privé-eindpunt.

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

Maak ten slotte een privé-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"

Zie deze quickstart voor Private Link voor meer informatie over het maken van privé-eindpunten in Azure CLI.

Privé-eindpuntverbindingen beheren

Naast het maken van een privé-eindpuntverbinding kunt u ook show, updateen delete de verbinding.

Als u een privé-eindpuntverbinding wilt ophalen en de status ervan wilt zien, gebruikt u 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>

Gebruik az search private-endpoint-connection update om de verbinding bij te werken. In het volgende voorbeeld wordt een privé-eindpuntverbinding ingesteld op geweigerd:

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"

Als u de privé-eindpuntverbinding wilt verwijderen, gebruikt u 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>

Beheerderssleutels opnieuw genereren

Gebruik az search admin-key renew om de API-sleutels voor beheerders uit te rollen. Er worden twee beheerderssleutels gemaakt met elke service voor geverifieerde toegang. Sleutels zijn vereist voor elke aanvraag. Beide beheerderssleutels zijn functioneel gelijkwaardig, waarbij volledige schrijftoegang tot een zoekservice wordt verleend met de mogelijkheid om informatie op te halen of een object te maken en te verwijderen. Er bestaan twee sleutels, zodat u er een kunt gebruiken terwijl u de andere vervangt.

U kunt slechts één voor één opnieuw genereren, opgegeven als de primary of secondary sleutel. Voor ononderbroken service moet u alle clientcode bijwerken om een secundaire sleutel te gebruiken tijdens het rollen van de primaire sleutel. Vermijd het wijzigen van de sleutels terwijl bewerkingen actief zijn.

Zoals u zou verwachten, mislukken aanvragen met behulp van de oude sleutel als u sleutels opnieuw genereert zonder clientcode bij te werken. Door alle nieuwe sleutels opnieuw te genereren, wordt uw service niet permanent vergrendeld en hebt u nog steeds toegang tot de service via de portal. Nadat u primaire en secundaire sleutels opnieuw hebt gegenereerd, kunt u clientcode bijwerken om de nieuwe sleutels en bewerkingen dienovereenkomstig te gebruiken.

Waarden voor de API-sleutels worden gegenereerd door de service. U kunt geen aangepaste sleutel opgeven die Azure AI Search kan gebruiken. Op dezelfde manier is er geen door de gebruiker gedefinieerde naam voor beheerders-API-sleutels. Verwijzingen naar de sleutel zijn vaste tekenreeksen, ofwel primarysecondary.

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

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer. Beide sleutels worden geretourneerd, zelfs als u slechts één voor één wijzigt.

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

Querysleutels maken of verwijderen

Als u query-API-sleutels wilt maken voor alleen-lezentoegang vanuit client-apps naar een Azure AI Search-index, gebruikt u az search query-key create. Querysleutels worden gebruikt om te verifiëren bij een specifieke index voor het ophalen van zoekresultaten. Querysleutels verlenen geen alleen-lezentoegang tot andere items in de service, zoals een index, gegevensbron of indexeerfunctie.

U kunt geen sleutel opgeven die Azure AI Search kan gebruiken. API-sleutels worden gegenereerd door de service.

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

Replica's en partities schalen

Als u replica's en partities wilt vergroten of verkleinen, gebruikt u az search service update. Het verhogen van replica's of partities wordt toegevoegd aan uw factuur, met zowel vaste als variabele kosten. Als u tijdelijk meer verwerkingskracht nodig hebt, kunt u replica's en partities verhogen om de werkbelasting te verwerken. Het bewakingsgebied op de pagina Overzichtsportal bevat tegels over querylatentie, query's per seconde en beperking, waarmee wordt aangegeven of de huidige capaciteit voldoende is.

Het kan even duren voordat u bronnen toevoegt of verwijdert. Aanpassingen aan de capaciteit vinden op de achtergrond plaats, zodat bestaande workloads kunnen worden voortgezet. Extra capaciteit wordt gebruikt voor binnenkomende aanvragen zodra deze gereed is, zonder dat er extra configuratie is vereist.

Het verwijderen van capaciteit kan verstorend zijn. Het wordt aanbevolen om alle indexerings- en indexeertaken te stoppen voordat u de capaciteit verlaagt om verwijderde aanvragen te voorkomen. Als dat niet haalbaar is, kunt u overwegen om de capaciteit incrementeel te verminderen, één replica en partitie tegelijk, totdat uw nieuwe doelniveaus zijn bereikt.

Zodra u de opdracht hebt verzonden, kunt u deze niet halverwege beëindigen. U moet wachten totdat de opdracht is voltooid voordat de tellingen worden herzien.

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

Naast het bijwerken van replica- en partitieaantallen, kunt u ook bijwerken ip-rules, public-accessen identity-type.

Privé-eindpunten van beveiligde resources die worden gemaakt via Azure AI Search-API's, worden gedeelde private link-resources genoemd. Dit komt doordat u toegang tot een resource deelt, zoals een opslagaccount dat is geïntegreerd met de Azure Private Link-service.

Als u een indexeerfunctie gebruikt om gegevens te indexeren in Azure AI Search en uw gegevensbron zich in een privénetwerk bevindt, kunt u een uitgaande privé-eindpuntverbinding maken om de gegevens te bereiken.

Hier vindt u een volledige lijst met de Azure-resources waarvoor u uitgaande privé-eindpunten kunt maken vanuit Azure AI Search, samen met de gerelateerde groeps-id-waarden.

Als u de gedeelde private link-resource wilt maken, gebruikt u az search shared-private-link-resource create. Houd er rekening mee dat sommige configuraties mogelijk vereist zijn voor de gegevensbron voordat u deze opdracht uitvoert.

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"

Gebruik az search shared-private-link-resource list om de gedeelde private link-resources op te halen en hun status weer te geven.

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

U moet de verbinding met de volgende opdracht goedkeuren voordat deze kan worden gebruikt. De id van de privé-eindpuntverbinding moet worden opgehaald uit de onderliggende resource. In dit geval halen we de verbindings-id op uit az storage.

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

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

Als u de gedeelde private link-resource wilt verwijderen, gebruikt u 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>

Zie indexeerfunctieverbindingen maken via een privé-eindpunt voor meer informatie over het instellen van gedeelde private link-resources.

Volgende stappen

Bouw een index, voer een query uit op een index met behulp van de portal, REST API's of de .NET SDK.