次の方法で共有

$search クエリ パラメーターを使用する

他の OData クエリ パラメーターに加えて、Microsoft Graph は、$search クエリ パラメーターをサポートして、要求の結果を検索条件と一致するものに制限します。

$search クエリ パラメーターのサポートはエンティティによって異なります。一部では、directoryObject から派生Microsoft Entraリソースなど、高度なクエリでのみ$searchがサポートされます。 この記事では、次の 3 つのメイン領域の検索構文と動作について説明します。

メッセージ コレクションで $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 や他の Microsoft 365 アプリケーション (SharePoint など) では 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 件の結果を返します。

次の要求では、サインインしているユーザーのコレクション ユーザー オブジェクトで "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 は単一のトークンと見なされます: 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 および description のフィールドでのみ動作します。 文字列型の任意のフィールドを $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内でも使用できます。 プロパティに応じて、プロパティで検索がサポートされていない場合、検索動作は "search" または "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"

関連コンテンツ