通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

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

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

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

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

请求验证失败

  • 不支持的 SKU：基本层和更高层支持共享的专用链接。 对于带有技能集的索引器，最小层是标准 1 (S1)。 有关详细信息，请参阅 共享专用链接资源限制。

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

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

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

    Azure 资源 组 ID 第一个可用的 API 版本
    Azure 存储 - Blob（或）ADLS Gen 2 blob 2020-08-01
    Azure 存储 - 表 table 2020-08-01
    Azure Cosmos DB（用于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（Azure 宇宙数据库） 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
    Azure SQL 托管实例（预览版） Microsoft.Sql/managedInstance 2020-08-01-Preview

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

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

部署失败

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

Azure 资源管理器部署失败的共享专用链接资源会显示在列出和获取 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”的共享私有链接时，由于groupId的不匹配，Azure 资源管理器的部署会失败。 仅凭 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. 搜索完成操作的查询（通常需要几分钟）。 此时，共享专用链接资源将具有预配状态 Deleting。

  4. 操作成功完成后，将删除备份专用终结点和任何关联的 DNS 映射。 该资源不会在列表操作中显示，并且尝试对此资源执行Get操作会导致404未找到。

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

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

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

后续步骤

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