Migrer de Recherche v2 vers v3

La fonctionnalité de recherche d’utilisateurs v2 a atteint sa fin de vie au 30 juin 2019. Nous vous recommandons vivement de migrer la fonctionnalité de recherche d’utilisateurs vers search engine v3 (search_engine=v3) dès que possible.

Avant de commencer la migration, vous devez savoir un certain nombre de choses

• Pour vous assurer que vos requêtes utilisent le moteur de recherche v3 avant que 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 déterminer si des requêtes doivent être mises à jour, de manière à ne pas subir de temps d’arrêt lorsque la v2 deviendra indisponible.

• Si vous effectuez des opérations de recherche d’utilisateur via l’un des trousses SDK impactées, vous devez également passer le paramètre search_engine=v30 comme indiqué ci-dessus.

• Les valeurs de recherche pour les champs utilisateur normalisés (courriel, nom, prénom, nom de famille, et surnom) 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 granulaires. Si vous avez besoin d’une liste de plus de 1000 utilisateurs à un moment donné, nous vous recommandons d’utiliser le point de terminaison de l’API  Export Job (Exporter la tâche) ou l’extension User Import/Export (Importation/Exportation des 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 tokenisés comme dans v2, donc user_id:auth0 ne correspondra pas à user_id avec la valeur auth0|12345, à la place, utilisez user_id:auth0*.

• Les caractères génériques peuvent être utilisés pour la correspondance de préfixe, par exemple  name:j*. Pour les autres utilisations des caractères génériques (par ex., la correspondance de suffixes), les littéraux doivent comporter 3 caractères ou plus. 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 v3, les champs correspondent à l’intégralité de la valeur fournie et ne comportent pas de jetons, comme c’était le cas dans V2 sans le suffixe .raw.

• Le champ  connexion n’est pas pris en charge dans v3. Vous devriez utiliser plutôt son alias identities.connection.

Les trousses SDK suivantes utilisent le moteur de recherche d’utilisateurs. Si vous les utilisez, assurez-vous que vous utilisez les versions énumérées ci-dessous (ou une version plus récente), et passez le paramètre search_engine=v3, lorsque vous effectuez des opérations de recherche d’utilisateurs.

Les extensions suivantes utilisent le moteur de recherche d’utilisateurs. Si vous les avez installées, assurez-vous que vous utilisez les versions listées ci-dessous (ou une version plus récente).

Vous pouvez tirer parti des logs (journaux) dans le Dashboard (Tableau de bord) pour trouver les appels vers le point de terminaison  /api/v2/users qui utilise le moteur de recherche v2, y compris les appels effectués par les trousses SDK. Ces journaux vous aideront à identifier les modifications à apporter au code de vos applications.

Utilisez la requête suivante pour récupérer tous les journaux relatifs à la recherche d’utilisateurs v2 :  type:w AND description:*search_engine*. Les journaux fourniront des informations supplémentaires dans le champ de description dans les cas suivants :

• Requêtes susceptibles de produire des résultats différents dans la v3

• Requêtes dont la syntaxe est incompatible avec la v3

• Requêtes qui ne répondent pas aux exigences de la v3 en matière de pagination

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

Notez qu’un seul journal du même type sera généré en l’espace de 60 minutes. Cela signifie que même si vous effectuez plusieurs appels au point de terminaison Recherche d’utilisateurs, un seul journal de chaque type sera généré par heure.