Répertorier les personnes

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Récupérez une liste d’objets de personne classés en fonction de leur pertinence pour l’utilisateur, qui est déterminée par les modèles de communication et de collaboration de l’utilisateur, ainsi que par les relations professionnelles.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) People.Read People.Read.All
Déléguée (compte Microsoft personnel) People.Read Non disponible.
Application People.Read.All Non disponible.

Requête HTTP

GET /me/people
GET /users/{id | userPrincipalName}/people

Paramètres facultatifs de la requête

Cette méthode prend en charge les paramètres de requête OData suivants pour vous aider à personnaliser la réponse.

Nom Valeur Description
$filter string Limite la réponse uniquement aux contacts dont l’enregistrement contient les critères spécifiés.
$orderby string Par défaut, les contacts de la réponse sont triés selon leur pertinence par rapport à votre requête. Vous pouvez modifier l’ordre des contacts dans la réponse à l’aide du paramètre $orderby.
$search string Rechercher des personnes par nom ou alias. Prend en charge la correspondance approximative. Le paramètre fonctionne pour rechercher uniquement les contacts pertinents de l’utilisateur connecté, pas ceux d’autres utilisateurs. Prend également en charge le mot clé topic permettant de rechercher des contacts en fonction de sujets extraits de conversations par e-mail avec cette personne. Pour obtenir des informations et des exemples, consultez la section Effectuer une recherche approximative dans Utiliser l’API Personnes pour obtenir des informations sur les personnes les plus pertinentes pour vous.
$select string Liste de propriétés séparées par des virgules à inclure dans la réponse. Pour des performances optimales, sélectionnez uniquement le sous-ensemble des propriétés nécessaires.
$skip int Ignorez les n premiers résultats, utiles pour la pagination. L’ignorer n’est pas pris en charge lors de l’utilisation de $search.
$top int Nombre maximal de résultats à retourner sur une page de résultats. Pour plus d’informations, consultez paramètre top.

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Accepter application/json

Corps de la demande

N’indiquez pas le corps de la demande pour cette méthode.

Réponse

Si elle réussit, cette méthode renvoie un 200 OK code de réponse et une collection d’objets person dans le corps de la réponse.

Exemples

Parcourir

Les requêtes de cette section obtiennent les personnes les plus pertinentes pour l’utilisateur connecté (/me), en fonction de la communication, de la collaboration et des relations commerciales.

Par défaut, chaque réponse renvoie 10 éléments. Mais vous pouvez modifier ce réglage en utilisant le paramètre $top. Ces demandes nécessitent le Personnes. Autorisation de lecture.

Demande

Voici un exemple de demande par défaut.

GET https://graph.microsoft.com/beta/me/people

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "33b43a5b-87d6-41ec-91f8-a2610048105f",
            "displayName": "Marketing",
            "givenName": null,
            "surname": null,
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "mailboxType": "GroupMailbox",
            "personType": "ModernGroup",
            "userPrincipalName": "",
            "emailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "rank": 30
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "mailboxType": "Mailbox",
            "personType": "Person",
            "userPrincipalName": "IsaiahL@contoso.com",
            "emailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

Demander la page de contacts suivante

Si la première réponse ne contient pas la liste complète des personnes concernées, vous pouvez effectuer une deuxième demande à l’aide de $top et $skip pour demander plus de pages d’informations. Si la demande précédente contient des informations supplémentaires, la demande suivante obtient la page de contacts suivante sur le serveur.

GET https://graph.microsoft.com/beta/me/people/?$top=10&$skip=10

Trier la réponse

Par défaut, les contacts de la réponse sont triés selon leur pertinence par rapport à votre requête. Vous pouvez modifier l’ordre des contacts dans la réponse à l’aide du paramètre $orderby. Cette requête sélectionne les contacts les plus pertinents, les trie par leur nom et renvoie les 10 premiers contacts sur la liste triée.

GET https://graph.microsoft.com/beta/me/people/?$orderby=DisplayName

Modifier le nombre de contacts renvoyés et les champs renvoyés

Vous pouvez modifier le nombre de contacts renvoyés dans la réponse en définissant le paramètre $top.

L’exemple suivant demande les 1 000 personnes les plus pertinentes pour /me. La demande limite également la quantité de données renvoyées du serveur en demandant uniquement le nom complet de la personne.

GET https://graph.microsoft.com/beta/me/people/?$top=1000&$select=DisplayName

Sélectionner les champs à renvoyer

Vous pouvez limiter la quantité de données retournées par le serveur à l’aide du paramètre $select pour choisir un ou plusieurs champs. Le champ @odata.id est toujours renvoyé.

L’exemple suivant limite la réponse aux valeurs DisplayName et EmailAddress des 10 personnes les plus pertinentes.

GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses

Utiliser un filtre pour limiter la réponse

Vous pouvez utiliser le paramètre $filter pour limiter la réponse uniquement aux contacts dont l’enregistrement contient les critères spécifiés.

La requête suivante limite la réponse aux personnes ayant le « Répertoire » source.

GET https://graph.microsoft.com/beta/me/people/?$filter=Sources/Any (source: source/Type  eq 'Directory')

Sélection des champs à retourner dans une réponse filtrée

Vous pouvez combiner les paramètres $select et $filter pour créer une liste personnalisée de contacts pertinents pour l’utilisateur et obtenir uniquement les champs dont votre application a besoin.

L’exemple suivant obtient les valeurs DisplayName et EmailAddress des personnes dont le nom d’affichage est égal au nom spécifié. Dans cet exemple, seuls les contacts dont le nom est « Nestor Kellum » sont renvoyés.

+GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$filter=DisplayName eq 'Nestor Kellum'

Rechercher des contacts

Les requêtes de cette section obtiennent également les personnes les plus pertinentes pour l’utilisateur connecté (/me). Les demandes de recherche nécessitent le Personnes. Autorisation de lecture.

Utilisation de la recherche pour sélectionner des personnes

Utilisez le paramètre $search pour sélectionner des contacts qui répondent à un ensemble de critères.

La requête de recherche suivante renvoie les personnes pertinentes pour /me lesquelles GivenName ou Surname commence par la lettre « j ».

GET https://graph.microsoft.com/beta/me/people/?$search=j

Utiliser la recherche pour spécifier un sujet pertinent

La requête suivante renvoie les personnes pertinentes dont /me le nom contient « ma » et qui ont une association avec « planification des fonctionnalités ».

GET https://graph.microsoft.com/beta/me/people/?$search="ma topic: feature planning"

La requête suivante recherche une personne nommée « Hermaini Hall ». Étant donné qu’il existe une personne nommée « Herminia Hull » pertinente pour l’utilisateur connecté, les informations pour « Herminia Hull » sont retournées.

GET https://graph.microsoft.com/beta/me/people/?$search="hermaini hall"

La requête suivante obtient les personnes les plus pertinentes pour une autre personne dans le organization de l’utilisateur. Cette demande nécessite User.ReadBasic.All pour Personnes. Autorisation Read.All. Dans cet exemple, les personnes pertinentes de Nestor Kellum sont affichées.

GET https://graph.microsoft.com/beta/users('nestork@contoso.com')/people/