Récupérer des utilisateurs à l’aide du point de terminaison Get Users

Découvrez comment récupérer des listes d’utilisateurs à l’aide du point de terminaison get_users.

Le point de terminaison GET /api/v2/users vous permet de récupérer une liste d’utilisateurs. Avec ce point de terminaison, vous pouvez :

• Effectuer une recherche selon divers critères
• Sélectionner les champs à renvoyer
• Trier les résultats renvoyés

Ce point de terminaison présente une cohérence éventuelle; par conséquent, nous vous recommandons de l’utiliser pour les processus de back-office, comme la modification du nom d’affichage d’un utilisateur existant.

​

Exemple de requête

Pour rechercher des utilisateurs, faites une requête GET au point de terminaison /api/v2/users. La requête doit inclure un jeton d’accès à la Management API. Passez votre requête de recherche dans le paramètre q et définissez le paramètre search_engine à v3.

Par exemple, pour rechercher un utilisateur dont le courriel correspond exactement à [e-mail], utilisez q=email:"[e-mail]" :

Si la requête réussit, vous recevrez une réponse comme celle-ci :

[
  {
    "email": "[e-mail]",
    "email_verified": false,
    "username": "janedoe",
    "phone_number": "[phone]",
    "phone_verified": false,
    "user_id": "auth0|5457edea1b8f22891a000004",
    "created_at": "",
    "updated_at": "",
    "identities": [
      {
        "connection": "Initial-Connection",
        "user_id": "5457edea1b8f22891a000004",
        "provider": "auth0",
        "isSocial": false
      }
    ],
    "app_metadata": {},
    "user_metadata": {},
    "picture": "",
    "name": "",
    "nickname": "",
    "multifactor": [
      ""
    ],
    "last_ip": "",
    "last_login": "",
    "logins_count": 0,
    "blocked": false,
    "given_name": "",
    "family_name": ""
  }
]

​

Exemples de requêtes

Vous trouverez ci-dessous quelques exemples des types de requêtes que vous pouvez effectuer avec la Management API.

Cas d’utilisation	Requête
Rechercher tous les utilisateurs dont le nom contient “john”	name:\*john\*
Rechercher tous les utilisateurs dont le nom est exactement “jane”	name:"jane"
Rechercher tous les noms d’utilisateurs qui commencent par “john”	name:john*
Rechercher les noms d’utilisateurs qui commencent par “jane” et se terminent par “smith”	name:jane*smith
Rechercher tous les utilisateurs dont le courriel est exactement “[e-mail]”	email:"[e-mail]"
Rechercher tous les utilisateurs dont le courriel est exactement “[e-mail]” ou “[e-mail]” à l’aide de OR	email:("[e-mail]" OR "[e-mail]")
Rechercher les utilisateurs sans courriel vérifié	email_verified:false OR NOT \_exists_\:email_verified
Rechercher les utilisateurs dont le champ user_metadata full_name a pour valeur “John Smith”	user_metadata.full_name:"John Smith"
Rechercher les utilisateurs provenant d’une connexion précise	identities.connection:"google-oauth2"
Rechercher tous les utilisateurs qui ne se sont jamais connectés	(NOT \_exists_\:logins_count OR logins_count:0)
Rechercher tous les utilisateurs qui se sont connectés avant 2018	last_login:[* TO 2017-12-31]
Rechercher tous les utilisateurs dont la dernière connexion a eu lieu en décembre 2017	last_login:[2017-11 TO 2017-12], last_login:[2017-12-01 TO 2017-12-31]
Rechercher tous les utilisateurs dont le nombre de connexions est >= 100 et <= 200	logins_count:[100 TO 200]
Rechercher tous les utilisateurs dont le nombre de connexions est >= 100	logins_count:[100 TO *]
Rechercher tous les utilisateurs dont le nombre de connexions est > 100 et < 200	logins_count:\{100 TO 200}
Rechercher tous les utilisateurs dont le domaine du courriel est “exampleco.com”	email.domain:"exampleco.com"

​

Limitations

• Le point de terminaison renvoie un maximum de 50 utilisateurs, même si plus de 50 utilisateurs correspondent à votre requête.

• Si vous devez renvoyer plus de 50 utilisateurs, utilisez le paramètre page pour afficher davantage de pages de résultats. Chaque page contient 50 utilisateurs. Par exemple, vous pouvez préciser &page=2 pour afficher les résultats 51 à 100, &page=3 pour afficher les résultats 101 à 150, et ainsi de suite. Toutefois, ce point de terminaison ne renvoie jamais plus de 1000 utilisateurs au total pour les mêmes critères de recherche, même avec la pagination.

• Une limite de 1 Mo par utilisateur s’applique aux données utilisateur pouvant être indexées, interrogées et renvoyées par le point de terminaison de recherche d’utilisateurs. Pour en savoir plus sur l’incidence de cette limite sur les métadonnées personnalisées de plus de 1 Mo, consultez Metadata Field Names and Data Types. Vous devez utiliser le point de terminaison d’obtention d’un utilisateur pour récupérer tous les attributs utilisateur des profils utilisateur qui dépassent cette taille.

• Par défaut, le point de terminaison GET /api/v2/users renvoie les résultats dans un ordre déterministe afin qu’une même requête produise chaque fois les mêmes résultats, dans le même ordre logique. Ce comportement est contrôlé par le paramètre de requête primary_order :

  • primary_order=true (par défaut) : les résultats de requêtes identiques sont systématiquement triés dans le même ordre.
  • primary_order=false : les résultats sont renvoyés dans un ordre non déterministe, ce qui peut améliorer les performances pour les requêtes complexes.

• Si votre application n’a pas besoin d’un ordre cohérent des résultats de recherche et que vos requêtes sont suffisamment courtes pour ne pas dépendre de la pagination, définissez primary_order=false afin d’améliorer les performances des requêtes.

• Si vous avez besoin d’une exportation complète de tous vos utilisateurs, utilisez la tâche d’exportation ou l’extension User Import / Export.

• Si vous obtenez l’erreur 414 Request-URI Too Large, cela signifie que votre chaîne de requête dépasse la longueur prise en charge. Dans ce cas, affinez votre recherche.

Nous ne recommandons pas d’utiliser ce point de terminaison pour :

• Les opérations qui exigent une cohérence immédiate. Utilisez plutôt le point de terminaison Get Users by Email ou le point de terminaison Get Users by ID.
• Les exportations d’utilisateurs. Utilisez plutôt le point de terminaison User Export.
• Les opérations qui exigent une recherche d’utilisateurs dans le cadre de processus d’authentification. Utilisez plutôt le point de terminaison Get Users by Email ou le point de terminaison Get Users by ID.
• La recherche d’utilisateurs pour Account Linking par courriel. Utilisez plutôt le point de terminaison Get Users by Email.

​

En savoir plus

• Syntaxe des requêtes de recherche d’utilisateurs
• Trier les résultats de recherche
• Afficher les résultats de recherche par page
• Exportations groupées d’utilisateurs
• Vérifier les appels d’API