Partager via

Utilisez l’API de personnes dans Microsoft Graph pour obtenir des informations sur les personnes les plus pertinentes pour vous

  • Article

Les applications Graph Microsoft peuvent utiliser l’API de personnes pour récupérer les personnes les plus pertinentes pour un utilisateur. La pertinence est déterminée par les relations professionnelles, ainsi que les modèles de communication et de collaboration de l’utilisateur. Il peut s’agit de contacts locaux ou de l’annuaire d’une organisation, ainsi que de contacts issus de communications récentes.

Parallèlement à la génération de cette information, l’API Contacts fournit également une prise en charge de recherche de correspondances floues et la possibilité de récupérer la liste des utilisateurs pertinents pour un autre utilisateur dans l’organisation de l’utilisateur connexion.

L’API contacts est utile pour les scénarios de sélection de personnes, tels que la composition d’un e-mail ou la création d’une réunion. Par exemple, vous pouvez utiliser l’API personnes dans les scénarios de composition de courrier électronique.

Inclure une personne comme pertinente ou « travailler avec »

Pour qu’une personne soit incluse comme pertinente ou « travaillant avec » un propriétaire de profil dans Delve, qu’elle soit affichée dans la carte de visite du propriétaire ou renvoyée par l’API de personnes, il doit y avoir une relation publique entre la personne et le propriétaire du profil. L’illustration suivante montre un utilisateur A, l’index de relations avec d’autres utilisateurs (utilisateur B) et un profil public montrant un sous-ensemble de relations utilisateur.

Image de l’utilisation des relations

Voici des exemples d'utilisation des relations publiques :

  • Personnes connectées dans l’organigramme : responsable, rapport direct, homologues (partagez le même responsable)
  • Membres d'un groupe public ou d'une liste de distribution de moins de 30 personnes. Les groupes publics disposent de listes de membres qui sont disponibles dans le répertoire.

Si le propriétaire du profil communique avec une personne et qu’il n’existe aucune relation publique entre elle, telle qu’une connexion à un organigramme ou un groupe en commun, le fait qu’elle a communiqué n’est pas visible par d’autres personnes.

Le classement des personnes( c’est-à-dire l’ordre dans lequel elles apparaissent sur la page du propriétaire du profil) est déterminé par la communication publique entre le propriétaire du profil et la personne de la liste.

Voici quelques exemples d’interaction publique :

  • Envoyer ou recevoir des messages électroniques dans le cadre d’un groupe public
  • Inviter des utilisateurs à des réunions dans le cadre du groupe, ou si plus d’un certain nombre X de personnes sont invitées

Le classement ne change pas selon qui est l’utilisateur A (la personne consultant la page d’une autre personne). Le classement est déterminé par le niveau d’interaction entre l’utilisateur B (le propriétaire de profil) et l’utilisateur C (la personne apparaissant dans la liste du propriétaire du profil).

Pour que l’utilisateur C apparaisse, le propriétaire du profil doit se trouver dans un groupe ou une liste de distribution relativement petit avec cet utilisateur public (ce qui signifie que la liste d’appartenances est disponible dans l’annuaire).

Personnes externes au organization ne s’affichent pas dans la liste du propriétaire du profil. Personnes ils ont envoyé un e-mail ou qu’ils rencontrent, mais qui ne font pas partie des mêmes organization, ne s’affichent pas en tant que personnes avec lesquelles le propriétaire travaille.

Désactivation de "working-with" (travailler avec)

Les administrateurs peuvent gérer l’affichage ou le retour des personnes pertinentes pour un propriétaire de profil à deux niveaux :

  • Pour une organisation :
    • Activez pour l’ensemble de l’organisation. Il s’agit du paramètre par défaut.
    • Désactiver pour l’ensemble de l’organisation, autre que le propriétaire du profil
  • Pour un groupe Microsoft Entra dans le organization :
    • Désactivez pour un groupe de Microsoft Entra spécifié. Cela est utile pour activer « working-with » pour un organization, à l’exception des membres du groupe Microsoft Entra.

Pour plus d’informations, voir personnaliser le contrôle de confidentialité des informations personnelles.

Autorisation

Pour appeler l’API contacts dans Microsoft Graph, votre application a besoin des autorisations appropriées :

  • People.Read : permet d’effectuer des appels d’API de personnes générales ; par exemple, https://graph.microsoft.com/v1.0/me/people/ . People.Read requiert le consentement de l’utilisateur final.
  • People.Read.All : nécessaire pour récupérer les contacts les plus pertinents pour un utilisateur spécifié dans les appels (https://graph.microsoft.com/v1.0/users/{id}/people) d’organisation de l’utilisateur connecté. People.Read.All requiert le consentement de l’administrateur.

Parcourir Contacts

Les requêtes de cette section obtiennent les personnes les plus pertinentes pour l’utilisateur connecté (/me) ou pour un utilisateur spécifique dans le organization de l’utilisateur connecté. Ces demandes nécessitent le Personnes. Lecture ou Personnes. Autorisation Read.All respectivement. Par défaut, chaque réponse retourne 10 enregistrements, mais vous pouvez modifier cela à l’aide du paramètre de requête $top .

Obtenir une collection de contacts pertinents

La demande suivante obtient les contacts les plus pertinents pour l’utilisateur connecté (/me), en fonction des relations professionnelles, ainsi que des modèles de communication et de collaboration.

GET https://graph.microsoft.com/v1.0/me/people/

L’exemple suivant illustre la réponse. Par défaut, chaque réponse retourne 10 enregistrements. Vous pouvez modifier cela à l’aide du paramètre de requête $top . Cet exemple utilise $top pour limiter la réponse à trois enregistrements.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Demander une autre page de contacts

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 des pages d’informations supplémentaires. 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/v1.0/me/people/?$top=3&$skip=10

L’exemple suivant illustre la réponse. Par défaut, chaque réponse retourne 10 enregistrements. Vous pouvez modifier cela à l’aide du paramètre de requête $top . Cet exemple utilise $top pour limiter la réponse à trois enregistrements.

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

{
  "value": [
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola",
      "givenName": "Felix",
      "surname": "Coppola",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Legal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2109",
      "profession": "",
      "userPrincipalName": "FelixC@contoso.com",
      "imAddress": "sip:FelixC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "FelixC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0104"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland",
      "givenName": "Lenora",
      "surname": "Rowland",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/1106",
      "profession": "",
      "userPrincipalName": "LenoraR@contoso.com",
      "imAddress": "sip:LenoraR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LenoraR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 954 555 0118"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette",
      "givenName": "Manuel",
      "surname": "Collette",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Accountant II",
      "companyName": null,
      "yomiCompany": "",
      "department": "Finance",
      "officeLocation": "98/2202",
      "profession": "",
      "userPrincipalName": "ManuelC@contoso.com",
      "imAddress": "sip:ManuelC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ManuelC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+20 255501070"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Trier la réponse

Par défaut, les personnes dans la réponse sont triées en fonction de leur pertinence par rapport à votre requête. Vous pouvez modifier l’ordre des personnes dans la réponse à l’aide du paramètre $orderby . Cette requête sélectionne les personnes les plus pertinentes pour vous, les trie par displayName, puis retourne les 10 premières personnes de la liste triée.

GET https://graph.microsoft.com/v1.0/me/people/?$orderby=displayName

L’exemple suivant illustre la réponse. Par défaut, chaque réponse retourne 10 enregistrements. Vous pouvez modifier cela à l’aide du paramètre $top . L’exemple suivant utilise $top pour limiter la réponse à trois enregistrements.

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

{
  "value": [
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos",
      "givenName": "Adriana",
      "surname": "Ramos",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/2111",
      "profession": "",
      "userPrincipalName": "AdrianaR@contoso.com",
      "imAddress": "sip:AdrianaR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AdrianaR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 425 555 0109"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley",
      "givenName": "Alyce",
      "surname": "Cooley",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "131/1104",
      "profession": "",
      "userPrincipalName": "AlyceC@contoso.com",
      "imAddress": "sip:AlyceC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyceC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 858 555 0110"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke",
      "givenName": "Alyssa",
      "surname": "Clarke",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Corporate Security Officer",
      "companyName": null,
      "yomiCompany": "",
      "department": "Operations",
      "officeLocation": "24/1106",
      "profession": "",
      "userPrincipalName": "AlyssaC@contoso.com",
      "imAddress": "sip:AlyssaC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyssaC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 262 555 0106"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Modifier le nombre de contacts et de 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 requête limite également la quantité de données renvoyées à partir du serveur en demandant uniquement le displayName de la personne.

GET https://graph.microsoft.com/v1.0/me/people/?$top=1000&$Select=displayName

L’exemple suivant illustre la réponse.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye"
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman"
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey"
    },
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Roscoe Seidel"
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke"
    },
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos"
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley"
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Wayne Leeper"
    },
    {
      "id": "E7D40AC5-0078-4575-B1F3-F738124C4BC9",
      "displayName": "Jan Travis"
    },
    {
      "id": "6F99D1CC-4FCC-49E4-9160-E8AB01BF3E83",
      "displayName": "Charlotte Delacruz"
    },
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola"
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland"
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette"
    }
  ]
}

Types de résultats inclus

Par défaut, Microsoft Graph fournit des résultats de boîte aux lettres uniquement, qui sont vos contacts enregistrés ou les personnes avec lesquelles vous êtes le plus susceptible d’interagir. Pour récupérer les résultats de l’annuaire au sein de l’organisation, spécifiez un en-tête HTTP, comme illustré ci-dessous.

"X-PeopleQuery-QuerySources: Mailbox,Directory”

Sélectionne 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 @odata.id champ est toujours retourné.

L’exemple suivant limite la réponse au nom complet (displayName) et aux adresses e-mail notées (scoredEmailAddresses) des 10 contacts les plus pertinents.

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses

L’exemple suivant illustre la réponse. Par défaut, chaque réponse retourne 10 enregistrements. Vous pouvez modifier cela à l’aide du paramètre $top . Cet exemple utilise $top pour limiter la réponse à trois enregistrements.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

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 demande suivante limite la réponse aux instances person dont la propriété personType comporte person en tant que classe (class) et organizationUser en tant que sous-classe (subclass).

GET https://graph.microsoft.com/v1.0/me/people/?$filter=personType/class eq 'Person' and personType/subclass eq 'OrganizationUser'

L’exemple suivant illustre la réponse. Par défaut, chaque réponse retourne 10 enregistrements. Vous pouvez modifier cela à l’aide du paramètre $top . Cet exemple utilise $top pour limiter la réponse à trois enregistrements.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Sélectionnez les champs à renvoyer 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 displayName et scoredEmailAddresses des personnes dont le nom d’affichage est égal au nom spécifié. Dans cet exemple, seules les personnes dont le nom d’affichage est égal à « Lorrie Frye » sont renvoyées.

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses&$filter=displayName eq 'Lorrie Frye'

L’exemple suivant illustre la réponse.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

Parcourir des contacts pertinents pour un autre utilisateur

La demande suivante obtient les contacts les plus pertinents pour une autre personne de l’organisation de l’utilisateur connecté, comme décrit dans la section Implémentation de la fonctionnalité travailler avec. Cette demande requiert l’autorisation People.Read.All. Tous les paramètres de requête décrits dans les sections précédentes s’appliquent également.

Dans cet exemple, les contacts pertinents pour Roscoe Seidel sont affichés.

GET https://graph.microsoft.com/v1.0/users('roscoes@contoso.com')/people/

L’exemple suivant illustre la réponse. Par défaut, chaque réponse retourne 10 enregistrements. Vous pouvez modifier cela à l’aide du paramètre $top . L’exemple ci-dessous utilise $top pour limiter la réponse à trois enregistrements.

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

{
  "value": [
    {
      "id": "56155636-703F-47F2-B657-C83F01F49BBC",
      "displayName": "Clifton Clemente",
      "givenName": "Clifton",
      "surname": "Clemente",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Director",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2106",
      "profession": "",
      "userPrincipalName": "CliftonC@contoso.com",
      "imAddress": "sip:CliftonC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "CliftonC@contoso.com",
          "relevanceScore": 20
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BF27D5A-AB4F-4C43-BED0-7DAD9EB0C1C4",
      "displayName": "Sheree Mitchell",
      "givenName": "Sheree",
      "surname": "Mitchell",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/2107",
      "profession": "",
      "userPrincipalName": "ShereeM@contoso.com",
      "imAddress": "sip:ShereeM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ShereeM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0107"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "B3E5302D-EAF0-4E8B-8C6C-A2AE64B4B163",
      "displayName": "Vincent Matney",
      "givenName": "Vincent",
      "surname": "Matney",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Engineering",
      "companyName": null,
      "yomiCompany": "",
      "department": "Engineering",
      "officeLocation": "23/2102",
      "profession": "",
      "userPrincipalName": "VincentM@contoso.com",
      "imAddress": "sip:VincentM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "VincentM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 502 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Rechercher des contacts

Les requêtes de cette section vous permettent de rechercher des personnes pertinentes pour l’utilisateur connecté (/me) et d’autres utilisateurs dans le organization de l’utilisateur connecté. Ces demandes nécessitent le Personnes. Autorisation de lecture, à l’exception de la recherche des personnes concernées par d’autres utilisateurs, qui nécessite Personnes. Read.All. Par défaut, chaque réponse retourne 10 enregistrements, mais vous pouvez le modifier à l’aide du paramètre $top .

Utiliser la recherche pour sélectionner des contacts

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 contacts pertinents pour /me dont le nom d’affichage displayName ou l’adresse e-mail emailAddress contient un mot commençant par la lettre « j ».

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

L’exemple suivant illustre la réponse. Par défaut, chaque réponse retourne 10 enregistrements. Vous pouvez modifier cela à l’aide du paramètre $top . Cet exemple utilise $top pour limiter la réponse à trois enregistrements.

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

{
  "value": [
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Jan Travis",
      "givenName": "Jan",
      "surname": "Travis",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "VP Sales",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "19/3123",
      "profession": "",
      "userPrincipalName": "JanT@contoso.com",
      "imAddress": "sip:JanT@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "JanT@contoso.com",
          "relevanceScore": -12.297347783416837
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 732 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "C43BF05E-5B6B-4DCF-B2FC-0837B09E0FA9",
      "displayName": "Jacob Cazares (TAILSPIN)",
      "givenName": null,
      "surname": null,
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JacobC@tailspintoys.com",
          "relevanceScore": -12.298154282019846
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "PersonalContact"
      }
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Jewell Montgomery",
      "givenName": "Jewell",
      "surname": "Montgomery",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "JewellM@contoso.com",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JewellM@contoso.com",
          "relevanceScore": -12.531408487977451
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Les recherches implémentent un algorithme de correspondance approximative. Ils retournent des résultats basés sur une correspondance exacte et également sur des inférences sur l’intention de la recherche. Par exemple, imaginons que le nom d’affichage d’un utilisateur soit « Tyler Lee » et que son adresse électronique soit tylerle@example.com, et qu’il se trouve dans la collection people de l’utilisateur connecté. Toutes les recherches suivantes renvoient cet utilisateur Tyler comme l’un des résultats.

GET https://graph.microsoft.com/v1.0/me/people?$search="tyler"                //matches both Tyler's name and email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle"              //matches Tyler's email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle@example.com"  //matches Tyler's email. Note the quotes to enclose '@'.
GET https://graph.microsoft.com/v1.0/me/people?$search="tiler"                //fuzzy match with Tyler's name
GET https://graph.microsoft.com/v1.0/me/people?$search="tyler lee"            //matches Tyler's name. Note the quotes to enclose the space.