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

  • [アーティクル]

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

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

注:

$search クエリ パラメーターは現在、Azure AD B2C テナントでは使用できません。

エンドポイント上の式のアンパサンド (&) シンボルのエンコードに $search 関連する既知の v1.0 問題があります。 この問題と推奨される回避策の詳細については、「既知の 問題: エンコードされたアンパサンド (&) 文字でディレクトリ オブジェクトの$searchが失敗する」を参照してください。

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

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

メッセージで検索を行うときに、特定のメッセージ プロパティを指定せずに値のみを指定した場合、検索は既定の検索プロパティである 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
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 アドレス、表示名、エイリアスとして指定されている、電子メール メッセージの to、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 を使用する

Microsoft Graph People API を使用してユーザーに最も関連のある人物を取得できます。 関連性は、ユーザーのコミュニケーションとコラボレーション パターンとビジネス関係によって決まります。 People API では、$search クエリ パラメーターがサポートされています。 $search 要求は最大 250 件まで結果を返します。

person リソースの displayName プロパティと emailAddress プロパティの両方で人物の検索を行います。

次の要求は、サインイン ユーザーの people コレクションに含まれる各ユーザーの displayName プロパティと emailAddress プロパティで、「Irene McGowen」という名前の人物を検索します。 「Irene McGowan」という名前の人物がサインインしているユーザーに関連するため、「Irene McGowan」の情報が返されます。

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 の使用

注:

アンパサンド (&) シンボルを$search含む値のディレクトリ オブジェクトに関連する既知の問題があります。

directoryObject から派生するリソースとそのリレーションシップMicrosoft Entra IDは、高度なクエリでのみクエリ パラメーターを$searchサポートします。 検索の実装では、"contains" ロジックはサポート されていません 。 代わりに、次の例に示すように、スペース、数字、異なる大文字と小文字の区別、記号を使用して、プロパティ値と検索文字列から単語を抽出することによって機能する、トークン化アプローチを使用しています。

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

⁽1⁾ 現在、トークン化は大文字と小文字の区別が小文字から大文字に変更されている場合にのみ機能するためHELLOworld、1 つのトークンと見なされます: helloworld、 HelloWORld は 2 つのトークンです。 helloworld ⁽2⁾ Tokenization ロジックは、シンボルによってのみ区切られた単語も結合します。たとえば、 をhelloworld検索すると、 と がhello.world見つかりますhello-world。

注:

  • トークン化の後、トークンは元の大文字と小文字の区別とは独立に、任意の順序で合致させられます。 たとえば、displayName は李四(David Li)、、、李四、 (李四Li 李DavidDavid)Liなどの李四(David Li)検索文字列と一致します。
  • ラテン語からキリル文字、中国語など、アルファベットの変更では、新しいトークンは作成されません。 たとえば、displayName は 蓝色group および 検索文字列と蓝色一致しますが、検索文字列は一致蓝色groupしませんgroup。displayName は group蓝色 および 検索文字列とgroup一致しますが、 または 蓝は一致group蓝色しません蓝色。
  • トークン化された検索サポートは、displayName および description のフィールドでのみ動作します。 String 型のフィールドは、displayName 以外のフィールドに$search入れることができ、説明の既定値は$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>" です。
  • 句では、プロパティ名を指定する必要があります。 $filter で使用できるプロパティは $search 内でも使用できます。 プロパティで検索がサポートされていない場合、そのプロパティに応じて、検索動作は "search" または "startsWith" のいずれかになります。
  • 句全体を二重引用符で宣言する必要があります。 二重引用符または円マーク (バックスラッシュ) が含まれている場合は、バックスラッシュを使用してエスケープする必要があります。 他のすべての特殊文字は URL エンコードする必要があります。
  • 論理 AND と OR 演算子は二重引用符の外側に配置し、大文字である必要があります。

次の表ではいくつかの例を示します。

オブジェクト クラス 説明 例
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"

$search で指定した文字列入力と検索可能なプロパティはどちらも、スペース、大文字または小文字、文字の種類 (数字と特殊文字) によって分割されます。

関連コンテンツ