Azure AI-Search szolgáltatás kezelése az Azure CLI-vel

  • Cikk

Az Azure AI Search létrehozásához és konfigurálásához Azure CLI-parancsokat és szkripteket futtathat Windowson, macOS-en, Linuxon vagy az Azure Cloud Shellben.

Az az search modullal hajtsa végre a következő feladatokat:

Időnként a fenti listán nem szereplő feladatokkal kapcsolatos kérdéseket is feltenek.

A kiszolgáló nevét, régióját vagy rétegét programozott módon vagy a portálon nem módosíthatja. Egy szolgáltatás létrehozásakor a rendszer dedikált erőforrásokat foglal le. Ezért a mögöttes hardver (hely vagy csomóponttípus) módosítása új szolgáltatást igényel.

Az eszközök és API-k nem használhatók tartalom( például index) átvitelére egyik szolgáltatásból a másikba. A szolgáltatáson belül a tartalom programozott létrehozása a Search Service REST API-val vagy egy SDK-val történik, például az Azure SDK for .NET-en keresztül. Bár nincsenek dedikált parancsok a tartalommigráláshoz, írhat olyan szkriptet, amely meghívja a REST API-t vagy egy ügyféltárat indexek új szolgáltatáson való létrehozásához és betöltéséhez.

Az előzetes verziójú felügyeleti funkciók általában nem érhetők el az az keresési modulban. Ha előzetes verziójú funkciót szeretne használni, használja a Felügyeleti REST API-t és az előzetes verziójú API-t.

Előfeltételek

Az Azure CLI-verziók a GitHubon jelennek meg.

Az az search modul teljes paritásossággal kiterjeszti az Azure CLI-t a Search Management REST API-k stabil verzióira.

Szolgáltatások listázása előfizetésben

Az alábbi parancsok az az erőforrásból származnak, és információkat adnak vissza az előfizetésben már kiépített meglévő erőforrásokról és szolgáltatásokról. Ha nem tudja, hogy hány keresési szolgáltatás van már létrehozva, ezek a parancsok visszaadják ezeket az információkat, így a portálra való utazást mentik.

Az első parancs az összes keresési szolgáltatást visszaadja.

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

A szolgáltatások listájából egy adott erőforrás adatait adja vissza.

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

Az összes keresési parancs listázása

Az az searchben elérhető alcsoportokra és parancsokra vonatkozó információkat a parancssori felületről tekintheti meg. Másik lehetőségként áttekintheti a dokumentációt.

Az elérhető az searchalcsoportok megtekintéséhez futtassa a következő parancsot.

az search --help

A válasznak az alábbi kimenethez hasonlóan kell kinéznie.

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"

Minden alcsoporton belül több parancs érhető el. Az alcsoporthoz elérhető parancsokat az service alábbi sor futtatásával tekintheti meg.

az search service --help

Egy adott parancshoz elérhető argumentumokat is megtekintheti.

az search service create --help

Keresési szolgáltatás adatainak lekérése

Ha ismeri a keresési szolgáltatást tartalmazó erőforráscsoportot, futtassa az az search service show parancsot a szolgáltatásdefiníció visszaadásához, beleértve a nevet, a régiót, a réteget, valamint a replika és a partíciók számát. Ehhez a parancshoz adja meg a keresési szolgáltatást tartalmazó erőforráscsoportot.

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

Szolgáltatás létrehozása vagy törlése

Új keresési szolgáltatás létrehozásához használja az az search service create parancsot.

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

Az eredményeknek az alábbi kimenethez hasonlóan kell kinéznie:

{
  "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 eltávolítja a szolgáltatást és annak adatait.

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

Szolgáltatás létrehozása IP-szabályokkal

A biztonsági követelményektől függően előfordulhat, hogy egy konfigurált IP-tűzfallal rendelkező keresőszolgáltatást szeretne létrehozni. Ehhez adja át a nyilvános IP-címeket (v4) vagy CIDR-tartományokat az argumentumnak az ip-rules alább látható módon. A szabályokat vesszővel () vagy pontosvesszővel (,;) kell elválasztani.

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"

Szolgáltatás létrehozása rendszer által hozzárendelt felügyelt identitással

Bizonyos esetekben, például amikor felügyelt identitással csatlakozik egy adatforráshoz, be kell kapcsolnia a rendszer által hozzárendelt felügyelt identitást. Ez úgy történik, hogy hozzáadja --identity-type SystemAssigned a parancsot.

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

Szolgáltatás létrehozása privát végponttal

Az Azure AI Search privát végpontjai lehetővé teszik, hogy egy virtuális hálózaton lévő ügyfél biztonságosan hozzáférjen a keresési indexben lévő adatokhoz privát kapcsolaton keresztül. A privát végpont a keresési szolgáltatás virtuális hálózati címteréből származó IP-címet használ. Az ügyfél és a keresési szolgáltatás közötti hálózati forgalom a virtuális hálózaton keresztül halad át, a Microsoft gerinchálózatán pedig egy privát kapcsolaton keresztül, kiküszöbölve a nyilvános internetről való kitettséget. További információkért tekintse meg az Azure AI Search privát végpontjának létrehozásáról szóló dokumentációt.

Az alábbi példa bemutatja, hogyan hozhat létre keresési szolgáltatást privát végponttal.

Először helyezzen üzembe egy keresési szolgáltatást a következő beállítással PublicNetworkAccessDisabled: .

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

Ezután hozzon létre egy virtuális hálózatot és a privát végpontot.

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

Végül hozzon létre egy privát DNS-zónát.

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

A privát végpontok Azure CLI-ben való létrehozásával kapcsolatos további információkért tekintse meg ezt a Privát kapcsolat rövid útmutatót.

Privátvégpont-kapcsolatok kezelése

A privát végpontkapcsolat létrehozása mellett a kapcsolatot és delete a kapcsolatot is showupdatehasználhatja.

A privát végpontkapcsolat lekéréséhez és állapotának megtekintéséhez használja az az search private-endpoint-connection show parancsot.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

A kapcsolat frissítéséhez használja az az search private-endpoint-connection update parancsot. Az alábbi példa egy privát végpontkapcsolat elutasítását állítja be:

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"

A privát végpont kapcsolatának törléséhez használja az az search private-endpoint-connection delete parancsot.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Rendszergazdai kulcsok újragenerálása

A rendszergazdai API-kulcsok átgördítéséhez használja az az search admin-key renew parancsot. Két rendszergazdai kulcs jön létre minden szolgáltatással a hitelesített hozzáféréshez. Minden kéréshez kulcsokra van szükség. Mindkét rendszergazdai kulcs funkcionálisan egyenértékű, így teljes írási hozzáférést biztosít egy keresési szolgáltatáshoz, amely bármilyen információt lekérhet, vagy bármilyen objektumot létrehozhat és törölhet. Két kulcs létezik, így az egyiket a másik cseréjekor használhatja.

Egyszerre csak egyet lehet újragenerálni, vagy kulcsként primarysecondary megadva. A zavartalan szolgáltatás érdekében ne felejtse el frissíteni az összes ügyfélkódot úgy, hogy egy másodlagos kulcsot használjon az elsődleges kulcs átgördülése közben. Ne módosítsa a kulcsokat a repülés közben.

Ahogy várható volt, ha az ügyfélkód frissítése nélkül hozza létre újra a kulcsokat, a régi kulcsot használó kérések sikertelenek lesznek. Az összes új kulcs újragenerálása nem zárja ki véglegesen a szolgáltatásból, és továbbra is elérheti a szolgáltatást a portálon keresztül. Az elsődleges és másodlagos kulcsok újragenerálása után frissítheti az ügyfélkódot az új kulcsok használatára, és a műveletek ennek megfelelően folytatódnak.

Az API-kulcsok értékeit a szolgáltatás hozza létre. Nem adhat meg egyéni kulcsot az Azure AI Search használatához. Hasonlóképpen, a rendszergazdai API-kulcsoknak nincs felhasználó által definiált neve. A kulcsra mutató hivatkozások rögzített sztringek vagy primarysecondary.

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

Az eredményeknek az alábbi kimenethez hasonlóan kell kinéznie. A rendszer mindkét kulcsot visszaadja, annak ellenére, hogy egyszerre csak egyet módosít.

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

Lekérdezési kulcsok létrehozása vagy törlése

Ha lekérdezési API-kulcsokat szeretne létrehozni az ügyfélalkalmazásokból egy Azure AI Search-indexhez való írásvédett hozzáféréshez, használja az az search query-key create parancsot. A lekérdezési kulcsok egy adott index hitelesítésére szolgálnak a keresési eredmények lekéréséhez. A lekérdezési kulcsok nem biztosítanak írásvédett hozzáférést a szolgáltatás egyéb elemeihez, például indexhez, adatforráshoz vagy indexelőhöz.

Nem adhat meg kulcsot az Azure AI Search használatához. Az API-kulcsokat a szolgáltatás hozza létre.

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

Replikák és partíciók méretezése

A replikák és partíciók növeléséhez vagy csökkentéséhez használja az az search service update-et. A replikák vagy partíciók növelése hozzáadja a számlához, amely rögzített és változó díjakkal is rendelkezik. Ha ideiglenesen több feldolgozási teljesítményre van szüksége, növelheti a replikákat és a partíciókat a számítási feladat kezeléséhez. Az Áttekintés portál oldalának figyelési területe csempékkel rendelkezik a lekérdezések késéséről, a másodpercenkénti lekérdezésekről és a szabályozásról, ami azt jelzi, hogy az aktuális kapacitás megfelelő-e.

Eltarthat egy ideig az újbóli beszerzés hozzáadása vagy eltávolítása. A kapacitás módosítása a háttérben történik, ami lehetővé teszi a meglévő számítási feladatok folytatását. A bejövő kérésekhez a rendszer azonnal extra kapacitást használ, és nincs szükség további konfigurációra.

A kapacitás eltávolítása zavaró lehet. Javasoljuk, hogy a kapacitás csökkentése előtt állítsa le az összes indexelő és indexelő feladatot az elvetett kérelmek elkerülése érdekében. Ha ez nem lehetséges, érdemes lehet fokozatosan csökkenteni a kapacitást, egyszerre egy replikát és partíciót, amíg el nem éri az új célszinteket.

A parancs elküldése után nem lehet félúton leállni. A szám módosítása előtt meg kell várnia, amíg a parancs befejeződik.

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

A replikák és a partíciók számának frissítése mellett frissítheti ip-rulesis az , public-accessés identity-type.

Az Azure AI Search API-kkal létrehozott biztonságos erőforrások privát végpontjait megosztott privát kapcsolati erőforrásoknak nevezzük. Ennek az az oka, hogy "megosztja" az erőforráshoz való hozzáférést, például egy tárfiókot, amely integrálva van az Azure Private Link szolgáltatással.

Ha indexelővel indexeli az adatokat az Azure AI Searchben, és az adatforrás egy magánhálózaton található, létrehozhat egy kimenő privát végpontkapcsolatot az adatok eléréséhez.

Itt található az Azure-erőforrások teljes listája, amelyhez kimenő privát végpontokat hozhat létre az Azure AI Searchből a kapcsolódó csoportazonosító értékekkel együtt.

A megosztott privát kapcsolat erőforrásának létrehozásához használja az az search shared-private-link-resource create parancsot. Ne feledje, hogy a parancs futtatása előtt szükség lehet némi konfigurációra az adatforráshoz.

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"

A megosztott privát kapcsolat erőforrásainak lekéréséhez és állapotuk megtekintéséhez használja az az search shared-private-link-resource listát.

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

Használat előtt jóvá kell hagynia a kapcsolatot a következő paranccsal. A magánvégpont-kapcsolat azonosítóját le kell kérni a gyermekerőforrásból. Ebben az esetben lekérjük a kapcsolatazonosítót az az storage-ból.

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

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

A megosztott privát kapcsolat erőforrásának törléséhez használja az az search shared-private-link-resource delete parancsot.

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

A megosztott privát kapcsolat erőforrásainak beállításával kapcsolatos további információkért tekintse meg az indexelő kapcsolatok privát végponton keresztüli létrehozását.

Következő lépések

Index létrehozása, index lekérdezése a portál, a REST API-k vagy a .NET SDK használatával.