Solución de problemas con vínculos privados compartidos en Azure AI Search

Artículo
12/10/2024

Un vínculo privado compartido permite a Azure AI Search 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 el portal o una API REST de administración. Durante el aprovisionamiento, el estado de la solicitud es "Actualizando". Una vez completada correctamente la operación, el estado es "Correcto". 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 Azure AI Search.

Pasos necesarios para crear recursos de vínculo privado compartidos

A continuación se enumeran algunos 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 conjuntos de aptitudes, el nivel mínimo es Estándar 2 (S2).
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 de la tabla siguiente:

Recurso de Azure	Id. 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 para 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 deprivateLinkResourceId: de forma similar a groupId, Azure AI Search valida que se haya especificado el tipo de recurso "correcto" en el elemento privateLinkResourceId. Los siguientes son tipos de recursos válidos:

Recurso de Azure	Tipo de recurso	Primera versión de API disponible
Almacenamiento de Azure	`Microsoft.Storage/storageAccounts`	`2020-08-01`
Azure Cosmos DB	`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, un elemento groupId con el valor "blob" es válido para el tipo "Microsoft.Storage/storageAccounts", pero 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). Estos se documentan en la sección Límites de los recursos de vínculo privado compartidos de la página de límites del servicio Azure AI Search.

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 el portal o mediante consulta, y solucionar los errores que puedan producirse.

Los recursos de vínculo privado compartidos que hayan tenido errores en la implementación de Azure Resource Manager se mostrarán en las llamadas de API List y Get, pero tendrán el "estado de aprovisionamiento" Failed (Con errores). Una vez que se haya determinado el motivo del error de implementación de Azure Resource Manager, elimine el recurso Failed y vuelva a crearlo después de aplicar la resolución adecuada a partir 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.	Vuelve a comprobar el identificador de vínculo privado en la solicitud para asegurarte de que no haya errores ni omisiones en el URI. Si Azure AI Search y el recurso PaaS de Azure están en distintas suscripciones y usas REST o una interfaz de línea de comandos, asegúrate de que la cuenta de Azure activa sea para 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 elemento `privateLinkResourceId` que apunta a una cuenta de base de datos que no es SQL, se producirá 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. Azure AI Search 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 producirá 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 Azure AI Search debe vincular la dirección IP privada del punto de conexión privado como parte de su configuración de red. A continuación, el valor de provisioningState del recurso de vínculo privado compartido pasará al estado Succeeded del terminal. Los clientes no deben aprobar o denegar (o, en general, modificar la configuración del punto de conexión privado de respaldo) hasta que el estado haya pasado 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 se debe realizar correctamente unos minutos después de que se haya aceptado la solicitud. En algunas circunstancias, Azure AI Search 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 y los puntos de conexión privados compartidos existentes 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.

El recurso de vínculo privado compartido se ha detenido en un estado "Actualizando" o "Incompleto"

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

En raras circunstancias, Azure AI Search 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 compartidos cambian automáticamente al estado Failed si se han quedado "bloqueados" en un estado no terminal durante varias horas.

Si observas que el recurso de vínculo privado compartido no ha pasado a un estado terminal, espera unas horas para asegurarte de que pasa al estado Failed antes de 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).

Actualización de un recurso de vínculo privado compartido

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.
El intento de actualizar el mensaje de solicitud de un recurso de vínculo privado compartido solo es posible si ha alcanzado el estado de aprovisionamiento Succeeded.

Eliminación de un recurso de vínculo privado compartido

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:

Puede solicitar al servicio Search la eliminación del recurso de vínculo privado compartido.
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.
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 "Eliminación en curso".
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 mostrará como parte de la operación List y si se intenta una operación Get en este recurso, se mostrará un error 404 No encontrado.

Pasos necesarios para eliminar recursos de vínculo privado compartidos

A continuación se enumeran algunos 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 (pero poco frecuente) que un recurso de vínculo privado compartido se bloquee en un estado no terminal durante un máximo de 8 horas.	Espere hasta que el recurso haya alcanzado un estado 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 de Azure Cognitive 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, al consultar el estado de la operación asincrónica se mostrará a los clientes 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.

Compartir vía