Migrer de Search v2 à v3

Découvrez comment migrer d’Auth0 Search v2 à v3.

User Search v2 est arrivé en fin de vie le 30 juin 2019. Nous vous recommandons fortement de migrer vers search engine v3 (search_engine=v3) dès que possible.

​

Considérations relatives à la migration

Avant de commencer la migration, voici quelques éléments à savoir :

• Pour vous assurer que vos requêtes utilisent search engine v3 avant que v2 ne devienne indisponible, vous devez mettre à jour tous vos appels à l’endpoint GET /api/v2/users afin d’inclure le paramètre search_engine=v3. Vous pourrez ainsi vérifier si certaines requêtes doivent être mises à jour, pour éviter toute interruption lorsque v2 ne sera plus disponible.
• Si vous effectuez des recherches d’utilisateurs au moyen de l’un des SDKs touchés, vous devez également transmettre le paramètre search_engine=v3 comme indiqué ci-dessus.
• Les valeurs de recherche pour les champs utilisateur normalisés (email, name, given_name, family_name et nickname) ne sont pas sensibles à la casse. Tous les autres champs (y compris tous les champs app_metadata/user_metadata) sont sensibles à la casse.
• v3 limite à 1000 le nombre d’utilisateurs que vous pouvez récupérer. Si vous atteignez cette limite, nous vous recommandons de redéfinir votre requête de recherche afin d’obtenir des résultats plus précis. Si vous avez besoin d’une liste de plus de 1000 utilisateurs à un moment donné, nous vous recommandons plutôt d’utiliser l’endpoint d’API Export Job ou User Import / Export Extension.
• Les recherches par plage et avec caractères génériques ne sont pas offertes pour les champs app_metadata/user_metadata.
• Les champs utilisateur ne sont pas segmentés comme dans v2. Ainsi, user_id:auth0 ne correspondra pas à un user_id dont la valeur est auth0|12345; utilisez plutôt user_id:auth0*.
• Les caractères génériques peuvent être utilisés pour faire une correspondance par préfixe, par exemple name:j*. Pour les autres utilisations des caractères génériques (p. ex. la correspondance par suffixe), les valeurs littérales doivent comporter au moins 3 caractères. Par exemple, name:*usa est permis, mais name:*sa ne l’est pas.
• L’extension de champ .raw n’est plus prise en charge et doit être supprimée. Dans v3, les champs correspondent à la valeur complète fournie et ne sont pas segmentés comme ils l’étaient dans v2 sans le suffixe .raw.
• Le champ connection n’est pas pris en charge dans v3. Vous devriez plutôt utiliser son alias identities.connection.

​

Requêtes à migrer

Cas d’utilisation	v2	v3
Recherche par date	updated_at:>=2018-01-15	updated_at:[2018-01-15 TO *]
Recherche par date	updated_at:>2018-01-15	<br/>updated_at:\{2018-01-15 TO *]<br/>
Recherche par date	updated_at:<=2018-01-15	updated_at:[* TO 2018-01-15]
Recherche par date	updated_at:<2018-01-15	updated_at:[* TO 2018-01-15}
Recherche par date	last_login:<=2017-12	last_login:[* TO 2017-12]
Correspondance exacte de chaîne de caractères	name.raw:"john richard doe"	name:"john richard doe"
Expression contenant un mot	name:"richard", name:richard	name:*richard*
Expression contenant un mot (de moins de 3 caractères)	name:*ri,name:*a, name:*ab*	(non pris en charge)

​

SDKs concernés

Les SDKs suivants utilisent le User Search engine. Si vous les utilisez, assurez-vous d’utiliser les versions indiquées ci-dessous (ou une version ultérieure) et de transmettre le paramètre search_engine=v3 lors de l’exécution d’opérations de recherche d’utilisateurs.

SDK	Version prenant en charge v3	Méthodes concernées	Considérations
Auth0 Java	1.8.0	com.auth0.client.mgmt.UsersEntity.list	Fournissez un UserFilter avec withSearchEngine("v3")
Auth0 Python	3.0.0	management.Users.list	Fournissez le paramètre search_engine='v3'
Auth0 Node	2.0.0	UsersManager.getAll, ManagementClient.getUsers	Fournissez le paramètre search_engine:'v3'
Auth0 .NET	3.0.0 ou 4.0.0	Auth0.ManagementApi.IUsersClient.GetAllAsync	Fournissez un objet GetUsersRequest avec SearchEngine = "v3"
Auth0 PHP	5.2.0	Auth0.SDK.API.Management.Users.getAll	Fournissez le paramètre 'search_engine' => 'v3'
Auth0 Ruby	4.5.0	Auth0.Api.V2.Users.users	Fournissez le paramètre search_engine: 'v3'

​

Extensions concernées

Les Extensions suivantes font appel au User Search engine. Si elles sont installées, assurez-vous d’utiliser les versions indiquées ci-dessous (ou une version ultérieure).

Extension	Version compatible avec v3	Considérations
Authorization Extension	2.5.0+	Si vous utilisez une version antérieure, vous devez mettre à jour manuellement l’extension depuis la page Extensions.
Delegated Administration	3.1+	Si vous utilisez une version antérieure, vous devez mettre à jour manuellement l’extension depuis la page Extensions. Le paramètre de configuration SEARCH_ENGINE n’existe plus dans la version 3.1, car seule la version User Search v3 est disponible.

​

Exploitez les journaux de votre tenant pour repérer l’utilisation de User Search v2

Vous pouvez exploiter les journaux dans le Dashboard pour repérer les appels au point de terminaison /api/v2/users qui utilisent le moteur User Search v2, y compris les appels effectués par les SDK. Ces journaux vous aideront à déterminer où des modifications du code pourraient être nécessaires dans vos applications.

Utilisez la requête suivante pour récupérer tous les journaux liés à User Search v2 : type:w AND description:*search_engine*. Les journaux fourniront des renseignements supplémentaires dans le champ description, dans les cas suivants :

• Les requêtes qui pourraient produire des résultats différents dans v3
• Les requêtes dont la syntaxe est incompatible avec v3
• Les requêtes qui ne respectent pas les exigences de pagination de v3

Si aucun détail supplémentaire n’est indiqué dans les entrées de journal, il est probable que vos requêtes soient compatibles avec v3. Nous vous recommandons toutefois de tester les requêtes avant de déployer vos changements en production.

Veuillez noter qu’un seul journal du même type sera généré sur une période de 60 minutes. Cela signifie que même si vous effectuez plusieurs appels au point de terminaison User Search, vous ne verrez qu’un seul journal de chaque type par heure.