Partager via

Utiliser le paramètre de requête $search dans les API Microsoft Graph

Le $search paramètre de requête est un puissant mécanisme de filtrage dans Microsoft Graph qui vous permet de trouver des données spécifiques en correspondant à des critères de recherche.

La prise en charge de ce paramètre de requête varie selon l’entité. Certaines entités, telles que les ressources Microsoft Entra qui dérivent de directoryObject, prennent en charge $search uniquement les requêtes avancées.

Cet article explique comment utiliser efficacement le $search paramètre de requête avec trois types de ressources clés : les messages électroniques, les personnes et les objets Microsoft Entra ID (objets d’annuaire). Vous découvrez les exigences de syntaxe spécifiques, les propriétés prises en charge et les comportements de recherche pour chaque type de ressource.

Utiliser $search sur les collections de messages

Vous pouvez rechercher des messages en fonction de propriétés de message spécifiques. Les résultats de la recherche sont triés par date et heure d’envoi du message. Une $search requête retourne jusqu’à 1 000 résultats.

Lorsque vous recherchez des messages sans spécifier de propriétés de message, la recherche cible ces propriétés par défaut : from, subject et body.

L’exemple suivant renvoie tous les messages de la boîte de réception de l’utilisateur connecté dont l’une des trois propriétés de recherche par défaut contient « pizza » :

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

Vous pouvez également rechercher des messages en spécifiant des noms de propriétés de message que la syntaxe KQL (Keyword Query Language) reconnaît. Ces noms de propriété correspondent aux propriétés définies dans l’entité de message de Microsoft Graph. Outlook et d’autres applications Microsoft 365 comme SharePoint prennent en charge la syntaxe KQL, qui fournit un domaine de découverte commun pour leurs magasins de données.

Propriété de messagerie utilisable dans une requête Description Exemple
attachment Noms des fichiers joints à un e-mail. GET../me/messages?$search="attachment:api-catalog.md"
bcc Champ Cci d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias. GET../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
body Corps d’un message électronique. GET../me/messages?$search="body:excitement"
cc Champ Cc d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias. GET../me/messages?$search="cc:danas"&$select=subject,ccRecipients
from Expéditeur d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias. GET../me/messages?$search="from:randiw"&$select=subject,from

GET../me/messages?$search="from:adelev OR from:alexw OR from: allanD"&$select=subject, from
hasAttachment true si un e-mail contient une pièce jointe qui n’est pas une pièce jointe inline ; false autrement. GET../me/messages?$search="hasAttachments:true"
importance Importance d’un message électronique qu’un expéditeur peut spécifier lors de l’envoi d’un message. Les valeurs possibles sont low, mediumou high. GET../me/messages?$search="importance:high"&$select=subject,importance
kind Type du message. Les valeurs possibles sont contacts, docs, email, faxes, im, meetingsjournals, notesposts, rssfeeds, , tasks, ou voicemail. GET../me/messages?$search="kind:voicemail"
participants Champs De, À, Cc et Cci d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias. GET../me/messages?$search="participants:danas"
received Date à laquelle un destinataire a reçu un e-mail. GET../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipients Champs to, cc et cci d’un e-mail, spécifiés en tant qu’adresse SMTP, nom d’affichage ou alias. GET../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sent Date à laquelle un e-mail a été envoyé par l’expéditeur. GET../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
size Taille d’un élément, en octets. GET../me/messages?$search="size:1..500000"
subject Texte de la ligne d’objet d’un message électronique. GET../me/messages?$search="subject:has"&$select=subject
to Champ À d’un message électronique spécifié en tant qu’adresse SMTP, nom d’affichage ou alias. GET.../me/messages?$search="to:randiw"&$select=subject,toRecipients

Pour plus d’informations sur les propriétés d’e-mail pouvant faire l’objet d’une recherche, la syntaxe KQL, les opérateurs pris en charge et les conseils de recherche, consultez les articles suivants :

Utiliser $search sur les collections de personnes

Vous pouvez appliquer $search aux propriétés displayName et emailAddresses de la ressource person . Les demandes retournent jusqu’à 250 résultats par défaut.

La requête suivante recherche « Irene McGowan » dans la collection d’objets person pour l’utilisateur connecté. Microsoft Graph recherche les propriétés displayName et emailAddresses .

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

L’exemple suivant illustre la réponse.

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

{
    "value": [
       {
           "id": "C0BD1BA1-A84E-4796-9C65-F8A0293741D1",
           "displayName": "Irene McGowan",
           "givenName": "Irene",
           "surname": "McGowan",
           "birthday": "",
           "personNotes": "",
           "isFavorite": false,
           "jobTitle": "Auditor",
           "companyName": null,
           "yomiCompany": "",
           "department": "Finance",
           "officeLocation": "12/1110",
           "profession": "",
           "userPrincipalName": "irenem@contoso.com",
           "imAddress": "sip:irenem@contoso.com",
           "scoredEmailAddresses": [
               {
                   "address": "irenem@contoso.com",
                   "relevanceScore": -16.446060612802224
               }
           ],
           "phones": [
               {
                   "type": "Business",
                   "number": "+1 412 555 0109"
               }
           ],
           "postalAddresses": [],
           "websites": [],
           "personType": {
               "class": "Person",
               "subclass": "OrganizationUser"
           }
       }
   ]
}

Pour en savoir plus sur l’API Contacts, consultez l’article Utiliser l’API Contacts dans Microsoft Graph pour obtenir des informations sur les contacts plus pertinents pour vous.

Utiliser $search sur les collections d’objets de répertoire

Microsoft Entra ID ressources et leurs relations qui dérivent de directoryObject prennent en charge le $search paramètre de requête uniquement dans les requêtes avancées.

Remarque

  • Le paramètre de requête $search n’est actuellement pas disponible dans les clients Azure AD B2C.
  • Il existe un problème connu avec $search les objets de répertoire pour les valeurs qui contiennent un symbole esperluette (&).

L’implémentation de recherche ne prend pas en charge la logique « contains ». Au lieu de cela, il utilise une approche de tokenisation qui extrait les mots des valeurs de propriété et des chaînes de recherche à l’aide d’espaces, de nombres, de casses différentes et de symboles, comme illustré dans ces exemples :

  • Espaces : hello world =>hello, world
  • Casse différente⁽1⁾ : HelloWorld ou helloWORLD =>hello, world
  • Symboles⁽2⁾ : hello.world =>hello, ., , worldhelloworld
  • Nombres : hello123world =>hello, 123, world

⁽1⁾ Pour une casse différente, la création de jetons ne fonctionne actuellement que lorsque la casse passe de minuscules à majuscules. Par exemple, HELLOworld est un jeton unique : helloworldet HelloWORld est deux jetons : hello, world.

⁽2⁾ La logique de tokenisation combine également des mots séparés uniquement par des symboles. Par exemple, recherchez helloworld des hello-world recherches et hello.world.

Après la création de jetons, les jetons sont mis en correspondance indépendamment de la casse d’origine et dans n’importe quel ordre. Par exemple, displayName 李四(David Li) correspond à des chaînes de recherche telles que 李四(David Li), 李四, David, Li, David), , (李四, . Li 李 Une modification de l’alphabet (par exemple, du latin au cyrillique ou au chinois) ne crée pas de jeton. Par exemple, displayName 蓝色group correspond aux 蓝色group chaînes de recherche et 蓝色 , mais pas groupà . DisplayName group蓝色 correspond aux group蓝色 chaînes de recherche et group , mais pas 蓝色 ou 蓝.

La recherche tokenisée fonctionne uniquement sur les champs displayName et description . N’importe quel champ de type de chaîne peut être utilisé dans $search, mais les champs autres que displayName et description sont par défaut de $filterstartswith comportement.

Par exemple :

GET https://graph.microsoft.com/v1.0/groups/?$search="displayName:OneVideo" OR "mail:onevideo"
ConsistencyLevel: eventual

Cela recherche tous les groupes avec des noms d’affichage qui ont one des jetons et video , ou courrier commençant par onevideo.

Vous pouvez utiliser $search avec $filter:

GET https://graph.microsoft.com/v1.0/groups/?$filter=mailEnabled eq true&$search="displayName:OneVideo"
ConsistencyLevel: eventual

Cette opération recherche tous les groupes à extension messagerie dont les noms d’affichage ressemblent à « OneVideo ». Les résultats sont filtrés en fonction d’une conjonction logique (AND) de et $filter de l’ensemble de la requête dans .$search

La syntaxe de recherche suit les règles suivantes :

  • Format général : $search="clause1 » [AND | OR] « clauseX »
  • Nombre de clauses : un nombre quelconque de clauses est pris en charge. Les parenthèses de priorité sont également prises en charge.
  • Syntaxe de clause : «< property> :<text to search> »
    • Vous devez spécifier le nom de la propriété dans la clause .
    • La clause entière doit être placée entre guillemets doubles. S’il contient des guillemets doubles ou une barre oblique inverse, placez-la dans une séquence d’échappement avec une barre oblique inverse. Tous les autres caractères spéciaux doivent être encodés dans une URL.
  • Opérateurs logiques : AND les opérateurs et OR doivent être en dehors des guillemets doubles et en majuscules.
  • Comportement de recherche : la recherche true est prise en charge uniquement pour les propriétés displayName et description . Toute propriété pouvant être utilisée dans $filter peut également être utilisée dans $search. Les propriétés autres que displayName et description sont par défaut $filter avec le comportement « startsWith » si la recherche n’est pas prise en charge.
  • Tokenisation : les entrées de chaîne que vous fournissez dans $search et les propriétés pouvant faire l’objet d’une recherche sont divisées en parties par espaces, différentes casses et types de caractères (nombres et caractères spéciaux).

Le tableau suivant présente quelques exemples :

Classe d’objet Description Exemple
Utilisateur Nom complet du carnet d'adresses de l'utilisateur. GET../users?$search="displayName:Guthr"
Utilisateur Nom complet du carnet d'adresses ou courrier de l'utilisateur. GET../users?$search="displayName:Guthr" OR "mail:Guthr"
Groupe Nom complet du carnet d'adresses ou description du groupe. GET../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")
Group Nom complet du carnet d’adresses dans un groupe à extension messagerie. GET../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"

Contenu connexe