使用 PowerShell 管理 Azure 认知搜索服务Manage your Azure Cognitive Search service with PowerShell

可以在 Windows、Linux 上运行 PowerShell cmdlet 和脚本,以创建和配置 Azure 认知搜索。You can run PowerShell cmdlets and scripts on Windows, Linux to create and configure Azure Cognitive Search. Az.Search 模块扩展了 Azure PowerShell,完全可与搜索管理 REST API 搭配使用,并可执行以下任务:The Az.Search module extends Azure PowerShell with full parity to the Search Management REST APIs and the ability to perform the following tasks:

偶尔,系统会询问有关任务未 在上述列表中出现的问题。Occasionally, questions are asked about tasks not on the above list. 目前,不能使用 Az.Search 模块或管理 REST API 来更改服务器名称、区域或层。Currently, you cannot use either the Az.Search module or the management REST API to change a server name, region, or tier. 创建服务时,会分配专用资源。Dedicated resources are allocated when a service is created. 因此,更改底层硬件(位置或节点类型)需要新的服务。As such, changing the underlying hardware (location or node type) requires a new service. 类似地,没有任何工具或 API 可将一个服务中的内容(例如索引)传输到另一个服务。Similarly, there are no tools or APIs for transferring content, such as an index, from one service to another.

在服务中,内容创建和管理通过搜索服务 REST API.NET SDK 完成。Within a service, content creation and management is through Search Service REST API or .NET SDK. 尽管没有专用的 PowerShell 命令可用于内容,但可以编写 PowerShell 脚本来调用 REST 或 .NET API 以创建并加载索引。While there are no dedicated PowerShell commands for content, you can write PowerShell script that calls REST or .NET APIs to create and load indexes.

检查版本并加载模块Check versions and load modules

本文中的示例是交互式,需要提升的权限。The examples in this article are interactive and require elevated permissions. 必须安装 Azure PowerShell(Az 模块)。Azure PowerShell (the Az module) must be installed. 有关详细信息,请参阅安装 Azure PowerShellFor more information, see Install Azure PowerShell.

PowerShell 版本检查(5.1 或更高版本)PowerShell version check (5.1 or later)

本地 PowerShell 必须是在任何受支持操作系统上运行的 5.1 或更高版本。Local PowerShell must be 5.1 or later, on any supported operating system.

$PSVersionTable.PSVersion

加载 Azure PowerShellLoad Azure PowerShell

如果你不确定是否已安装 Az,请运行以下命令作为验证步骤。If you aren't sure whether Az is installed, run the following command as a verification step.

Get-InstalledModule -Name Az

某些系统不会自动加载模块。Some systems do not auto-load modules. 如果运行上述命令时出错,请尝试加载该模块,如果失败,请重新查看安装说明,以检查是否遗漏了某个步骤。If you get an error on the previous command, try loading the module, and if that fails, go back to the installation instructions to see if you missed a step.

Import-Module -Name Az

使用浏览器登录令牌连接到 AzureConnect to Azure with a browser sign-in token

可以在 PowerShell 中使用门户登录凭据连接到订阅。You can use your portal sign-in credentials to connect to a subscription in PowerShell. 或者,可以使用服务主体以非交互方式进行身份验证Alternatively you can authenticate non-interactively with a service principal.

Connect-AzAccount -EnvironmentName AzureChinaCloud

如果你持有多个 Azure 订阅,请设置 Azure 订阅。If you hold multiple Azure subscriptions, set your Azure subscription. 若要查看当前订阅的列表,请运行以下命令。To see a list of your current subscriptions, run this command.

Get-AzSubscription | sort SubscriptionName | Select SubscriptionName

若要指定订阅,请运行以下命令。To specify the subscription, run the following command. 在以下示例中,订阅名为 ContosoSubscriptionIn the following example, the subscription name is ContosoSubscription.

Select-AzSubscription -SubscriptionName ContosoSubscription

列出订阅中的服务List services in a subscription

以下命令摘自 Az.Resources,它会返回有关订阅中已预配的现有资源和服务的信息。The following commands are from Az.Resources, returning information about existing resources and services already provisioned in your subscription. 如果你不知道已经创建了多少个搜索服务,则这些命令会返回该信息,省得要在门户中查找。If you don't know how many search services are already created, these commands return that information, saving you a trip to the portal.

第一个命令返回所有搜索服务。The first command returns all search services.

Get-AzResource -ResourceType Microsoft.Search/searchServices | ft

在服务列表中返回有关特定资源的信息。From the list of services, return information about a specific resource.

Get-AzResource -ResourceName <service-name>

结果应如以下输出所示。Results should look similar to the following output.

Name              : my-demo-searchapp
ResourceGroupName : demo-chinaeast2
ResourceType      : Microsoft.Search/searchServices
Location          : chinaeast2
ResourceId        : /subscriptions/<alpha-numeric-subscription-ID>/resourceGroups/demo-chinaeast2/providers/Microsoft.Search/searchServices/my-demo-searchapp

导入 Az.SearchImport Az.Search

Az.Search 中的命令只有在加载该模块之后才可用。Commands from Az.Search are not available until you load the module.

Install-Module -Name Az.Search

列出所有 Az.Search 命令List all Az.Search commands

作为验证步骤,返回模块中提供的命令列表。As a verification step, return a list of commands provided in the module.

Get-Command -Module Az.Search

结果应如以下输出所示。Results should look similar to the following output.

CommandType     Name                                Version    Source
-----------     ----                                -------    ------
Cmdlet          Get-AzSearchAdminKeyPair            0.7.1      Az.Search
Cmdlet          Get-AzSearchQueryKey                0.7.1      Az.Search
Cmdlet          Get-AzSearchService                 0.7.1      Az.Search
Cmdlet          New-AzSearchAdminKey                0.7.1      Az.Search
Cmdlet          New-AzSearchQueryKey                0.7.1      Az.Search
Cmdlet          New-AzSearchService                 0.7.1      Az.Search
Cmdlet          Remove-AzSearchQueryKey             0.7.1      Az.Search
Cmdlet          Remove-AzSearchService              0.7.1      Az.Search
Cmdlet          Set-AzSearchService                 0.7.1      Az.Search

获取搜索服务信息Get search service information

导入 Az.Search 之后,如果你知道哪个资源组包含你的搜索服务,请运行 Get-AzSearchService 返回服务定义,包括名称、区域、层级、副本计数和分区计数。After Az.Search is imported and you know the resource group containing your search service, run Get-AzSearchService to return the service definition, including name, region, tier, and replica and partition counts.

Get-AzSearchService -ResourceGroupName <resource-group-name>

结果应如以下输出所示。Results should look similar to the following output.

Name              : my-demo-searchapp
ResourceGroupName : demo-chinaeast2
ResourceType      : Microsoft.Search/searchServices
Location          : China East 2
Sku               : Standard
ReplicaCount      : 1
PartitionCount    : 1
HostingMode       : Default
ResourceId        : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-chinaeast2/providers/Microsoft.Search/searchServices/my-demo-searchapp

创建或删除服务Create or delete a service

New-AzSearchService 用于创建新的搜索服务New-AzSearchService is used to create a new search service.

New-AzSearchService -ResourceGroupName "demo-chinaeast2" -Name "my-demo-searchapp" -Sku "Standard" -Location "China East 2" -PartitionCount 3 -ReplicaCount 3

结果应如以下输出所示。Results should look similar to the following output.

ResourceGroupName : demo-chinaeast2
Name              : my-demo-searchapp
Id                : /subscriptions/<alphanumeric-subscription-ID>/demo-chinaeast2/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location          : China East 2
Sku               : Standard
ReplicaCount      : 3
PartitionCount    : 3
HostingMode       : Default
Tags

重新生成管理员密钥Regenerate admin keys

New-AzSearchAdminKey 用于滚动更新管理 API 密钥New-AzSearchAdminKey is used to roll over admin API keys. 两个管理密钥是使用每个服务创建的,用于进行身份验证访问。Two admin keys are created with each service for authenticated access. 需要在每个请求中提供密钥。Keys are required on every request. 这两个管理密钥在功能上是等效的,授予对搜索服务的完全写入访问权限,并可以检索任何信息,或创建和删除任何对象。Both admin keys are functionally equivalent, granting full write access to a search service with the ability to retrieve any information, or create and delete any object. 这两个密钥可以换用。Two keys exist so that you can use one while replacing the other.

一次只能重新生成其中的一个密钥(指定为 primarysecondary 密钥)。You can only regenerate one at a time, specified as either the primary or secondary key. 为避免服务中断,在滚动更新主密钥时,请记得将所有客户端代码更新为使用辅助密钥。For uninterrupted service, remember to update all client code to use a secondary key while rolling over the primary key. 请避免在操作是正在进行时更改密钥。Avoid changing the keys while operations are in flight.

如果在不更新客户端代码的情况下重新生成密钥,使用旧密钥的请求预期将会失败。As you might expect, if you regenerate keys without updating client code, requests using the old key will fail. 重新生成所有新密钥不会永久性地将你锁定在服务之外,你仍可以通过门户访问服务。Regenerating all new keys does not permanently lock you out of your service, and you can still access the service through the portal. 重新生成主密钥和辅助密钥后,可将客户端代码更新为使用新密钥,而操作也会相应地恢复。After you regenerate primary and secondary keys, you can update client code to use the new keys and operations will resume accordingly.

API 密钥的值由服务生成。Values for the API keys are generated by the service. 无法提供自定义密钥供 Azure 认知搜索使用。You cannot provide a custom key for Azure Cognitive Search to use. 同样,管理 API 密钥没有用户定义的名称。Similarly, there is no user-defined name for admin API-keys. 对密钥的引用是固定的字符串:primarysecondaryReferences to the key are fixed strings, either primary or secondary.

New-AzSearchAdminKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name> -KeyKind Primary

结果应如以下输出所示。Results should look similar to the following output. 即使每次只更改一个,也会同时返回两个密钥。Both keys are returned even though you only change one at a time.

Primary                    Secondary
-------                    ---------
<alphanumeric-guid>        <alphanumeric-guid>  

创建或删除查询密钥Create or delete query keys

使用 New-AzSearchQueryKey 创建查询 API 密钥,用于从客户端应用对 Azure 认知搜索索引进行只读访问。New-AzSearchQueryKey is used to create query API keys for read-only access from client apps to an Azure Cognitive Search index. 查询密钥用于对特定的索引进行身份验证,以检索搜索结果。Query keys are used to authenticate to a specific index for the purpose of retrieving search results. 查询密钥不授予对服务中其他项(例如索引、数据源或索引器)的只读访问权限。Query keys do not grant read-only access to other items on the service, such as an index, data source, or indexer.

无法提供密钥供 Azure 认知搜索使用。You cannot provide a key for Azure Cognitive Search to use. API 密钥由服务生成。API keys are generated by the service.

New-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name> -Name <query-key-name> 

缩放副本和分区Scale replicas and partitions

Set-AzSearchService 用于增加或减少副本与分区,以调整服务中的可计费资源。Set-AzSearchService is used to increase or decrease replicas and partitions to readjust billable resources within your service. 增加副本或分区会增大费用,两者都提供固定和可变的费率。Increasing replicas or partitions adds to your bill, which has both fixed and variable charges. 如果你暂时需要更大的处理能力,可以增加副本和分区来处理工作负荷。If you have a temporary need for additional processing power, you can increase replicas and partitions to handle the workload. “概述”门户页中的监视区域提供有关查询延迟、每秒查询数和限制的磁贴,指示当前容量是否足够。The monitoring area in the Overview portal page has tiles on query latency, queries per second, and throttling, indicating whether current capacity is adequate.

添加或删除资源可能需要一段时间。It can take a while to add or remove resourcing. 容量调整在后台发生,使现有工作负荷能够继续运行。Adjustments to capacity occur in the background, allowing existing workloads to continue. 附加容量准备就绪后,将立即用于处理传入的请求,无需进行额外的配置。Additional capacity is used for incoming requests as soon as it's ready, with no additional configuration required.

删除容量可能会造成中断。Removing capacity can be disruptive. 建议在减少容量之前先停止所有索引和索引器作业,以免请求遭到丢弃。Stopping all indexing and indexer jobs prior to reducing capacity is recommended to avoid dropped requests. 如果无法做到这一点,可以考虑以增量方式减少容量(每次删除一个副本和分区),直至达到新的目标级别。If that isn't feasible, you might consider reducing capacity incrementally, one replica and partition at a time, until your new target levels are reached.

提交命令后,没有任何办法可以中途终止该命令。Once you submit the command, there is no way to terminate it midway through. 必须等到该命令完成才能修改计数。You will have to wait until the command is finished before revising the counts.

Set-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6

结果应如以下输出所示。Results should look similar to the following output.

ResourceGroupName : demo-chinaeast2
Name              : my-demo-searchapp
Location          : China East 2
Sku               : Standard
ReplicaCount      : 6
PartitionCount    : 6
HostingMode       : Default
Id                : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-chinaeast2/providers/Microsoft.Search/searchServices/my-demo-searchapp

后续步骤Next steps

使用门户、REST API 或 .NET SDK 生成索引查询索引Build an index, query an index using the portal, REST APIs, or the .NET SDK.