使用 PowerShell 管理 Azure AI 搜尋服務
您可以在 Windows、Linux 或 Azure Cloud Shell 上執行 PowerShell Cmdlet 和腳本,以建立及設定 Azure AI 搜尋。
使用 Az.Search 模組來執行下列工作:
有時候,系統會詢問有關不在上述清單上之工作的問題。
您無法以程式設計方式或在入口網站中變更伺服器名稱、區域或階層。 建立服務時,會配置專用資源。 因此,變更基礎硬體(位置或節點類型)需要新的服務。
您無法使用工具或 API,將內容,例如索引從某個服務傳輸到另一個服務。 在服務中,以程式設計方式建立內容是透過 Search Service REST API 或 SDK,例如 Azure SDK for .NET。 雖然內容移轉沒有專用命令,但您可以撰寫腳本來呼叫 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
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 服務,則會使用 和 的組合。-HostingMode
-Sku
設定為 Standard3
,並將 -HostingMode
設定-Sku
為 HighDensity
。
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard3 `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
使用私人端點建立服務
Azure AI 搜尋的私人端點可讓虛擬網路上的用戶端透過 Private Link 安全地存取搜尋索引中的數據。 私人端點會針對您的搜尋服務使用虛擬網路位址空間中的IP位址。 用戶端與搜尋服務之間的網路流量會透過虛擬網路和 Microsoft 骨幹網路上的私人連結周遊,從而消除來自公用因特網的風險。 如需詳細資訊,請參閱 建立 Azure AI 搜尋的私人端點。
下列範例示範如何使用私人端點建立搜尋服務。
首先,部署已設定為Disabled
的搜尋服務PublicNetworkAccess
。
$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中建立私人端點的詳細資訊,請參閱此 Private Link 快速入門。
管理私人端點連線
除了建立私人端點連線之外,您也可以 Get
、 Set
和 Remove
連接。
Get-AzSearchPrivateEndpoint 連線 ion 可用來擷取私人端點連線,並查看其狀態。
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
Set-AzSearchPrivateEndpoint 連線 ion 可用來更新連線。 下列範例會將私人端點連線設定為拒絕:
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
Remove-AzSearchPrivateEndpoint 連線 ion 可用來刪除私人端點連線。
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
重新產生系統管理金鑰
New-AzSearch 管理員 Key 可用來變換管理員 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
如需設定共用私人鏈接資源的完整詳細數據,請參閱透過私人端點建立索引器連線的檔。