通过

使用 Azure CLI 管理 Azure AI 搜索服务

可以在 Windows、macOS、Linux 或 Azure Power Shell 上运行 Azure CLI 命令和脚本，以创建和配置 Azure AI 搜索。

使用 az search 模块执行以下任务：

偶尔，系统会询问有关任务未 在上述列表中出现的问题。

不能以编程方式或在 Azure 门户中更改服务的名称或区域。 创建服务时会分配专用资源，因此更改基础硬件（位置或节点类型）需要新服务。

你无法使用工具或 API 将一个服务中的内容（例如索引）传输到另一个服务。 在服务内，以编程方式创建内容的操作是通过搜索服务 REST API 或 SDK（例如用于 .Net 的 Azure SDK）进行的。 虽然没有用于内容迁移的专用命令，但你可以编写调用 REST API 或客户端库的脚本，以便在新服务上创建和加载索引。

预览版管理功能通常在 az search 模块中不可用。 如果要使用预览功能，请使用管理 REST API 和预览 API 版本。

先决条件

  • 如需在本地运行 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-chinanorth/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "China North",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-chinanorth",
  "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-rules 参数传递公共 IP (v4) 地址或 CIDR 范围，如下所示。 规则应当以逗号 (,) 或分号 (;) 分隔。

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 主干网络上的专用链接，不会从公共 Internet 公开。 有关详细信息，请参阅有关为 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 "China North" \
    --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.azure.cn"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.azure.cn" \
    --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.azure.cn" \
   --zone-name "searchServiceZone"

若要详细了解如何在 Azure CLI 中创建专用终结点，请参阅此专用链接快速入门

管理专用终结点连接

除了创建专用终结点连接之外，还可以 showupdate 和 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>

使用机密计算创建服务

机密计算 是用于数据使用保护的可选计算类型。 配置后，搜索服务将部署在机密 VM（DCasv5 或 DCesv5）而不是标准 VM 上。 此计算类型还会对计费层级收取 10% 的附加费。 有关详细信息，请参阅定价页。

对于日常使用，不需要机密计算。 我们仅建议此计算类型符合严格的法规、合规性或安全要求。 有关详细信息，请参阅 机密计算用例。

计算类型在搜索服务的生存期内是固定的。 若要永久配置机密计算，请在新服务中将 compute-type 属性设置为 confidential。

az search service create \
  --name <search-service-name> \
  --resource-group <search-service-resource-group-name> \
  --location <search-service-region> \
  --sku basic \
  --compute-type confidential

重新生成管理员密钥

若要滚动更新管理 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 专用链接服务集成的资源（例如存储帐户）的访问权限。

如果你是使用索引器在 Azure AI 搜索中为数据编制索引，并且数据源位于专用网络上，则可以创建出站专用终结点连接来访问数据。

可在此处找到可从 Azure AI 搜索中为其创建出站专用终结点的 Azure 资源的完整列表，以及相关的“组 ID”值。

若要创建共享的专用链接资源，请使用 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>

需要先使用以下命令批准连接，然后才能使用该连接。 必须从子资源中检索专用终结点连接的 ID。 在本例中，我们通过 az storage 获取连接 ID。

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>

有关设置共享专用链接资源的详细信息，请参阅通过专用终结点建立索引器连接。

后续步骤

使用 Azure 门户、REST API 或 .NET SDK 生成索引和查询索引。