使用 Azure CLI 管理 Azure AI 搜尋服務

發行項
04/07/2024

您可以在 Windows、macOS、Linux 或 Azure Cloud Shell 上執行 Azure CLI 命令和腳本，以建立及設定 Azure AI 搜尋。

列出訂用帳戶中的搜尋服務
傳回服務資訊
建立或刪除服務
使用私人端點建立服務
重新產生系統管理 API 金鑰
建立或刪除查詢 API 金鑰
使用複本和分割區相應增加或減少
建立共用私人鏈接資源

有時候，系統會詢問有關不在上述清單上之工作的問題。

您無法以程式設計方式或在入口網站中變更伺服器名稱、區域或階層。建立服務時，會配置專用資源。因此，變更基礎硬體（位置或節點類型）需要新的服務。

您無法使用工具或 API，將內容，例如索引從某個服務傳輸到另一個服務。在服務中，以程式設計方式建立內容是透過 Search Service REST API 或 SDK，例如 Azure SDK for .NET。雖然內容移轉沒有專用命令，但您可以撰寫腳本來呼叫 REST API 或用戶端連結庫，以在新的服務上建立和載入索引。

預覽系統管理功能通常無法在 az search 模組中使用。如果您想要使用預覽功能，請使用管理 REST API 和預覽 API 版本。

必要條件

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

Azure CLI 版本會列在 GitHub 上。

az search module 會將 Azure CLI 與完整同位擴充至穩定版本的搜尋管理 REST API。

列出訂用帳戶中的服務

下列命令來自 az resource，傳回訂用帳戶中已布建的現有資源和服務的相關信息。如果您不知道已經建立多少個搜尋服務，這些命令會傳回該資訊，以節省您前往入口網站的行程。

第一個命令會傳回所有搜尋服務。

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

從服務清單中，傳回特定資源的相關信息。

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

列出所有 az search 命令

您可以從 CLI 中檢視 az search 中可用的子群組和命令資訊。或者，您可以檢閱檔。

若要檢視中 az search可用的子群組，請執行下列命令。

az search --help

回應看起來應該類似下列輸出。

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"

在每個子群組內，有多個命令可供使用。您可以執行下列程式代碼列來查看子群組的可用命令 service 。

az search service --help

您也可以查看特定命令可用的自變數。

az search service create --help

取得搜尋服務資訊

如果您知道包含搜尋服務的資源群組，請執行 az search service show 以傳回服務定義，包括名稱、區域、層和複本和數據分割計數。針對此命令，請提供包含搜尋服務的資源群組。

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

建立或刪除服務

若要建立新的搜尋服務，請使用 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

結果看起來應該類似下列輸出：

{
  "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 會移除服務及其數據。

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

使用IP規則建立服務

根據您的安全性需求，您可能想要建立已設定IP防火牆的搜尋服務。若要這樣做，請將公用IP（v4）位址或 CIDR 範圍傳遞至自變數， ip-rules 如下所示。規則應該以逗號（,）或分號（;）分隔。

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"

使用系統指派的受控識別建立服務

在某些情況下，例如使用受控識別連線至數據源時，您必須開啟系統指派的受控識別。這是藉由將新增 --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

使用私人端點建立服務

Azure AI 搜尋的私人端點可讓虛擬網路上的用戶端透過 Private Link 安全地存取搜尋索引中的數據。私人端點會針對您的搜尋服務使用虛擬網路位址空間中的IP位址。用戶端與搜尋服務之間的網路流量會透過虛擬網路和 Microsoft 骨幹網路上的私人連結周遊，從而消除來自公用因特網的風險。如需詳細資訊，請參閱建立 Azure AI 搜尋私人端點的檔。

下列範例示範如何使用私人端點建立搜尋服務。

首先，部署已設定為Disabled的搜尋服務PublicNetworkAccess。

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

接下來，建立虛擬網路和私人端點。

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

最後，建立私人 DNS 區域。

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

如需在 Azure CLI 中建立私人端點的詳細資訊，請參閱此 Private Link 快速入門。

管理私人端點連線

除了建立私人端點連線之外，您也可以 show、 update和 delete 連接。

若要擷取私人端點連線並查看其狀態，請使用 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>

若要更新連線，請使用 az search private-endpoint-connection update。下列範例會將私人端點連線設定為拒絕：

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"

若要刪除私人端點連線，請使用 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>

重新產生系統管理金鑰

若要變換管理員 API 密鑰，請使用 az search admin-key renew。每個服務都會建立兩個系統管理密鑰，以取得已驗證的存取權。每個要求都需要金鑰。這兩個系統管理密鑰在功能上都相等，授與搜尋服務的完整寫入許可權，並能夠擷取任何資訊，或建立和刪除任何物件。有兩個索引鍵可供您在取代另一個時使用。

您一次只能重新產生一個，指定為 primary 或 secondary 索引鍵。針對不間斷的服務，請記得更新所有用戶端程序代碼，以在變換主鍵時使用次要密鑰。避免在作業進行時變更金鑰。

如您所料，如果您在不更新用戶端程式代碼的情況下重新產生密鑰，則使用舊密鑰的要求將會失敗。重新產生所有新金鑰並不會永久鎖定您的服務，您仍然可以透過入口網站存取服務。重新產生主要和次要金鑰之後，您可以更新用戶端程式代碼以使用新的金鑰，而且作業將會隨之繼續。

API 金鑰的值是由服務所產生。您無法提供自訂金鑰供 Azure AI 搜尋使用。同樣地，系統管理 API 金鑰沒有使用者定義的名稱。索引鍵的參考是固定字串，可以是 primary 或 secondary。

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

結果看起來應該類似下列輸出。即使您一次只變更一個，也會傳回這兩個索引鍵。

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

建立或刪除查詢金鑰

若要建立查詢 API 金鑰，以便從用戶端應用程式存取 Azure AI 搜尋索引，請使用 az search query-key create。查詢索引鍵可用來向特定索引進行驗證，以擷取搜尋結果。查詢索引鍵不會授與服務上其他專案的唯讀存取權，例如索引、數據源或索引器。

您無法提供 Azure AI 搜尋要使用的金鑰。 API 金鑰是由服務產生。

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

調整複本和數據分割

若要增加或減少複本和分割區，請使用 az search service update。增加複本或分割區會新增至您的帳單，其中包含固定和可變費用。如果您有更多處理能力的暫時需求，您可以增加複本和分割區來處理工作負載。 [概觀入口網站] 頁面中的監視區域具有查詢延遲、每秒查詢和節流的磚，指出目前的容量是否足夠。

可能需要一段時間才能新增或移除資源。調整容量會發生在背景中，讓現有的工作負載得以繼續。當傳入要求準備就緒時，就會使用額外的容量，不需要額外的設定。

拿掉容量可能會造成干擾。建議在減少容量之前停止所有編製索引和索引器作業，以避免卸除的要求。如果這不可行，您可能會考慮以累加方式減少容量，一次減少一個復本和分割區，直到達到新的目標層級為止。

提交命令之後，就沒有辦法在中途終止命令。您必須等到命令完成，再修改計數。

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

除了更新複本和資料分割計數之外，您也可以更新 ip-rules、 public-access和 identity-type。

建立共用私人鏈接資源

透過 Azure AI 搜尋 API 建立的安全資源私人端點稱為 共用私人鏈接資源。這是因為您是「共用」資源存取權，例如已與 Azure Private Link 服務整合的記憶體帳戶。

如果您使用索引器在 Azure AI 搜尋服務中編制數據索引，而且您的數據源位於專用網，您可以建立輸出私人端點連線以連線到數據。

您可以在這裡找到您可以從 Azure AI 搜尋建立輸出私人端點的 Azure 資源完整清單，以及相關的群組識別符值。

若要建立共用的私人鏈接資源，請使用 az search shared-private-link-resource create。請記住，執行此命令之前，數據源可能需要某些設定。

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"

若要擷取共用的私人鏈接資源並檢視其狀態，請使用 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>

您必須先核准使用下列命令的連線，才能使用它。私人端點聯機的標識碼必須從子資源擷取。在此情況下，我們會從 az storage 取得連線標識碼。

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

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

若要刪除共用的私人鏈接資源，請使用 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>

如需設定共用私人鏈接資源的詳細資訊，請參閱透過私人端點建立索引器連線。

下一步

使用入口網站、REST API 或 .NET SDK 建置索引、查詢索引。