使用 PowerShell 管理 Azure AI 搜索服务
可以在 Windows、Linux 上运行 PowerShell cmdlet 和脚本，以创建和配置 Azure AI 搜索。 Az.Search 模块扩展了 Azure PowerShell，完全可与搜索管理 REST API 搭配使用，并可执行以下任务：
偶尔，系统会询问有关任务未 在上述列表中出现的问题。
你无法以编程方式或在门户中更改服务器名称、区域或层级。 创建服务时，会分配专用资源。 因此，更改底层硬件（位置或节点类型）需要新的服务。
你无法使用工具或 API 将一个服务中的内容（例如索引）传输到另一个服务。 在服务内，以编程方式创建内容的操作是通过搜索服务 REST API 或 SDK（例如用于 .Net 的 Azure 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 -Environment AzureChinaCloud
如果你持有多个 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-chinanorth
ResourceType : Microsoft.Search/searchServices
Location : chinanorth
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-chinanorth/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-chinanorth
ResourceType : Microsoft.Search/searchServices
Location : China North
Sku : Standard
ReplicaCount : 1
PartitionCount : 1
HostingMode : Default
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-chinanorth/providers/Microsoft.Search/searchServices/my-demo-searchapp
创建或删除服务
New-AzSearchService 用于创建新的搜索服务。
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "China North" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
结果应如以下输出所示。
ResourceGroupName : demo-chinanorth
Name : my-demo-searchapp
Id : /subscriptions/<alphanumeric-subscription-ID>/demo-chinanorth/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location : China North
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 "China North" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IPRuleList $ipRules
使用系统分配的托管标识创建服务
在某些情况下，例如当使用托管标识连接到数据源时，需要启用系统分配的托管标识。 这可以通过在命令中添加 -IdentityType SystemAssigned 来完成。
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "China North" `
-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 "China North" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
创建具有专用终结点的服务
Azure AI 搜索的专用终结点允许虚拟网络上的客户端通过专用链接安全地访问搜索索引中的数据。 专用终结点将虚拟网络地址空间中的 IP 地址用于你的搜索服务。 客户端与搜索服务之间的网络流量将穿过虚拟网络以及 Microsoft Azure 主干网络上的专用链接，不会从公共 Internet 公开。 有关详细信息，请参阅为 Azure AI 搜索创建专用终结点。
下面的示例演示了如何使用专用终结点创建搜索服务。
首先，部署一个搜索服务，将 PublicNetworkAccess 设为 Disabled。
$searchService = New-AzSearchService `
-ResourceGroupName <search-service-resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "China North" `
-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 "China North" `
-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 "China North" `
-Subnet $virtualNetwork.subnets[0] `
-PrivateLinkServiceConnection $privateLinkConnection
最后，创建专用 DNS 区域。
## Create private dns zone
$zone = New-AzPrivateDnsZone `
-ResourceGroupName <private-dns-resource-group-name> `
-Name "privatelink.search.azure.cn"
## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
-ResourceGroupName <private-dns-link-resource-group-name> `
-ZoneName "privatelink.search.azure.cn" `
-Name "myLink" `
-VirtualNetworkId $virtualNetwork.Id
## Create DNS configuration
$config = New-AzPrivateDnsZoneConfig `
-Name "privatelink.search.azure.cn" `
-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 中创建专用终结点，请参阅此专用链接快速入门。
管理专用终结点连接
除了创建专用终结点连接之外，还可以 GetSet 和 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-chinanorth
Name : my-demo-searchapp
Location : China North
Sku : Standard
ReplicaCount : 6
PartitionCount : 6
HostingMode : Default
Id : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-chinanorth/providers/Microsoft.Search/searchServices/my-demo-searchapp
创建共享的专用链接资源
通过 Azure AI 搜索 API 创建的安全资源的专用终结点称为“共享的专用链接资源”。 这是因为你是在“共享”对已与 Azure 专用链接服务集成的资源（例如存储帐户）的访问权限。
如果你是使用索引器在 Azure AI 搜索中为数据编制索引，并且数据源位于专用网络上，则可以创建出站专用终结点连接来访问数据。
可在此处找到可从 Azure AI 搜索中为其创建出站专用终结点的 Azure 资源的完整列表，以及相关的“组 ID”值。
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
有关设置共享专用链接资源的完整详细信息，请参阅通过专用终结点建立索引器连接的文档。