Solución de problemas con vínculos privados compartidos en Búsqueda de Azure AI

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Un vínculo privado compartido permite a Búsqueda de Azure AI crear conexiones salientes seguras a través de un punto de conexión privado al acceder a los recursos del cliente en una red virtual. Este artículo puede ayudarle a resolver los errores que pueden producirse.

La creación de un vínculo privado compartido es una operación del plano de control del servicio de búsqueda. Puede crear un vínculo privado compartido mediante Azure Portal o una API REST de administración. Durante el aprovisionamiento, el estado de la solicitud es Updating. Una vez completada correctamente la operación, el estado es Succeeded. Se crea un punto de conexión privado para el recurso, junto con las zonas DNS y las asignaciones. Este punto de conexión lo usa exclusivamente la instancia del servicio de búsqueda y se administra a través de Búsqueda de Azure AI.

Pasos necesarios para crear recursos de vínculo privado compartidos

A continuación se muestran errores comunes que se producen durante la fase de creación.

Errores de validación de la solicitud

  • SKU no admitida: los vínculos privados compartidos se admiten en el nivel Básico y versiones posteriores. Para los indexadores con habilidades, el nivel mínimo es Estándar 1 (S1). Para más información, consulte Límites de recursos de vínculo privado compartido.

  • Nombre no válido: las reglas de nomenclatura para un vínculo privado compartido son:

    • La longitud debe estar entre 1 y 60 caracteres.
    • Caracteres alfanuméricos.
    • Los nombres pueden incluir guiones bajos _, puntos . y guiones -, siempre que no sea el primer carácter del nombre.

  • Identificador de grupo no válido: los identificadores de grupo distinguen mayúsculas de minúsculas y deben ser uno de los valores siguientes.

    Recurso de Azure Identificador de grupo Primera versión de API disponible
    Azure Storage: Blob (o) ADLS Gen2 blob 2020-08-01
    Azure Storage: Tablas table 2020-08-01
    Azure Cosmos DB for NoSQL Sql 2020-08-01
    Azure SQL Database sqlServer 2020-08-01
    Azure Database for MySQL (versión preliminar) mysqlServer 2020-08-01-Preview
    Azure Key Vault vault 2020-08-01
    Azure Functions (versión preliminar) sites 2020-08-01-Preview

    Los recursos marcados con "(versión preliminar)" deben crearse mediante una versión preliminar de las versiones de la API REST de administración.

  • Validación de tipos de privateLinkResourceId: de forma similar a groupId, Búsqueda de Azure AI valida que se haya especificado el tipo de recurso "correcto" en privateLinkResourceId. Los siguientes son tipos de recursos válidos:

    Recurso de Azure Tipo de recurso Primera versión de API disponible
    Azure Storage Microsoft.Storage/storageAccounts 2020-08-01
    Azure Cosmos DB (la base de datos de Azure Cosmos) Microsoft.DocumentDb/databaseAccounts 2020-08-01
    Azure SQL Database Microsoft.Sql/servers 2020-08-01
    Azure Key Vault Microsoft.KeyVault/vaults 2020-08-01
    Azure Database for MySQL (versión preliminar) Microsoft.DBforMySQL/servers 2020-08-01-Preview
    Azure Functions (versión preliminar) Microsoft.Web/sites 2020-08-01-Preview
    Azure SQL Managed Instance (versión preliminar) Microsoft.Sql/managedInstance 2020-08-01-Preview

    Además, el elemento groupId especificado debe ser válido para el tipo de recurso especificado. Por ejemplo, groupId "blob" es válido para el tipo Microsoft.Storage/storageAccounts, no se puede usar con ningún otro tipo de recurso. Para una versión determinada de la API de administración de Azure Cognitive Search, los clientes pueden averiguar los detalles del tipo de recurso y de los elementos groupId admitidos mediante la API List supported.

  • Cumplimiento del límite de cuota: los servicios de Azure Cognitive Search tienen cuotas impuestas en el número de recursos de vínculo privado compartidos que se pueden crear y en el número de diversos tipos de recursos de destino que se usan (en función de groupId). Para más información, consulte Límites de recursos de vínculo privado compartido.

Errores de implementación

Un servicio de búsqueda inicia la solicitud para crear un vínculo privado compartido, pero Azure Resource Manager realiza el trabajo real. Puede comprobar el estado de la implementación en Azure Portal o mediante consulta, y solucionar los errores que puedan producirse.

Los recursos de vínculo privado compartidos que fallan en la implementación de Azure Resource Manager aparecen en las llamadas API List y Get, pero tienen un "Estado de aprovisionamiento" de Failed. Una vez comprobado el motivo del error de implementación de Azure Resource Manager, elimine el Failed recurso y vuelva a crearlo después de aplicar la resolución adecuada de la tabla siguiente.

Motivo del error de implementación Descripción Resolución
"LinkedAuthorizationFailed" El mensaje de error indica que el cliente tiene permiso para crear el vínculo privado compartido en el servicio de búsqueda, pero no tiene permiso para realizar la acción "privateEndpointConnectionApproval/action" en el ámbito vinculado. Vuelva a comprobar el identificador de vínculo privado de la solicitud para asegurarse de que no haya errores ni omisiones en el URI. Si Búsqueda de Azure AI y el recurso PaaS de Azure están en suscripciones diferentes y, si usa REST o una interfaz de línea de comandos, asegúrese de que la cuenta de Azure activa sea el recurso PaaS de Azure. En el caso de los clientes REST, asegúrate de que no usas un token de portador caducado y de que el token es válido para la suscripción activa.
El proveedor de recursos de red no está registrado en la suscripción del recurso de destino. Se crea un punto de conexión privado (y las asignaciones DNS asociadas) para el recurso de destino (cuenta de almacenamiento, Azure Cosmos DB, Azure SQL) mediante el proveedor de recursos (RP) Microsoft.Network. Si la suscripción que hospeda el recurso de destino ("suscripción de destino") no está registrada con el RP Microsoft.Network, se puede producir un error en la implementación de Azure Resource Manager. Debe registrar este RP en la suscripción de destino. Puede registrar el proveedor de recursos mediante Azure Portal, PowerShell o la CLI.
Elemento groupId no válido para el recurso de destino Cuando se crean cuentas de Azure Cosmos DB, puede especificar el tipo de API para la cuenta de base de datos. Aunque Azure Cosmos DB ofrece varios tipos de API diferentes, Azure Cognitive Search solo admite "Sql" como valor de groupId para los recursos de vínculo privado compartidos. Cuando se crea un vínculo privado compartido de tipo "Sql" para un privateLinkResourceId que apunta a una cuenta que no es de base de datos SQL, se produce un error en la implementación de Azure Resource Manager debido a la falta de coincidencia de groupId. El id. de recurso de Azure de una cuenta de Azure Cosmos DB no es suficiente para determinar el tipo de API que se está utilizando. Búsqueda de Azure AI intenta crear el punto de conexión privado, que Azure Cosmos DB deniega. Debe asegurarse de que el elemento privateLinkResourceId del recurso de Azure Cosmos DB especificado sea para una cuenta de base de datos del tipo de API "Sql"
Recurso de destino no encontrado La existencia del recurso de destino especificado en privateLinkResourceId solo se comprueba durante el inicio de la implementación de Azure Resource Manager. Si el recurso de destino ya no está disponible, se produce un error en la implementación. Debe asegurarse de que el recurso de destino esté presente en la suscripción y el grupo de recursos especificados y de que no se mueva ni elimine.
Errores transitorios y otros errores La implementación de Azure Resource Manager puede producir un error si se produce una interrupción en la infraestructura o debido a otros motivos inesperados. Esto debe ser poco frecuente y normalmente indica un estado transitorio. Vuelva a intentar crear este recurso más adelante. Si el problema persiste, póngase en contacto con el equipo de Soporte técnico de Azure.

Problemas al aprobar el punto de conexión privado de respaldo

Se crea un punto de conexión privado en el recurso de Azure de destino, tal como se especifica en la solicitud de creación de vínculo privado compartido. Este es uno de los pasos finales de la operación asincrónica de implementación de Azure Resource Manager, pero Búsqueda de Azure AI debe vincular la dirección IP privada del punto de conexión privado como parte de su configuración de red. Una vez hecho este vínculo, el provisioningState del recurso de vínculo privado compartido va a un estado de éxito del terminal Succeeded. Los clientes solo deben aprobar o denegar (o en general modificar la configuración del punto de conexión privado de respaldo) después de que el estado pase a Succeeded. Cualquier tipo de modificación del punto de conexión privado que se realice antes podría provocar que no se completara la implementación y que el recurso de vínculo privado compartido termine (inmediatamente o, normalmente, al cabo de unas horas) en un estado Failed.

Un cambio de conectividad de red del servicio Search se ha detenido en el estado "Actualizando"

Los vínculos privados y los puntos de conexión privados compartidos se usan cuando el acceso a la red pública del servicio Search está deshabilitado. Normalmente, cambiar la conectividad de red debe realizarse en unos minutos después de que se acepte la solicitud. En algunas circunstancias, Búsqueda de Azure AI puede tardar varias horas en completar la operación de cambio de conectividad.

Captura de pantalla de cómo cambiar el acceso a la red pública a deshabilitado.

Si observa que la operación de cambio de conectividad tarda un tiempo significativo, espere unas horas. Las operaciones de cambio de conectividad implican operaciones como la actualización de registros DNS que pueden tardar más de lo esperado.

Si se cambia el acceso a la red pública , es posible que los vínculos privados compartidos existentes y los puntos de conexión privados no funcionen correctamente. Si los vínculos privados y los puntos de conexión privados compartidos existentes dejan de funcionar durante una operación de cambio de conectividad, espere unas horas hasta que se complete la operación. Si siguen sin funcionar, intenta eliminarlos y volver a crearlos.

Normalmente, un recurso de vínculo privado compartido debe ir a un estado terminal (Succeeded o Failed) en unos minutos después de que se acepte la solicitud.

En raras circunstancias, Búsqueda de Azure AI puede no marcar correctamente el estado del recurso de vínculo privado compartido en un estado terminal (Succeeded o Failed). Esto suele producirse debido a un error inesperado. Los recursos de vínculo privado compartido se pasan automáticamente a un estado de Failed si se "bloquea" en un estado no determinado durante más de unas horas.

Si el recurso de vínculo privado compartido no realiza la transición a un estado de terminal, espere unas horas para asegurarse de que se convierte Failed en antes de poder eliminarlo y volver a crearlo. Como alternativa, en lugar de esperar, puede intentar crear otro recurso de vínculo privado compartido con otro nombre (manteniendo todos los demás parámetros iguales).

Un recurso de vínculo privado compartido existente se puede actualizar mediante la API Create or Update. Search solo permite actualizaciones restringidas en el recurso de vínculo privado compartido: solo se puede modificar el mensaje de solicitud mediante esta API.

  • No es posible actualizar ninguna de las propiedades "principales" de un recurso de vínculo privado compartido existente (como privateLinkResourceId o groupId) y esto siempre será incompatible. Si es necesario cambiar cualquier otra propiedad que no sea el mensaje de solicitud, recomendamos a los clientes que eliminen y vuelvan a crear el recurso de vínculo privado compartido.

  • La actualización del mensaje de solicitud de un recurso de vínculo privado compartido solo es posible si alcanza el estado de aprovisionamiento de Succeeded.

Los clientes pueden eliminar un recurso de vínculo privado compartido existente mediante la API Delete. De forma similar al proceso de creación (o de actualización), también se trata de una operación asincrónica con cuatro pasos:

  1. Puede solicitar al servicio Search la eliminación del recurso de vínculo privado compartido.

  2. El servicio Search comprueba que el recurso exista y se encuentre en un estado válido para su eliminación. Si es así, inicia una operación de eliminación de Azure Resource Manager para quitar el recurso.

  3. Azure Cognitive Search consulta la finalización de la operación (que normalmente tarda unos minutos). En este momento, el recurso de vínculo privado compartido tendría un estado de aprovisionamiento de Deleting.

  4. Una vez que la operación se completa correctamente, se quitan el punto de conexión privado de respaldo y las asignaciones de DNS asociadas. El recurso no se muestra como parte de la operación List y el intento de una operación Get en este recurso da como resultado un error 404 No encontrado.

Pasos necesarios para eliminar recursos de vínculo privado compartidos

A continuación se muestran errores comunes que se producen durante la fase de eliminación.

Tipo del error Descripción Resolución
El recurso está en estado no terminal No se puede eliminar un recurso de vínculo privado compartido que no esté en un estado terminal (Succeeded o Failed). Es posible (poco frecuente) que un recurso de vínculo privado compartido se bloquee en un estado no determinado durante hasta 8 horas. Espere hasta que el recurso alcance un estado de terminal y vuelva a intentar la solicitud de eliminación.
Error en la operación de eliminación con el error "Conflicto" La operación de Azure Resource Manager para eliminar un recurso de vínculo privado compartido llega al proveedor de recursos del recurso de destino especificado en privateLinkResourceId ("RP de destino") antes de poder quitar el punto de conexión privado y las asignaciones de DNS. Los clientes pueden usar bloqueos de recursos de Azure para evitar cambios en sus recursos. Cuando Azure Resource Manager accede al RP de destino, requiere que el RP de destino modifique el estado del recurso de destino (para quitar los detalles sobre el punto de conexión privado de sus metadatos). Cuando el recurso de destino tiene un bloqueo configurado (o su grupo de recursos o suscripción), se produce un error en la operación de Azure Resource Manager con el error "Conflicto" (y los detalles adecuados). El recurso de vínculo privado compartido no se eliminará. Los clientes deben quitar el bloqueo en el recurso de destino antes de reintentar la operación de eliminación. Nota: Este problema también se puede producir cuando los clientes intentan eliminar un servicio Search con recursos de vínculo privado compartidos que apuntan a recursos de destino "bloqueados".
Error de la operación de eliminación La operación de eliminación asincrónica de Azure Resource Manager puede producir un error en raras ocasiones. Cuando se produce un error en esta operación, consultar el estado de la operación asincrónica presenta un mensaje de error y los detalles adecuados. Vuelva a intentar la operación más adelante o póngase en contacto con el equipo de soporte técnico de Azure si el problema persiste.
Recurso bloqueado en el estado "Eliminación en curso" En raras ocasiones, un recurso de vínculo privado compartido podría estar bloqueado en el estado "Eliminación en curso" durante un máximo de 8 horas, probablemente debido a algún error catastrófico en el RP de Azure Cognitive Search. Espere 8 horas, después de las cuales el recurso pasaría al estado Failed y, a continuación, vuelva a emitir la solicitud.

Pasos siguientes

Más información sobre los recursos de vínculo privado compartidos y cómo usarlos para proteger el acceso al contenido protegido.

  • Last updated on