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

發行項
09/04/2024

您可以在 Windows、macOS、Linux 或 Azure Cloud Shell 中執行 Azure CLI 命令和指令碼，以建立並設定 Azure AI 搜尋服務。

列出訂用帳戶中的搜尋服務
傳回服務資訊
建立或刪除服務
使用私人端點建立服務
重新產生管理 API 金鑰
建立或刪除查詢 API 金鑰
使用複本和分割區擴大或縮小
建立共用私人連結資源

有時候我們會收到與「沒有」列於上方的工作相關的問題。

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

您無法使用工具或 API 在服務之間傳輸索引之類的內容。若要在服務中以程式設計的方式建立內容，必須透過搜尋服務 REST API (機器翻譯) 或 Azure SDK for .NET (英文) 之類的 SDK。雖然內容移轉沒有專用命令，您仍可撰寫呼叫 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 模組會擴充 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 搜尋服務的私人端點可讓虛擬網路上的用戶端透過私人連結，安全存取搜尋索引中的資料。私人端點會使用來自虛擬網路位址空間的 IP 位址來執行搜尋服務。用戶端和搜尋服務之間的網路流量會經過 Microsoft 骨幹網路上的虛擬網路和私人連結，避免暴露在公開網際網路中。如需詳細資訊，請參閱說明如何為 Azure AI 搜尋服務建立私人端點的文件。

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

首先，部署將 PublicNetworkAccess 設定為 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

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

# 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 中建立私人端點，請參閱私人連結快速入門。

管理私人端點連線

除了建立私人端點連線，您還可以 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 建置索引 (機器翻譯) 或查詢索引 (機器翻譯)。

共用方式為