通过

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

  • 项目

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

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

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

下面列出了创建阶段的一些常见错误。

请求验证失败

  • 不支持的 SKU：基本层和以上层支持共享的私有链接。 对于带有技能集的索引器，最小层是标准 2(S2)。

  • 无效名称：共享专用链接的命名规则为：

    • 长度应在 1 至 60 个字符之间
    • 字母数字字符
    • 名称可以包括下划线 _、句点 . 和连字符 -，只要它不是名称中的第一个字符

  • 组 ID 无效：组 ID 区分大小写，必须是下表中的值之一：

    Azure 资源 组 ID 第一个可用的 API 版本
    Azure 存储 - Blob（或）ADLS Gen 2 blob 2020-08-01
    Azure 存储 - 表 table 2020-08-01
    Azure Cosmos DB for NoSQL Sql 2020-08-01
    Azure SQL 数据库 sqlServer 2020-08-01
    Azure Database for MySQL（预览版） mysqlServer 2020-08-01-Preview
    Azure Key Vault 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 Key Vault 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

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

  • 强制执行配额限制：搜索服务对可创建的共享专用链接资源的不同数量和正在使用的各种目标资源类型的数量施加配额（基于 groupId）。 Azure AI 搜索服务限制页的共享专用链接资源限制部分阐述了这些限制。

部署失败

搜索服务启动创建共享专用链接的请求，但由 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 删除现有的共享专用链接资源。 与创建（或更新）过程相似，这也是一个异步操作，分为四个步骤：

  1. 请求搜索服务删除共享专用链接资源。

  2. 搜索服务验证该资源是否存在且是否处于一种可供删除的状态。 如果是，它会启动 Azure 资源管理器删除操作以删除资源。

  3. 搜索完成操作的查询（通常需要几分钟）。 此时，共享专用链接资源的预配状态为“正在删除”。

  4. 操作成功完成后，将删除备份专用终结点和任何关联的 DNS 映射。 该资源将不会显示为列出操作的一部分，并且对该资源尝试执行获取操作将导致出现“404 未找到”错误。

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

下面列出了删除阶段的一些常见错误。

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

后续步骤

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