次の方法で共有

Microsoft Graph API で $search クエリ パラメーターを使用する

$search クエリ パラメーターは、Microsoft Graph の強力なフィルター処理メカニズムであり、検索条件を一致させて特定のデータを検索できます。

このクエリ パラメーターのサポートはエンティティによって異なります。 directoryObject から派生Microsoft Entraリソースなどの一部のエンティティでは、高度なクエリでのみ$searchがサポートされます。

この記事では、メール メッセージ、ユーザー、Microsoft Entra ID オブジェクト (ディレクトリ オブジェクト) という 3 種類の主要なリソースで、$search クエリ パラメーターを効果的に使用する方法について説明します。 リソースの種類ごとに、特定の構文要件、サポートされているプロパティ、および検索動作について説明します。

メッセージ コレクションで$searchを使用する

特定の メッセージ プロパティに基づいてメッセージを検索できます。 検索結果は、メッセージが送信された日時で並べ替えられます。 $search要求では、最大 1,000 件の結果が返されます。

メッセージ プロパティを指定せずにメッセージを検索する場合、検索では、次の既定のプロパティ (from、 subject、 body) が対象になります。

次の例は、サインイン中のユーザーの受信トレイにあるメッセージのうち、既定の 3 つの検索プロパティのいずれかに "pizza" が含まれるメッセージをすべて返します。

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

または、キーワード クエリ言語 (KQL) 構文で認識されるメッセージ プロパティ名を指定して、メッセージを検索することもできます。 これらのプロパティ名は Microsoft Graph の message エンティティで定義したプロパティです。 Outlook や SharePoint などの他の Microsoft 365 アプリケーションでは、データ ストアに共通の検出ドメインを提供する KQL 構文がサポートされています。

検索可能な電子メール プロパティ 説明 例
attachment 電子メール メッセージに添付されたファイルの名前。 GET../me/messages?$search="attachment:api-catalog.md"
bcc SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの bcc フィールド。 GET../me/messages?$search="bcc:samanthab@contoso.com"&$select=subject,bccRecipients
body 電子メール メッセージの本文。 GET../me/messages?$search="body:excitement"
cc SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの cc フィールド。 GET../me/messages?$search="cc:danas"&$select=subject,ccRecipients
from SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの送信者。 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 電子メール メッセージにインライン添付ファイルではない添付ファイルが含まれている場合。それ以外の場合 false 。 GET../me/messages?$search="hasAttachments:true"
importance 送信者がメッセージを送信するときに指定できる電子メール メッセージの重要性。 使用可能な値は、 low、 medium、または highです。 GET../me/messages?$search="importance:high"&$select=subject,importance
kind メッセージの種類。 使用できる値は、 contacts、 docs、 email、 faxes、 im、 journals、 meetings、 notes、 posts、 rssfeeds、 tasks、または voicemailです。 GET../me/messages?$search="kind:voicemail"
participants SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの from、to、cc、bcc フィールド。 GET../me/messages?$search="participants:danas"
received 受信者が電子メール メッセージを受信した日付。 GET../me/messages?$search="received:07/23/2018"&$select=subject,receivedDateTime
recipients SMTP アドレス、表示名、またはエイリアスとして指定された電子メール メッセージの宛先、 cc、 および bcc フィールド。 GET../me/messages?$search="recipients:randiq"&$select=subject,toRecipients,ccRecipients,bccRecipients
sent 送信者から電子メール メッセージが送信された日付。 GET../me/messages?$search="sent:07/23/2018"&$select=subject,sentDateTime
size アイテムのサイズ (バイト数)。 GET../me/messages?$search="size:1..500000"
subject 電子メール メッセージの件名行に含まれるテキスト。 GET../me/messages?$search="subject:has"&$select=subject
to SMTP アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの to フィールド。 GET.../me/messages?$search="to:randiw"&$select=subject,toRecipients

検索可能なメール プロパティ、KQL 構文、サポートされている演算子、検索ヒントの詳細については、次の記事を参照してください。

個人コレクションで$searchを使用する

ユーザー リソースのdisplayName プロパティと emailAddresses プロパティに$searchを適用できます。 要求は、既定で最大 250 件の結果を返します。

次の要求では、サインインしているユーザーの person オブジェクト コレクションで "Irene McGowan" を検索します。 Microsoft Graph では、 displayName プロパティと emailAddresses プロパティが 検索されます。

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

次の例は応答を示しています。

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"
           }
       }
   ]
}

People API の詳細については、「関係する人の情報を取得する」を参照してください。

ディレクトリ オブジェクト コレクションで$searchを使用する

directoryObject から派生するリソースとそのリレーションシップMicrosoft Entra IDは、高度なクエリでのみ$searchクエリ パラメーターをサポートします。

注:

  • $search クエリ パラメーターは現在、Azure AD B2C テナントでは使用できません。
  • アンパサンド (&) シンボルを含む値のディレクトリ オブジェクトの$searchに関する既知の問題があります。

検索の実装では、"contains" ロジックはサポートされていません。 代わりに、次の例に示すように、プロパティ値から単語を抽出し、スペース、数値、異なる大文字と小文字、記号を使用して文字列を検索するトークン化アプローチを使用します。

  • スペース: hello world =>hello、 world
  • 異なる大文字と小文字⁽1⁾: HelloWorld または helloWORLD =>hello、 world
  • シンボル⁽2⁾: hello.world =>hello、 .、 world、 helloworld
  • 数値: hello123world =>hello、 123、 world

⁽1⁾ 大文字と小文字が異なる場合、トークン化は現在、小文字から大文字への大文字と小文字の変更でのみ機能します。 たとえば、 HELLOworld は 1 つのトークンです。 helloworld、 HelloWORld は 2 つのトークンです: hello、 world。

⁽2⁾ Tokenization ロジックでは、シンボルによってのみ区切られた単語も結合されます。 たとえば、 helloworld を検索すると、 hello-world と hello.worldが検索されます。

トークン化後、トークンは元の大文字と小文字に関係なく、任意の順序で照合されます。 たとえば、displayName 李四(David Li) は、 李四(David Li)、 李四、 David、 Li、 David)、 (李四、 Li 李などの検索文字列と一致します。 アルファベットの変更 (ラテン語からキリル文字、中国語など) では、新しいトークンは作成されません。 たとえば、displayName 蓝色group は、 蓝色group と 蓝色 検索文字列と一致しますが、 groupは一致しません。 DisplayName group蓝色 は、 group蓝色 および group 検索文字列と一致しますが、 蓝色 や 蓝は一致しません。

トークン化された検索は 、displayName フィールドと 説明 フィールドでのみ機能します。 $searchでは任意の文字列型フィールドを使用できますが、displayName および description 以外のフィールドは既定で$filterstartswith動作になります。

例:

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

これにより、 one トークンと video トークンを持つ表示名を持つすべてのグループ、または onevideoで始まるメールが検索されます。

$searchは、$filterと共に使用できます。

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

これにより、"OneVideo" のような表示名を持つすべてのメールが有効なグループが検索されます。 結果は、 $filter の論理結合 (AND) と $search内のクエリ全体に基づいてフィルター処理されます。

検索構文は、次の規則に従います。

  • 一般的な形式: $search="clause1" [AND |OR] "clauseX"
  • 句の数: 任意の数の句がサポートされています。 優先順位のかっこもサポートされています。
  • 句構文: "<property>:<text to search>"
    • 句でプロパティ名を指定する必要があります。
    • 句全体を二重引用符で囲む必要があります。 二重引用符または円記号が含まれている場合は、円記号でエスケープします。 その他のすべての特殊文字は URL エンコードされている必要があります。
  • 論理演算子: AND 演算子と OR 演算子は、二重引用符の外側と大文字である必要があります。
  • 検索動作: true 検索は 、displayName プロパティと description プロパティでのみサポートされます。 $filter で使用できるプロパティは $search 内でも使用できます。 検索がサポートされていない場合、 displayName および description 以外のプロパティは既定で "startsWith" 動作で $filter されます。
  • トークン化: $search で指定する文字列入力と検索可能なプロパティの両方が、スペース、異なる大文字と小文字、および文字型 (数字と特殊文字) ごとに部分に分割されます。

次の表に、いくつかの例を示します。

オブジェクト クラス 説明 例
User ユーザーのアドレス帳の表示名。 GET../users?$search="displayName:Guthr"
User ユーザーのアドレス帳の表示名またはメール。 GET../users?$search="displayName:Guthr" OR "mail:Guthr"
Group グループのアドレス帳の表示名または説明。 GET../groups?$search="description:One" AND ("displayName:Video" OR "displayName:Drive")
Group メールが有効なグループのアドレス帳の表示名。 GET../groups?$filter=mailEnabled eq true&$search="displayName:OneVideo"

関連コンテンツ