Utiliser l’API Recherche Microsoft pour rechercher des personnes

Les applications Microsoft Graph peuvent utiliser l’API Recherche Microsoft 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 String
CompanyName String
Service String
displayName String
emailAddress String
givenName String
hitId String
imAddress String
jobTitle String
officeLocation String
personType String
phones String
rank Entier
résumé String
surname String
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 : rechercher une personne par 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"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Prochaines étapes