排查Azure AI 搜索中共享专用链接的问题

共享专用链接允许Azure AI 搜索在访问虚拟网络中的客户资源时通过专用终结点建立安全的出站连接。本文可以帮助你解决可能出现的错误。

创建共享专用链接是搜索服务控制平面操作。可以使用 Azure 门户或 Management REST API 创建共享专用链接。在预配期间，请求的状态为 Updating。作成功完成后，状态为 Succeeded。将创建资源的专用终结点以及任何 DNS 区域和映射。此终结点由搜索服务实例独占使用，并通过Azure AI 搜索进行管理。

创建共享专用链接资源时所涉及的步骤

以下是在创建阶段发生的常见错误。

请求验证失败

不支持的 SKU：基本层和更高层支持共享的专用链接。对于带有技能集的索引器，最小层是标准 1 (S1)。有关详细信息，请参阅共享专用链接资源限制。
无效名称：共享专用链接的命名规则为：
- 长度应在 1 至 60 个字符之间
- 字母数字字符
- 名称可以包括下划线 _、句点 . 和连字符 -，只要它不是名称中的第一个字符

组 ID 无效：组 ID 区分大小写，必须是以下值之一。

Azure资源	组标识	第一个可用的 API 版本
Azure 存储 - Blob （或） ADLS Gen 2	`blob`	`2020-08-01`
Azure 存储 - 表	`table`	`2020-08-01`
NoSQL的Azure Cosmos DB	`Sql`	`2020-08-01`
Azure SQL 数据库	`sqlServer`	`2020-08-01`
Azure Database for MySQL（预览版）	`mysqlServer`	`2020-08-01-Preview`
Azure 密钥保管库	`vault`	`2020-08-01`
Azure Functions（预览版）	`sites`	`2020-08-01-Preview`

标有“（预览版）”的资源必须使用管理 REST API 版本的预览版创建。

privateLinkResourceId 类型验证：类似于 groupId，Azure AI 搜索验证privateLinkResourceId中是否指定了“正确”资源类型。下面是有效的资源类型：

Azure资源	资源类型	第一个可用的 API 版本
Azure 存储	`Microsoft.Storage/storageAccounts`	`2020-08-01`
Azure Cosmos DB	`Microsoft.DocumentDb/databaseAccounts`	`2020-08-01`
Azure SQL 数据库	`Microsoft.Sql/servers`	`2020-08-01`
Azure 密钥保管库	`Microsoft.KeyVault/vaults`	`2020-08-01`
Azure Database for MySQL（预览版）	`Microsoft.DBforMySQL/servers`	`2020-08-01-Preview`
Azure Functions（预览版）	`Microsoft.Web/sites`	`2020-08-01-Preview`
Azure SQL 托管实例（预览版）	`Microsoft.Sql/managedInstance`	`2020-08-01-Preview`

此外，指定的 groupId 需要对指定的资源类型有效。例如，groupId“blob”对于类型 Microsoft.Storage/storageAccounts有效，它不能用于任何其他资源类型。对于给定的搜索管理 API 版本，客户可以使用列出支持的 API来找出支持的groupId和资源类型的详细信息。

强制执行配额限制：搜索服务对可创建的共享专用链接资源的不同数量和正在使用的各种目标资源类型的数量施加配额（基于 groupId）。有关详细信息，请参阅共享专用链接资源限制。

部署失败

搜索服务启动创建共享专用链接的请求，但Azure 资源管理器执行实际工作。可以在Azure门户或查询中检查部署的状态，并解决可能发生的任何错误。

失败的 Azure 资源管理器部署的共享专用链接资源出现在 List 和 Get API 调用中，但它们的“配置状态”为 Failed。确定Azure 资源管理器部署失败的原因后，请删除 Failed 资源，并在应用下表中的相应解决方案后重新创建它。

部署失败原因	说明	解决方法
“LinkedAuthorizationFailed”	此错误消息表明客户端有权在搜索服务上创建共享专用链接，但无权对链接范围执行操作“privateEndpointConnectionApproval/action”。	重新检查请求中的专用链接 ID，以确保 URI 中没有错误或遗漏。如果 Azure AI 搜索和 Azure PaaS 资源位于不同的订阅中，并且您正在使用 REST 或命令行接口，请确保当前的 Azure 帐户关联的是该 Azure PaaS 资源。对于 REST 客户端，请确保你未使用过期的持有者令牌，并确保该令牌对活动订阅有效。
网络资源供应商未在目标资源的订阅上注册	通过 `Microsoft.Network` 资源提供程序（RP）为目标资源（存储帐户、Azure Cosmos DB、Azure SQL）创建专用终结点（和关联的 DNS 映射）。如果托管目标资源的订阅（“目标订阅”）未注册到 `Microsoft.Network` RP，则Azure 资源管理器部署可能会失败。	你需要在目标订阅中注册此 RP。可以使用 Azure 门户、PowerShell 或 CLI 注册资源提供程序。
目标资源的 `groupId` 无效	创建Azure Cosmos DB帐户时，可以为数据库帐户指定 API 类型。虽然Azure Cosmos DB提供了几种不同的 API 类型，但Azure AI 搜索仅支持“Sql”作为共享专用链接资源的 `groupId`。为指向非 Sql 数据库帐户的 `privateLinkResourceId` 创建类型为 "Sql" 的专用共享链接时，Azure 资源管理器部署失败，因为 `groupId` 不匹配。 Azure Cosmos DB帐户Azure资源 ID 不足以确定正在使用的 API 类型。 Azure AI 搜索尝试创建专用终结点，然后Azure Cosmos DB拒绝该终结点。	应确保指定Azure Cosmos DB资源的 `privateLinkResourceId` 适用于“Sql”API 类型的数据库帐户
找不到目标资源	仅在开始Azure 资源管理器部署期间，才会检查 `privateLinkResourceId` 中指定的目标资源是否存在。如果目标资源不再可用，则部署将失败。	你应确保目标资源存在于指定的订阅和资源组中，并且未被移动或删除
暂时性/其他错误	如果发生基础结构中断或其他意外原因，则Azure 资源管理器部署可能会失败。这种情况应该很少见，通常指示暂时性状态。	请稍后再尝试创建此资源。如果问题仍然存在，请联系Azure支持部门。

批准后备专用终结点的问题

专用终结点根据共享专用链接创建请求中指定的目标 Azure 资源而创建。这是异步Azure 资源管理器部署操作的最后一个步骤之一，但Azure AI 搜索需要在网络配置过程中链接专用终结点的专用 IP 地址。完成此链接后， provisioningState 共享专用链接资源将进入终端成功状态 Succeeded。客户只应在状态转换为 Succeeded 后批准或拒绝（或是通常修改后备专用终结点的配置）。在此之前以任何方式修改专用终结点都可能会导致部署操作不完整，并可能导致共享专用链接资源以 Failed 状态结束（立即，或通常在几个小时内）。

搜索服务的网络连接更改滞留在“正在更新”状态

当搜索服务的“公用网络访问”处于“已禁用”状态时，将使用共享专用链接和专用终结点。通常，在接受请求后几分钟内，更改网络连接应成功。在某些情况下，Azure AI 搜索可能需要几个小时才能完成连接更改操作。

公用网络访问更改为禁用的屏幕截图。

如果你发现连接更改操作花费的时间很长，请等待几个小时。连接更改操作涉及更新 DNS 记录等操作，这些操作可能比预期耗时更长。

如果 更改了公用网络访问 ，则现有的共享专用链接和专用终结点可能无法正常工作。如果现有的共享专用链接和专用终结点在执行连接更改操作期间停止工作，请等待几个小时，让该操作完成。如果它们仍然无法正常工作，请尝试将其删除再重新创建。

共享专用链接资源停滞在“正在更新”或“未完成”状态

通常，在接受请求后的几分钟内，共享专用链接资源应进入终端状态（Succeeded 或 Failed）。

在极少数情况下，Azure AI 搜索无法将共享专用链接资源的状态正确标记为终端状态（Succeeded 或 Failed）。这通常是由于意外故障而导致的。如果共享专用链接资源处于非终止状态超过几个小时，则会自动转换为 Failed 状态。

如果共享专用链接资源没有转换为终端状态，请等待几个小时，以确保它变为Failed状态后再删除和重新创建。或者你不用等待，可以尝试使用其他名称创建另一个共享专用链接资源（其他所有参数保持不变）。

更新共享专用链接资源

可以使用创建或更新 API更新现有的共享专用链接资源。搜索服务只允许对共享专用链接资源进行小范围更新 - 通过此 API 只能修改请求消息。

无法更新现有共享专用链接资源的任何“核心”属性（例如 privateLinkResourceId 和 groupId），并且此操作始终不受支持。如果需要更改除请求消息以外的任何其他属性，我们建议客户删除并重新创建共享专用链接资源。
仅当共享专用链接资源达到预配状态 Succeeded时，才能更新共享专用链接资源的请求消息。

删除共享专用链接资源

客户可以通过删除 API 删除现有的共享专用链接资源。与创建（或更新）过程相似，这也是一个异步操作，分为四个步骤：

请求搜索服务删除共享专用链接资源。
搜索服务验证该资源是否存在且是否处于一种可供删除的状态。如果是这样，它将启动Azure 资源管理器删除操作以删除资源。
查询以获取操作完成状态（通常需要几分钟）。此时，共享专用链接资源将具有预配状态 Deleting。
操作成功完成后，将删除备份专用终结点和任何关联的 DNS 映射。该资源不会在列表操作中显示，并且尝试对此资源执行Get操作会导致404未找到。

删除共享专用链接资源时所涉及的步骤

以下是在删除阶段发生的常见错误。

失败类型	说明	解决方法
资源处于非终止状态	无法删除不处于终端状态（`Succeeded` 或 `Failed`）的共享专用链接资源。共享专用链接资源可能会在非终止状态下卡住，最长可达 8 小时（极少见）。	等待资源达到终端状态，然后重试删除请求。
删除操作失败，出现“冲突”错误	删除共享专用链接资源的Azure 资源管理器操作将到达 `privateLinkResourceId` （“target RP”）中指定的目标资源的资源提供程序，然后才能删除专用终结点和 DNS 映射。客户可以利用 Azure 资源锁来防止对其资源进行任何更改。当 Azure 资源管理器与目标 RP 进行交互时，它会要求目标 RP 修改目标资源的状态，以从其元数据中删除有关专用终结点的详细信息。当目标资源在其（或其资源组/订阅）上配置了锁时，Azure 资源管理器操作会失败并显示“冲突”（以及相应的详细信息）。不会删除共享专用链接资源。	客户应在重试删除操作之前移除目标资源的锁。注意：当客户尝试删除具有指向锁定目标资源的共享专用链接资源的搜索服务时，也会发生此问题
删除操作失败	在极少数情况下，异步Azure 资源管理器删除操作可能会失败。如果此作失败，查询异步作的状态会显示错误消息和相应的详细信息。	稍后重试该操作，或联系Azure支持（如果问题仍然存在）。
资源陷入“正在删除”状态	在极少数情况下，共享专用链接资源可能会卡在“正在删除”状态长达 8 个小时，这可能是由于搜索 RP 发生灾难性故障。	等待 8 小时后，资源将转换为 `Failed` 状态，然后请重新发出请求。

后续步骤

了解有关共享专用链接资源的详细信息，以及如何使用它来安全访问受保护的内容。

Last updated on 2026-04-08