Hantera din Azure Cognitive Search-tjänst med Azure CLI

Du kan köra Azure CLI-kommandon och skript i Windows, macOS, Linux eller i Azure Cloud Shell för att skapa och konfigurera Azure Cognitive Search. Modulen az search utökar Azure CLI med fullständig paritet till REST-API:erna för search management och möjligheten att utföra följande uppgifter:

Ibland kan frågor ställas om aktiviteter 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. I en tjänst är programmatiskt skapande av innehåll via Search Service REST API eller ett SDK, till exempel Azure SDK för .NET. Även om det inte finns några dedikerade kommandon för innehållsmigrering kan du 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 modulen az search . Om du vill använda en förhandsgranskningsfunktion använder du REST-API:et för hantering och en förhandsversion av API:et.

Förutsättningar

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å läsa 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"

Flera kommandon är tillgängliga i varje undergrupp. 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

Resultatet bör se ut ungefär så här:

{
  "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. Det gör du genom att skicka de offentliga IP-adresserna (v4) eller CIDR-intervallen ip-rules till argumentet enligt nedan. Regler ska 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 Cognitive Search tillåta att en klient i ett virtuellt nätverk på ett säkert sätt kommer åt data i ett sökindex över en Private Link. Den privata slutpunkten använder en IP-adress från det virtuella nätverkets adressutrymme för söktjänsten. Nätverkstrafik mellan klienten och söktjänsten passerar över det virtuella nätverket och en privat länk i Microsofts stamnätverk, vilket eliminerar exponering från det offentliga Internet. Mer information finns i dokumentationen om hur du skapar en privat slutpunkt för Azure Cognitive 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 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"

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 förnya api-nycklar för administratörer 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 information eller skapa och ta bort 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 nyckeln eller 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 pågående åtgärder.

Som förväntat misslyckas begäranden som använder den gamla nyckeln om du återskapar nycklar utan att uppdatera klientkoden. Att återskapa alla nya nycklar låser inte ut dig 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 så att de nya nycklarna och åtgärderna återupptas.

Värden för API-nycklarna genereras av tjänsten. Du kan inte ange en anpassad nyckel som Azure Cognitive Search ska 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 Cognitive 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 ett index, en datakälla eller en indexerare.

Du kan inte ange en nyckel för Azure Cognitive Search att 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. Om du ökar antalet repliker eller partitioner läggs fakturan till, som har både fasta och variabla avgifter. Om du har ett tillfälligt behov av ytterligare bearbetningskraft kan du öka repliker och partitioner för att hantera arbetsbelastningen. Övervakningsområdet på översiktsportalsidan har paneler för frågesvarstid, frågor per sekund och begränsning, som anger om aktuell kapacitet är tillräcklig.

Det kan ta en stund att lägga till eller ta bort resursen. Justeringar av kapaciteten sker i bakgrunden, vilket gör att befintliga arbetsbelastningar kan fortsätta. Ytterligare kapacitet används för inkommande begäranden så snart den är klar, utan att någon ytterligare 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 avbrutna 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 finns det inget sätt att avsluta det halvvägs igenom. 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 Azure Cognitive Search API:er 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 Cognitive Search och datakällan 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 Cognitive 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 den delade privata länken 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> 

Fullständig information om hur du konfigurerar delade privata länkresurser finns i dokumentationen om hur du gör 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.