Répertorier les personnes

Article
02/01/2024

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.People.GetAsync();

Importante

Microsoft Graph SDK utilisent la version v1.0 de l’API par défaut et ne prennent pas en charge tous les types, propriétés et API disponibles dans la version bêta. Pour plus d’informations sur l’accès à l’API bêta avec le SDK, consultez Utiliser les kits de développement logiciel (SDK) Microsoft Graph avec l’API bêta.

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).



mgc-beta users people list --user-id {user-id}

Importante



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
people, err := graphClient.Me().People().Get(context.Background(), nil)

Importante


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

PersonCollectionResponse result = graphClient.me().people().get();

Importante


const options = {
	authProvider,
};

const client = Client.init(options);

let people = await client.api('/me/people')
	.version('beta')
	.get();

Importante


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->me()->people()->get()->wait();

Importante


Import-Module Microsoft.Graph.Beta.People

# A UPN can also be used as -UserId.
Get-MgBetaUserPerson -UserId $userId

Importante


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.me.people.get()

Importante

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). Recherche demandes 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"

Exécution d’une recherche approximative

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/

Partager via

Répertorier les personnes

Autorisations

Requête HTTP

Paramètres facultatifs de la requête

En-têtes de demande

Corps de la demande

Réponse

Exemples

Parcourir

Demande

Réponse

Demander la page de contacts suivante

Trier la réponse

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

Sélectionner les champs à renvoyer

Utiliser un filtre pour limiter la réponse

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

Rechercher des contacts

Utilisation de la recherche pour sélectionner des personnes

Utiliser la recherche pour spécifier un sujet pertinent

Exécution d’une recherche approximative

Commentaires

Ressources supplémentaires

Partager via

Répertorier les personnes

Autorisations

Requête HTTP

Paramètres facultatifs de la requête

En-têtes de demande

Corps de la demande

Réponse

Exemples

Parcourir

Demande

Réponse

Demander la page de contacts suivante

Trier la réponse

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

Sélectionner les champs à renvoyer

Utiliser un filtre pour limiter la réponse

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

Rechercher des contacts

Utilisation de la recherche pour sélectionner des personnes

Utiliser la recherche pour spécifier un sujet pertinent

Exécution d’une recherche approximative

Personnes associées

Commentaires

Ressources supplémentaires