Migrer de Search v2 vers v3

Découvrez comment migrer de Search v2 vers v3 dans Auth0.

La recherche d’utilisateurs v2 est en fin de vie depuis le 30 juin 2019. Nous vous recommandons fortement de migrer la fonctionnalité de recherche d’utilisateurs vers le moteur de recherche v3 (search_engine=v3) dès que possible.

​

Considérations relatives à la migration

Avant de commencer la migration, voici quelques points à savoir :

• Pour vous assurer que vos requêtes utilisent le moteur de recherche v3 avant que la v2 ne devienne indisponible, vous devez mettre à jour tous vos appels au point de terminaison GET /api/v2/users pour inclure le paramètre search_engine=v3. Cela vous permettra de voir si certaines requêtes doivent être mises à jour, afin d’éviter toute interruption de service lorsque la v2 ne sera plus disponible.
• Si vous effectuez des opérations de recherche d’utilisateurs au moyen de l’un des SDK concernés, vous devez également transmettre le paramètre search_engine=v3, comme indiqué ci-dessus.
• Les valeurs de recherche des 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.
• La 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 le point de terminaison d’API Tâche d’exportation ou l’extension d’importation/exportation d’utilisateurs.
• Les recherches par plage et par caractères génériques ne sont pas disponibles pour les champs app_metadata/user_metadata.
• Les champs utilisateur ne sont pas découpés en jetons comme dans la v2, donc 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 la 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 littéraux doivent comporter au moins 3 caractères. Par exemple, name:*usa est autorisé, mais name:*sa ne l’est pas.
• L’extension de champ .raw n’est plus prise en charge et doit être supprimée. Dans la v3, les champs correspondent à l’ensemble de la valeur fournie et ne sont pas découpés en jetons, comme c’était le cas dans la v2 sans le suffixe .raw.
• Le champ connection n’est pas pris en charge dans la v3. Vous devez utiliser son alias identities.connection à la place.

​

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)

​

SDK concernés

Les SDK suivants utilisent le moteur User Search. Si vous les utilisez, assurez-vous d’employer les versions indiquées ci-dessous (ou une version ultérieure) et de transmettre le paramètre search_engine=v3 lorsque vous effectuez des opérations de User Search.

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 utilisent le moteur User Search. Si vous les avez installées, assurez-vous d’utiliser les versions indiquées ci-dessous (ou une version ultérieure).

Extension	Compatibilité avec v3	Considérations
Authorization Extension	2.5.0+	Si vous utilisez une version antérieure, vous devez mettre à jour l’extension manuellement à partir de la page Extensions.
Delegated Administration	3.1+	Si vous utilisez une version antérieure, vous devez mettre à jour l’extension manuellement à partir de 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 locataire pour repérer l’utilisation de User Search v2

Vous pouvez exploiter les journaux dans l’Auth0 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 modifications en production.

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