Hantera din Azure AI-tjänsten Search med Azure CLI

  • Artikel

Du kan köra Azure CLI-kommandon och skript i Windows, macOS, Linux eller Azure Cloud Shell för att skapa och konfigurera Azure AI Search.

Använd az search-modulen för att utföra följande uppgifter:

Ibland kan frågor ställas om uppgifter som inte finns med i listan ovan.

Du kan inte ändra ett servernamn, en region eller en nivå programmatiskt eller i portalen. Dedikerade resurser allokeras när du skapar en tjänst. Därför krävs en ny tjänst för att ändra den underliggande maskinvaran (plats eller nodtyp).

Du kan inte använda verktyg eller API:er för att överföra innehåll, till exempel ett index, från en tjänst till en annan. Inom en tjänst är programmatiskt skapande av innehåll via Search Service REST API eller ett SDK, till exempel Azure SDK för .NET. Det finns inga dedikerade kommandon för innehållsmigrering, men du kan skriva skript som anropar REST API eller ett klientbibliotek för att skapa och läsa in index på en ny tjänst.

Administrationsfunktioner för förhandsversioner är vanligtvis inte tillgängliga i az search-modulen . Om du vill använda en förhandsversionsfunktion använder du REST API för hantering och en förhandsversion av API:et.

Förutsättningar

Azure CLI-versioner visas på GitHub.

Az Search-modulen utökar Azure CLI med fullständig paritet till de stabila versionerna av REST-API:erna för sökhantering.

Visa en lista över tjänster i en prenumeration

Följande kommandon kommer från az resource och returnerar information om befintliga resurser och tjänster som redan har etablerats i din prenumeration. Om du inte vet hur många söktjänster som redan har skapats returnerar dessa kommandon den informationen, vilket sparar en resa till portalen.

Det första kommandot returnerar alla söktjänster.

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

I listan över tjänster returnerar du information om en specifik resurs.

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

Visa en lista över alla az search-kommandon

Du kan visa information om de undergrupper och kommandon som är tillgängliga i az search inifrån CLI. Du kan också granska dokumentationen.

Om du vill visa de undergrupper som är tillgängliga i az searchkör du följande kommando.

az search --help

Svaret bör se ut ungefär som följande utdata.

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"

I varje undergrupp finns flera kommandon tillgängliga. Du kan se de tillgängliga kommandona för service undergruppen genom att köra följande rad.

az search service --help

Du kan också se de argument som är tillgängliga för ett visst kommando.

az search service create --help

Hämta söktjänstinformation

Om du känner till resursgruppen som innehåller söktjänsten kör du az search service show för att returnera tjänstdefinitionen, inklusive namn, region, nivå och antal repliker och partitioner. För det här kommandot anger du den resursgrupp som innehåller söktjänsten.

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

Skapa eller ta bort en tjänst

Om du vill skapa en ny söktjänst använder du kommandot 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

Resultaten bör se ut ungefär som följande utdata:

{
  "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 tar bort tjänsten och dess data.

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

Skapa en tjänst med IP-regler

Beroende på dina säkerhetskrav kanske du vill skapa en söktjänst med en konfigurerad IP-brandvägg. För att göra det skickar du de offentliga IP-adresserna (v4) eller CIDR-intervallen ip-rules till argumentet enligt nedan. Regler bör avgränsas med kommatecken (,) eller semikolon (;).

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"

Skapa en tjänst med en systemtilldelad hanterad identitet

I vissa fall, till exempel när du använder hanterad identitet för att ansluta till en datakälla, måste du aktivera systemtilldelad hanterad identitet. Detta görs genom att lägga --identity-type SystemAssigned till i kommandot.

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

Skapa en tjänst med en privat slutpunkt

Privata slutpunkter för Azure AI Search gör det möjligt för en klient i ett virtuellt nätverk att på ett säkert sätt komma åt data i ett sökindex via en Private Link. Den privata slutpunkten använder en IP-adress från det virtuella nätverkets adressutrymme för söktjänsten. Nätverkstrafiken mellan klienten och söktjänsten passerar över det virtuella nätverket och en privat länk i Microsofts stamnätverk, vilket eliminerar exponeringen från det offentliga Internet. Mer information finns i dokumentationen om hur du skapar en privat slutpunkt för Azure AI Search.

I följande exempel visas hur du skapar en söktjänst med en privat slutpunkt.

Distribuera först en söktjänst med PublicNetworkAccess inställd på 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

Skapa sedan ett virtuellt nätverk och den privata slutpunkten.

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

Skapa slutligen en privat DNS-zon.

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

Mer information om hur du skapar privata slutpunkter i Azure CLI finns i den här snabbstarten för Private Link.

Hantera privata slutpunktsanslutningar

Förutom att skapa en privat slutpunktsanslutning kan du även show, updateoch delete anslutningen.

Om du vill hämta en privat slutpunktsanslutning och se dess status använder du 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>

Om du vill uppdatera anslutningen använder du az search private-endpoint-connection update. I följande exempel anges en privat slutpunktsanslutning till avvisad:

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"

Om du vill ta bort den privata slutpunktsanslutningen använder du 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>

Återskapa administratörsnycklar

Om du vill rulla över administratörs-API-nycklar använder du az search admin-key renew. Två administratörsnycklar skapas med varje tjänst för autentiserad åtkomst. Nycklar krävs för varje begäran. Båda administratörsnycklarna är funktionellt likvärdiga, vilket ger fullständig skrivåtkomst till en söktjänst med möjlighet att hämta all information eller skapa och ta bort alla objekt. Det finns två nycklar så att du kan använda en när du ersätter den andra.

Du kan bara återskapa en i taget, som anges som antingen primary eller-nyckeln secondary . Kom ihåg att uppdatera all klientkod för att använda en sekundär nyckel när du rullar över den primära nyckeln för oavbruten tjänst. Undvik att ändra nycklarna under drift.

Om du återskapar nycklar utan att uppdatera klientkoden misslyckas begäranden som använder den gamla nyckeln som du kan förvänta dig. Att återskapa alla nya nycklar låser dig inte permanent från tjänsten och du kan fortfarande komma åt tjänsten via portalen. När du har återskapat primära och sekundära nycklar kan du uppdatera klientkoden för att använda de nya nycklarna och åtgärderna återupptas i enlighet med detta.

Värden för API-nycklarna genereras av tjänsten. Du kan inte ange en anpassad nyckel för Azure AI Search att använda. På samma sätt finns det inget användardefinierat namn för administratörs-API-nycklar. Referenser till nyckeln är fasta strängar, antingen primary eller secondary.

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

Resultaten bör se ut ungefär som följande utdata. Båda nycklarna returneras även om du bara ändrar en i taget.

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

Skapa eller ta bort frågenycklar

Om du vill skapa fråge-API-nycklar för skrivskyddad åtkomst från klientappar till ett Azure AI Search-index använder du az search query-key create. Frågenycklar används för att autentisera till ett specifikt index för att hämta sökresultat. Frågenycklar ger inte skrivskyddad åtkomst till andra objekt i tjänsten, till exempel index, datakälla eller indexerare.

Du kan inte ange en nyckel som Azure AI Search kan använda. API-nycklar genereras av tjänsten.

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

Skala repliker och partitioner

Om du vill öka eller minska repliker och partitioner använder du az search service update. Att öka repliker eller partitioner lägger till din faktura, som har både fasta och variabla avgifter. Om du har ett tillfälligt behov av mer bearbetningskraft kan du öka repliker och partitioner för att hantera arbetsbelastningen. Övervakningsområdet på översiktsportalsidan innehåller paneler om frågesvarstid, frågor per sekund och begränsning som anger om den aktuella kapaciteten är tillräcklig.

Det kan ta en stund att lägga till eller ta bort resursen. Kapacitetsjusteringar sker i bakgrunden, vilket gör att befintliga arbetsbelastningar kan fortsätta. Extra kapacitet används för inkommande begäranden så snart den är klar, utan att någon extra konfiguration krävs.

Det kan vara störande att ta bort kapacitet. Vi rekommenderar att du stoppar alla indexerings- och indexeringsjobb innan du minskar kapaciteten för att undvika borttagna begäranden. Om det inte är möjligt kan du överväga att minska kapaciteten stegvis, en replik och partition i taget tills de nya målnivåerna har nåtts.

När du har skickat kommandot går det inte att avsluta det halvvägs. Du måste vänta tills kommandot är klart innan du ändrar antalet.

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

Förutom att uppdatera antalet repliker och partitioner kan du även uppdatera ip-rules, public-accessoch identity-type.

Privata slutpunkter för skyddade resurser som skapas via Api:er för Azure AI Search kallas delade privata länkresurser. Det beror på att du "delar" åtkomsten till en resurs, till exempel ett lagringskonto som har integrerats med Azure Private Link-tjänsten.

Om du använder en indexerare för att indexera data i Azure AI Search och din datakälla finns i ett privat nätverk kan du skapa en utgående privat slutpunktsanslutning för att nå data.

En fullständig lista över De Azure-resurser som du kan skapa utgående privata slutpunkter för från Azure AI Search finns här tillsammans med relaterade grupp-ID-värden .

Om du vill skapa resursen för delad privat länk använder du az search shared-private-link-resource create. Tänk på att viss konfiguration kan krävas för datakällan innan du kör det här kommandot.

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"

Om du vill hämta resurserna för den delade privata länken och visa deras status använder du 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>

Du måste godkänna anslutningen med följande kommando innan den kan användas. ID:t för den privata slutpunktsanslutningen måste hämtas från den underordnade resursen. I det här fallet hämtar vi anslutnings-ID:t från az storage.

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

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

Om du vill ta bort resursen för delad privat länk använder du 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>

Mer information om hur du konfigurerar delade privata länkresurser finns i Skapa indexerareanslutningar via en privat slutpunkt.

Nästa steg

Skapa ett index, fråga ett index med hjälp av portalen, REST-API:er eller .NET SDK.