使用 Azure CLI 管理 Azure AI 搜尋服務
您可以在 Windows、macOS、Linux 或 Azure Cloud Shell 中執行 Azure CLI 命令和指令碼，以建立並設定 Azure AI 搜尋服務。
使用 az search module 執行下列工作：
有時候我們會收到與「沒有」列於上方的工作相關的問題。
您無法以程式設計方式或在 Azure 入口網站 中變更伺服器名稱、區域或階層。 建立服務時，會配置專用資源。 因此，若要變更基礎硬體 (位置或節點類型)，您必須建立新服務。
您無法使用工具或 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 (機器翻譯)，會傳回已佈建在您訂閱中的現有資源和服務的資訊。 如果您不知道已經建立多少個搜尋服務，這些命令會傳回該資訊，並儲存您前往 Azure 入口網站。
第一個命令會傳回所有搜尋服務。
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 金鑰。 若要讓服務不受中斷，請記得更新所有用戶端程式碼，藉此在主要金鑰變換期間使用次要金鑰。 請避免於作業進行時變更金鑰。
您可能也料想得到，如果您在沒有更新用戶端程式碼的情況下重新產生金鑰，使用舊金鑰的要求就會失敗。 重新產生所有新金鑰並不會永久鎖定您的服務，您仍然可以透過 Azure 入口網站 存取服務。 重新產生主要和次要金鑰後，您就可更新用戶端程式碼來使用新的金鑰，作業也能因此繼續進行。
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>
如需設定共用私人連結資源的詳細資料，請參閱透過私人端點建立索引子連線。