Utiliser l’API Microsoft Recherche pour rechercher des personnes
Les applications Microsoft Graph peuvent utiliser l’API Microsoft Recherche 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. Personnes peuvent être des contacts locaux ou à partir de l’annuaire d’un organization ou de personnes provenant de communications récentes.
En plus de générer ces informations, la recherche fournit également la prise en charge de la recherche de correspondance approximative et la possibilité de récupérer la liste des utilisateurs pertinents pour un autre utilisateur dans le organization de l’utilisateur connecté.
API Personnes
Vous pouvez utiliser les API suivantes pour rechercher des personnes à l’intérieur d’un organization.
- /rechercher
- /Personnes
Remarque
Nous recommandons aux utilisateurs d’appeler le /search point de terminaison au lieu du /people point de terminaison. À l’avenir, tous les investissements futurs seront uniquement disponibles dans le point de /search terminaison ; le point de /people terminaison est en mode maintenance.
Propriétés des personnes retournées
L’API people retourne l’ensemble de propriétés suivant.
| Propriété | Type |
|---|---|
| additionalOfficeLocation | Chaîne |
| CompanyName | Chaîne |
| Service | Chaîne |
| displayName | Chaîne |
| emailAddress | Chaîne |
| givenName | Chaîne |
| hitId | Chaîne |
| imAddress | String |
| jobTitle | Chaîne |
| officeLocation | Chaîne |
| personType | Chaîne |
| phones | Chaîne |
| rank | Entier |
| résumé | Chaîne |
| surname | Chaîne |
| userPrincipalName | String |
Types de personnes
Le tableau suivant présente les types de personnes et les sous-types pris en charge dans l’API people.
| Variantes de personnes, de groupes et de salles prises en charge | Détails du type de destinataire | Boîte aux lettres | Répertoire | Personnes type | sous-type Personnes | Notes |
|---|---|---|---|---|---|---|
| Utilisateur de l’organisation | UserMailbox, MailUser | v | v | Personne | OrganizationUser | Utilisateur qui appartient au organization. |
| Utilisateur de l’organisation sans adresse e-mail | Utilisateur | Y (Désactivé par défaut) | Y (Désactivé par défaut) | Personne | OrganizationUser | Utilisateur qui appartient au organization. |
| Contact de l’organisation | MailContact, Contact | N | v | Personne | OrganizationContact | Contact explicitement ajouté à la liste d’adresses globale (GAL) par l’administrateur du locataire, mais qui ne fait pas partie de la organization. |
| Contact privé | Contact | O | S/O | Personne | PersonalContact | Contact créé explicitement par l’utilisateur qui n’appartient pas au organization. Si l’utilisateur ajoute manuellement à ses contacts une partie de la organization, il est toujours classé comme OrganizationUser. |
| Contact privé sans adresse e-mail | Contact | Y (Désactivé par défaut) | S/O | Personne | PersonalContact | Contact créé explicitement par l’utilisateur qui n’appartient pas au organization. Si l’utilisateur ajoute manuellement à ses contacts une partie de la organization, il est toujours classé comme OrganizationUser. |
| Contact implicite à partir de l’historique des communications | Contact | O | S/O | Personne | ImplicitContact | Un contact déduit de l’historique des communications (e-mail et conversation) dont nous n’avons pas suffisamment d’informations pour déterminer s’il s’agit d’une personne, d’un groupe, etc. Sur les comptes professionnels, il s’agit toujours d’un contact de organization externe, car à l’intérieur organization contacts trouvés dans l’historique des communications sont toujours classés comme OrganizationUser. Pour les comptes de consommateurs, tout ce qui n’est pas un PersonalContact est classé comme ImplicitContact. |
| Contact implicite à partir de l’historique des conversations | Contact | O | S/O | Personne | ChatImplicitContact | Identique à ImplicitContact, mais lorsque l’historique des communications provient exclusivement d’une conversation. |
| Room | Rooms | v | v | Autre | Room | |
| Guest | GuestUser | v | v | Autre | Guest | |
| Invité masqué | GuestUser | Y (Désactivé par défaut) | Y (Désactivé par défaut) | Autre | Guest | |
| Groupe moderne | Groupe | v | v | Groupe | UnifiedGroup | Groupe appelé : Groupe Exchange 365, Groupes modernes, Groupes Microsoft 365. Pour plus d’informations sur Groupes Microsoft 365, consultez En savoir plus sur Groupes Microsoft 365. |
| Groupe Teams | Groupe | v | v | Groupe | UnifiedGroup | Identique à Groupes Microsoft 365, mais représente en interne une équipe dans Microsoft Teams. |
| Groupe Teams masqué | Groupe | Y (Désactivé par défaut) | O | Groupe | UnifiedGroup | Groupe Teams masqué. |
| Liste de distribution | Groupe | v | v | Groupe | PublicDistributionList | Liste de distribution Exchange classique ou groupe de sécurité à extension messagerie. |
| Liste de distribution personnelle | Contact | Y (Désactivé par défaut) | S/O | Groupe | PersonalDistributionList | Groupe de distribution virtuel créé par l’utilisateur en tant qu’assistance pour envoyer facilement des e-mails à plusieurs contacts. Utilisé uniquement pour Outlook sur le web composer en tant que fonctionnalité d’expérience utilisateur, non retourné pour les autres appelants. |
| Objet masqué de tout type, à l’exception de l’invité et du groupe Teams | N | N |
Détails de la demande
Rendez les résultats de l’API contacts plus spécifiques en fournissant des détails supplémentaires lorsque vous effectuez une demande. Voici quelques façons de rendre les requêtes plus spécifiques.
Exemple 1 : résultats de boîte aux lettres uniquement
"Provenances": ["Mailbox"]
Exemple 2 : résultats des deux sources
"Provenances": ["Mailbox", "Directory"]
Source des résultats
Personnes résultats proviennent de deux sources, boîte aux lettres ou répertoire. Par défaut, les résultats proviennent des deux sources avec des conflits supprimés, ce qui garantit que les mêmes valeurs ne seront pas retournées.
Remarque : En cas de conflit, les sources d’annuaire sont préférées.
Les résultats de la boîte aux lettres se composent des éléments suivants :
- Personnes qui vous a envoyé un e-mail
- Personnes à qui vous avez envoyé un e-mail
- Personnes que vous avez rencontré
- Personnes avec lequel vous avez eu des conversations Teams
- Personnes dans l’organigramme de votre responsable
- Contacts publics des personnes ci-dessus
Aspects pertinents pour le cas d’usage lorsqu’une source d’annuaire effectue des recherches dans la liste d’adressage globale de Microsoft Entra ID :
- Non applicable aux utilisateurs consommateurs
- Personnes qui ne figurent pas dans la liste d’adressage globale de l’appelant ne seront pas retournés
- Personnes qui sont masqués par le protocole IBP (information barrier protocol) ne seront pas retournés
- Personnes qui sont masqués dans la liste d’adresses ne seront pas retournés
Obtenir plus de résultats
Spécifiez la taille pour obtenir plus de résultats. Par défaut, 25 résultats ou moins sont retournés en fonction des correspondances de la requête de recherche.
"Size": 25
Spécifier l’index minimal pour la pagination
Définissez l’index minimal pour la pagination afin de spécifier la page initiale des résultats. Par défaut, l’index minimal pour la pagination est 0 et le premier résultat est le plus pertinent.
"From": 0
Sélectionne les champs à renvoyer
L’API retourne un ensemble de propriétés par défaut, mais vous pouvez personnaliser une demande pour retourner un nombre spécifique de propriétés. L’exemple suivant limite la réponse aux propriétés DisplayName, EmailAddresses et phones .
"Fields": ["DisplayName", "EmailAddresses", "phones"]
Utiliser un filtre pour limiter la réponse
Utilisez l’objet Filter pour limiter la réponse à des valeurs spécifiques. Les valeurs de filtre possibles sont : PeopleType, PeopleSubType.
Les exemples suivants illustrent les demandes qui utilisent l’objet Filter pour renvoyer des personnes dont l’enregistrement contient les critères spécifiés.
Exemple 1 : Filtrer sur les suggestions des personnes
L’exemple suivant limite la réponse aux seules suggestions de personne. La réponse contient des contacts privés et organization.
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
}
]
},
Exemple 2 : Filtrer les suggestions de personnes dans le organization
L’exemple suivant limite la reponse uniquement aux utilisateurs professionnels.
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
}
]
},
Exemple 3 : Filtrer sur tous les utilisateurs, listes de distribution ou liste de distribution moderne dans le organization
L’exemple suivant limite la réponse à différentes catégories de PeopleSubtype.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "PublicDistributionList"
}
},
{
"Term": {
"PeopleSubtype": "UnifiedGroup"
}
}
]
},
Exemple 4 : Filtrer pour organization les utilisateurs et les salles de réunion
L’exemple suivant limite la réponse aux utilisateurs organization et aux salles de réunion.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Rooms"
}
}
]
},
Exemple 5 : Filtrer pour organization utilisateurs et invités
L’exemple suivant limite la réponse à organization utilisateurs et invités.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
},
Exemple 6 : Combiner plusieurs filtres
L’exemple suivant combine plusieurs filtres pour limiter la réponse aux critères spécifiés.
"Filter": {
"And": [
{
"Or": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleType": "Other"
}
}
]
},
{
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
}
]
},
Demande complète
Exemple : Recherche personne par son nom
La requête suivante obtient les personnes les plus pertinentes pour l’utilisateur connecté, en fonction des modèles de communication et de collaboration et des relations commerciales.
Demande
POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"person"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 25
}
]
}
Réponse
Voici un exemple de réponse, qui contient un message qui correspond au critère de recherche.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.searchResponse",
"value": [
{
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "fc138b85-18ac-48e0-80a4-633ae4b594e0@41f988bf-86f1-53af-91ab-2d7cd034db47",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.person",
"displayName": "Example User",
"givenName": "User",
"surname": "User",
"department": "Finance",
"officeLocation": "London",
"userPrincipalName": "example.user@contoso.com",
"emailAddresses": [
{
"address": "example.user@contoso.com",
"rank": 1
}
],
"phones": [
{
"type": "business",
"number": "+44 (20) 12345678"
}
]
}
}
]
}
]
}
]
}