Migrar de Search v2 a v3

Aprenda a migrar de Auth0 Search v2 a v3.

La búsqueda de usuarios v2 dejó de estar disponible el 30 de junio de 2019. Recomendamos encarecidamente migrar la funcionalidad de búsqueda de usuarios al motor de búsqueda v3 (search_engine=v3) lo antes posible.

​

Consideraciones sobre la migración

Antes de comenzar la migración, hay algunas cosas que debe saber:

• Para asegurarse de que sus consultas usen el motor de búsqueda v3 antes de que v2 deje de estar disponible, debe actualizar todas sus llamadas al endpoint GET /api/v2/users para incluir el parámetro search_engine=v3. Esto le permitirá comprobar si alguna consulta debe actualizarse, para que no experimente interrupciones cuando v2 deje de estar disponible.
• Si realiza operaciones de búsqueda de usuarios mediante cualquiera de los SDK afectados, también debe pasar el parámetro search_engine=v3 como se indicó anteriormente.
• Los valores de búsqueda de los campos de usuario normalizados (email, name, given_name, family_name y nickname) no distinguen entre mayúsculas y minúsculas. Todos los demás campos (incluidos todos los campos app_metadata/user_metadata) sí distinguen entre mayúsculas y minúsculas.
• v3 limita a 1000 la cantidad de usuarios que puede recuperar. Si alcanza este límite, le recomendamos reformular la consulta de búsqueda para obtener resultados más específicos. Si necesita una lista de más de 1000 usuarios en un momento determinado, le recomendamos usar el endpoint de la API Trabajo de exportación o la Extensión de importación/exportación de usuarios.
• Las búsquedas por rango y con comodines no están disponibles para los campos app_metadata/user_metadata.
• Los campos de usuario no se tokenizan como en v2, por lo que user_id:auth0 no coincidirá con un user_id cuyo valor sea auth0|12345; en su lugar, use user_id:auth0*.
• Los comodines pueden usarse para coincidencias por prefijo, por ejemplo name:j*. Para otros usos de comodines (por ejemplo, coincidencias por sufijo), los literales deben tener 3 caracteres o más. Por ejemplo, name:*usa está permitido, pero name:*sa no.
• La extensión de campo .raw ya no se admite y debe eliminarse. En v3, los campos coinciden con el valor completo proporcionado y no se tokenizan como ocurría en v2 sin el sufijo .raw.
• El campo connection no es compatible con v3. En su lugar, debe usar su alias identities.connection.

​

Consultas que deben migrarse

Caso de uso	v2	v3
Búsqueda por fecha	updated_at:>=2018-01-15	updated_at:[2018-01-15 TO *]
Búsqueda por fecha	updated_at:>2018-01-15	<br/>updated_at:\{2018-01-15 TO *]<br/>
Búsqueda por fecha	updated_at:<=2018-01-15	updated_at:[* TO 2018-01-15]
Búsqueda por fecha	updated_at:<2018-01-15	updated_at:[* TO 2018-01-15}
Búsqueda por fecha	last_login:<=2017-12	last_login:[* TO 2017-12]
Coincidencia exacta de cadena	name.raw:"john richard doe"	name:"john richard doe"
La frase contiene una palabra	name:"richard", name:richard	name:*richard*
La frase contiene una palabra (con menos de 3 caracteres)	name:*ri,name:*a, name:*ab*	(no compatible)

​

SDK afectados

Los siguientes SDK usan el motor de User Search. Si usa alguno de ellos, asegúrese de utilizar las versiones que se indican a continuación (o una posterior) y de pasar el parámetro search_engine=v3 al realizar operaciones de User Search.

SDK	Versión compatible con v3	Métodos afectados	Consideraciones
Auth0 Java	1.8.0	com.auth0.client.mgmt.UsersEntity.list	Proporcione un UserFilter con withSearchEngine("v3")
Auth0 Python	3.0.0	management.Users.list	Proporcione el parámetro search_engine='v3'
Auth0 Node	2.0.0	UsersManager.getAll, ManagementClient.getUsers	Proporcione el parámetro search_engine:'v3'
Auth0 .NET	3.0.0 o 4.0.0	Auth0.ManagementApi.IUsersClient.GetAllAsync	Proporcione un objeto GetUsersRequest con SearchEngine = "v3"
Auth0 PHP	5.2.0	Auth0.SDK.API.Management.Users.getAll	Proporcione el parámetro 'search_engine' => 'v3'
Auth0 Ruby	4.5.0	Auth0.Api.V2.Users.users	Proporcione el parámetro search_engine: 'v3'

​

Extensiones afectadas

Las siguientes extensiones utilizan el motor User Search. Si las tiene instaladas, asegúrese de usar las versiones que se indican a continuación (o una posterior).

Extensión	Compatibilidad de versiones con v3	Consideraciones
Authorization Extension	2.5.0+	Si usa una versión anterior, debe actualizar manualmente la extensión desde la página Extensions.
Delegated Administration	3.1+	Si usa una versión anterior, debe actualizar manualmente la extensión desde la página Extensions. La opción de configuración SEARCH_ENGINE ya no existe en la versión 3.1, porque solo está disponible User Search v3.

​

Aprovecha los registros del inquilino para identificar el uso de User Search v2

Puedes aprovechar los logs en el Dashboard para encontrar llamadas al endpoint /api/v2/users que usan el motor User Search v2, incluidas las realizadas por SDKs. Esos logs te ayudarán a identificar dónde podrían ser necesarios cambios de código en tus aplicaciones.

Usa la siguiente consulta para recuperar todos los logs relacionados con User Search v2: type:w AND description:*search_engine*. Los logs proporcionarán información adicional en el campo description en los siguientes casos:

• Consultas que podrían producir resultados diferentes en v3
• Consultas con sintaxis incompatible con v3
• Consultas que no cumplen los requisitos de paginación de v3

Si no se especifican detalles adicionales en las entradas de log, es probable que tus consultas sean compatibles con v3. Aun así, nuestra recomendación sigue siendo que pruebes las consultas antes de desplegar tus cambios en producción.

Ten en cuenta que solo se generará un log del mismo tipo en un periodo de 60 minutos. Esto significa que, aunque hagas varias llamadas al endpoint de User Search, solo verás un log de cada tipo por hora.