使用 PowerShell 管理 Azure AI 搜尋服務
您可以在 Windows、Linux 或 Azure Cloud Shell 中執行 PowerShell Cmdlet 和指令碼，以建立及設定 Azure AI 搜尋服務。
使用 Az.Search 模組來執行下列工作：
有時候我們會收到與「沒有」列於上方的工作相關的問題。
您無法以程式設計的方式，或透過入口網站變更伺服器名稱、區域或階層。 建立服務時，會配置專用資源。 因此，若要變更基礎硬體 (位置或節點類型)，您必須建立新服務。
您無法使用工具或 API 在服務之間傳輸索引之類的內容。 若要在服務中以程式設計的方式建立內容，必須透過搜尋服務 REST API (機器翻譯) 或 Azure SDK for .NET (英文) 之類的 SDK。 雖然內容移轉沒有專用命令，您仍可撰寫呼叫 REST API 或用戶端程式庫的指令碼，在新服務上建立並載入索引。
Az.Search 模組通常無法使用預覽管理功能。 如果您想使用預覽功能，請使用管理 REST API 及預覽的 API 版本。
Az.Search 模組會延伸 Azure PowerShell，以具有搜尋管理 REST API 穩定版本的完整同位。
檢查版本和負載模組
本文提供互動式範例，且需要較高的權限。 請務必具備本地 PowerShell 和 Azure PowerShell (Az 模組)。
PowerShell 版本檢查
如果您還沒有，請安裝 PowerShell 的最新版本。
$PSVersionTable.PSVersion
載入 Azure PowerShell
如果您不確定 Az 是否已安裝，請執行下列命令進行驗證。
Get-InstalledModule -Name Az
部分系統不會自動載入模組。 如果您執行上一個命令時顯示錯誤，請嘗試載入模組。如果失敗，請回顧 Azure PowerShell 安裝指示，檢查是否有遺漏的步驟。
Import-Module -Name Az
用瀏覽器登入權杖連線至 Azure
您可以使用入口網站登入認證連線至 PowerShell 中的訂閱。 或者，您可以非互動的方式使用服務主體進行驗證。
Connect-AzAccount
如果您有多個 Azure 訂閱，請設定您的 Azure 訂閱。 如果想查看目前的訂用帳戶清單，請執行這個命令。
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
若要指定訂用帳戶，請執行下列命令。 在下列範例中，訂用帳戶的名稱為 ContosoSubscription。
Select-AzSubscription -SubscriptionName ContosoSubscription
列出訂閱中的服務
下列命令來自 Az.Resources，會傳回已佈建在您訂閱中現有資源和服務的資訊。 如果您不知道已建立的搜尋服務有幾項，這些命令會傳回該項資訊，您無需親自前往入口網站查看。
第一個命令會傳回所有搜尋服務。
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
系統會從服務清單中傳回特定資源的資訊。
Get-AzResource -ResourceName <service-name>
結果看起來應該會類似以下的輸出。
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : westus
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
匯入 Az.Search
來自 Az.Search 的命令在載入模組以前無法使用。
Install-Module -Name Az.Search -Scope CurrentUser
列出所有 Az.Search 命令
驗證時，系統會傳回模組中提供的命令清單。
Get-Command -Module Az.Search
結果看起來應該會類似以下的輸出。
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet Get-AzSearchAdminKeyPair 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateLinkResource 0.10.0 Az.Search
Cmdlet Get-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Get-AzSearchService 0.10.0 Az.Search
Cmdlet Get-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet New-AzSearchAdminKey 0.10.0 Az.Search
Cmdlet New-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet New-AzSearchService 0.10.0 Az.Search
Cmdlet New-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Remove-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Remove-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Remove-AzSearchService 0.10.0 Az.Search
Cmdlet Remove-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Set-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Set-AzSearchService 0.10.0 Az.Search
Cmdlet Set-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
如果您有該套件的較舊版本，請更新模組以取得最新功能。
Update-Module -Name Az.Search
取得搜尋服務資訊
匯入 Az.Search 且了解包含搜尋服務的資源群組之後，請執行 Get-AzSearchService 來傳回服務定義，包括名稱、區域、階層、複本和分割區計數。 針對這項命令，請提供包含搜尋服務的資源群組。
Get-AzSearchService -ResourceGroupName <resource-group-name>
結果看起來應該會類似以下的輸出。
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : West US
Sku : Standard
ReplicaCount : 1
PartitionCount : 1
HostingMode : Default
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
建立或刪除服務
New-AzSearchService 會用來建立新的搜尋服務。
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
結果看起來應該會類似以下的輸出。
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Id : /subscriptions/<alphanumeric-subscription-ID>/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 3
PartitionCount : 3
HostingMode : Default
Tags
Remove-AzSearchService 用來刪除服務及其資料。
Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>
系統會要求您確認動作。
Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
使用 IP 規則建立服務
視您的安全性需求而定，不妨建立具備已設定 IP 防火牆的搜尋服務。 為此，請先定義 IP 規則，然後將其傳遞至 IPRuleList 參數，如下所示。
$ipRules = @([pscustomobject]@{Value="55.5.63.73"},
[pscustomobject]@{Value="52.228.215.197"},
[pscustomobject]@{Value="101.37.221.205"})
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IPRuleList $ipRules
使用系統指派的受控識別建立服務
在部分情況下，例如使用受控識別連線至資料來源時，您必須啟用系統指派的受控識別。 做法是將 -IdentityType SystemAssigned 新增至命令。
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IdentityType SystemAssigned
建立 S3HD 服務
建立 S3HD 服務時，會使用 -Sku 與 -HostingMode 的組合。 將 -Sku 設為 Standard3，並將 -HostingMode 設為 HighDensity。
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard3 `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
使用私人端點建立服務
適用於 Azure AI 搜尋服務的私人端點可讓虛擬網路上的用戶端透過私人連結，安全存取搜尋索引中的資料。 私人端點會使用來自虛擬網路位址空間的 IP 位址來執行搜尋服務。 用戶端和搜尋服務之間的網路流量會經過 Microsoft 骨幹網路上的虛擬網路和私人連結，避免暴露在公開網際網路中。 如需詳細資訊，請參閱為 Azure AI 搜尋服務建立私人端點。
下列範例顯示如何用私人端點建立搜尋服務。
首先，部署將 PublicNetworkAccess 設定為 Disabled 的搜尋服務。
$searchService = New-AzSearchService `
-ResourceGroupName <search-service-resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 1 `
-HostingMode Default `
-PublicNetworkAccess Disabled
接著建立虛擬網路、私人網路連線以及私人端點。
# Create the subnet
$subnetConfig = New-AzVirtualNetworkSubnetConfig `
-Name <subnet-name> `
-AddressPrefix 10.1.0.0/24 `
-PrivateEndpointNetworkPolicies Disabled
# Create the virtual network
$virtualNetwork = New-AzVirtualNetwork `
-ResourceGroupName <vm-resource-group-name> `
-Location "West US" `
-Name <virtual-network-name> `
-AddressPrefix 10.1.0.0/16 `
-Subnet $subnetConfig
# Create the private network connection
$privateLinkConnection = New-AzPrivateLinkServiceConnection `
-Name <private-link-name> `
-PrivateLinkServiceId $searchService.Id `
-GroupId searchService
# Create the private endpoint
$privateEndpoint = New-AzPrivateEndpoint `
-Name <private-endpoint-name> `
-ResourceGroupName <private-endpoint-resource-group-name> `
-Location "West US" `
-Subnet $virtualNetwork.subnets[0] `
-PrivateLinkServiceConnection $privateLinkConnection
最後，建立私人 DNS 區域。
## Create private dns zone
$zone = New-AzPrivateDnsZone `
-ResourceGroupName <private-dns-resource-group-name> `
-Name "privatelink.search.windows.net"
## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
-ResourceGroupName <private-dns-link-resource-group-name> `
-ZoneName "privatelink.search.windows.net" `
-Name "myLink" `
-VirtualNetworkId $virtualNetwork.Id
## Create DNS configuration
$config = New-AzPrivateDnsZoneConfig `
-Name "privatelink.search.windows.net" `
-PrivateDnsZoneId $zone.ResourceId
## Create DNS zone group
New-AzPrivateDnsZoneGroup `
-ResourceGroupName <private-dns-zone-resource-group-name> `
-PrivateEndpointName <private-endpoint-name> `
-Name 'myZoneGroup' `
-PrivateDnsZoneConfig $config
如需深入了解如何在 PowerShell 中建立私人端點，請參閱此私人連結快速入門。
管理私人端點連線
除了建立私人端點連線，您還可以 Get、Set 並 Remove 連線。
Get-AzSearchPrivateEndpointConnection 是用來擷取私人端點連線並查看其狀態。
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
Set-AzSearchPrivateEndpointConnection 是用來更新連線。 下列範例將私人端點連線設定為已拒絕：
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
Remove-AzSearchPrivateEndpointConnection 是用來刪除私人端點連線。
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
重新產生系統管理金鑰
New-AzSearchAdminKey 是用來變換管理員 API 金鑰。 每項服務各會建立兩個系統管理金鑰來進行已驗證的存取。 每項要求都必須使用金鑰。 兩個系統管理金鑰具備相同的功能，都能將完整的寫入權限授與搜尋服務，且能擷取任何資訊，或者建立及刪除任何物件。 之所以產生兩個金鑰，是為了能在使用其中之一的期間更換另一個金鑰。
您一次只可重新產生一個金鑰，也就是指定為 primary 或 secondary 金鑰。 若要讓服務不受中斷，請記得更新所有用戶端程式碼，藉此在主要金鑰變換期間使用次要金鑰。 請避免於作業進行時變更金鑰。
您可能也料想得到，如果您在沒有更新用戶端程式碼的情況下重新產生金鑰，使用舊金鑰的要求就會失敗。 重新產生所有新金鑰不會讓您永遠無法使用服務，您仍可透過入口網站存取服務。 重新產生主要和次要金鑰後，您就可更新用戶端程式碼來使用新的金鑰，作業也能因此繼續進行。
API 金鑰的值由服務產生， 您無法提供自訂金鑰讓 Azure AI 搜尋服務使用。 同理，系統管理 API 金鑰也不能採用使用者定義的名稱。 金鑰的參考對象都是固定字串，不是 primary 就是 secondary。
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
結果看起來應該會類似以下的輸出。 即使您一次只變更一個金鑰，系統依然會傳回兩個金鑰。
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
建立或刪除查詢金鑰
New-AzSearchQueryKey 是用來建立查詢 API 金鑰，以便為用戶端應用程式提供 Azure AI 搜尋服務索引的唯讀存取權。 查詢金鑰是用來驗證特定索引，以便擷取搜尋結果。 查詢金鑰無法授與服務上其他項目 (例如索引、資料來源或索引子) 唯讀存取權。
您無法提供金鑰讓 Azure AI 搜尋服務使用。 API 金鑰會由服務產生。
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
調整複本和分割區
Set-AzSearchService 是用來增加或減少複本及分割區，以便重新調整服務內的可計費資源。 增加複本或分割區會提高帳單費用，包括固定和變動費用。 如果您暫時需要額外的處理能力，可增加複本和分割區來處理工作負載。 入口網站 [概觀] 頁面的監視區域有查詢延遲、每秒查詢和節流的圖格，會指出目前的容量是否足夠。
新增或移除資源處理需要一些時間來完成。 調整容量的過程會於背景進行，使現有的工作負載不受干擾。 一旦額外容量準備就緒，就會立即用於傳入的要求，無需進一步設定。
移除容量可能會造成中斷， 建議於減少容量前停下所有編製索引和索引子工作，避免要求遭到捨棄。 如果無法這麼做，建議您以漸進式方法減少容量，一次減少一個複本和分割區，直到達到新的目標層級為止。
命令一經提交，即無法中途終止。 您必須等候命令完成，才能修改計數。
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
結果看起來應該會類似以下的輸出。
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 6
PartitionCount : 6
HostingMode : Default
Id : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
建立共用私人連結資源
透過 Azure AI 搜尋服務 API 建立的受保護資源私人端點，稱為「共用私人連結資源」。 這是因為您已針對與 Azure Private Link 服務整合的資源 (例如儲存體帳戶)「共用」存取權。
如果您使用索引子來為 Azure AI 搜尋服務中的資料編製索引，且資料來源位於私人網路上，則可以建立輸出私人端點連線以觸達該資料。
有關可從 Azure AI 搜尋服務建立輸出私人端點的完整 Azure 資源清單，以及相關群組識別碼的值，請參閱此處。
New-AzSearchSharedPrivateLinkResource 是用來建立共用私人連結資源。 請記住，執行此命令前，可能須先為資料來源進行部分設定。
New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-serviceresource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId <group-id> -RequestMessage "Please approve"
Get-AzSearchSharedPrivateLinkResource 可讓您擷取共用私人連結資源並檢視其狀態。
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
您必須先使用下列命令來核准連線，之後才能使用。
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
Remove-AzSearchSharedPrivateLinkResource 是用來刪除共用私人連結資源。
$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob
$job | Get-Job
如需設定共用私人連結資源的完整詳細資料，請參閱透過私人端點建立索引子連線文件。