Delen via

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

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 de naam of regio van een service niet programmatisch of in Azure Portal wijzigen. Toegewezen resources worden toegewezen wanneer een service wordt gemaakt, dus het wijzigen van de onderliggende hardware (locatie of knooppunttype) vereist een nieuwe service.

Opmerking

De REST API's voor Search Management en Azure Portal ondersteunen het wijzigen van uw prijscategorie. Momenteel kunt u alleen schakelen tussen de niveaus Basic en Standard (S1, S2 en S3).

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, geven deze opdrachten die informatie terug, wat u een bezoek aan de Azure Portal bespaart.

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>

Lijst 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 subgroepen die beschikbaar zijn binnen az search wilt weergeven, voert u de volgende opdracht uit.

az search --help

Het antwoord moet ongeveer lijken op 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 die uw zoekservice bevat kent, voert u az search service show uit om de servicedefinitie te retourneren, inclusief naam, regio, laag, en het 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 zouden moeten lijken op de volgende output:

{
  "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 ingesteld op 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 voor meer informatie over het maken van privé-eindpunten in Azure CLI deze Quickstart voor Private Link.

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>

Een service maken met confidential computing

Confidential Computing is een optioneel rekentype voor de beveiliging van gegevens in gebruik. Wanneer deze is geconfigureerd, wordt uw zoekservice geïmplementeerd op vertrouwelijke VM's (DCasv5 of DCesv5) in plaats van op standaard-VM's. Dit rekentype kost ook een toeslag van 10% voor factureerbare lagen. Zie voor meer informatie de pagina met prijzen.

Voor dagelijks gebruik is confidential computing niet nodig. We raden dit rekentype alleen aan voor strenge wettelijke, nalevings- of beveiligingsvereisten. Zie Gebruiksvoorbeelden voor Confidential Computing voor meer informatie.

Het rekentype is vast voor de levensduur van uw zoekservice. Als u confidential computing permanent wilt configureren, stelt u de compute-type eigenschap confidential in op een nieuwe service.

az search service create \
  --name <search-service-name> \
  --resource-group <search-service-resource-group-name> \
  --location <search-service-region> \
  --sku basic \
  --compute-type confidential

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. Om een ononderbroken service te garanderen, moet u alle clientcode bijwerken om een secundaire sleutel te gebruiken bij het overschakelen 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 Azure 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 zo uitzien als de volgende uitvoer. Beide sleutels worden geretourneerd, zelfs als u er slechts één tegelijkertijd 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 voor gebruik door Azure AI Search. 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 als schaalmodellen

Als u replica's en partities wilt vergroten of verkleinen, gebruikt u az search service update. Het verhogen van replica's of partities verhoogt 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 overzichtsportaal bevat tegels die betrekking hebben op querylatentie, query's per seconde en beperkingen, 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 via Azure AI Search-API's worden gemaakt, 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 Azure Portal, REST API's of de .NET SDK.

  • Last updated on