Microsoft Search API を使用してデータをクエリする

Microsoft Search API を使用して、アプリで Microsoft 365 データをクエリできます。

検索要求は、サインインしているユーザーのコンテキストで実行されます。このユーザーは、委任されたアクセス許可を持つアクセス トークンを使用して識別されます。

一般的なユース ケース

Microsoft Search API には、クエリ 方法が用意されており、Microsoft Searchのデータ中を検索します。います。この方法では、要求本文にsearchRequestを渡し、検索の詳細を定義します。

このセクションでは、クエリの searchRequest の本文で設定したプロパティとパラメーターに基づいて、クエリ メソッドの一般的なユースケースを一覧表示します。

検索要求は、ユーザーに代わって実行されます。 検索結果は、アイテムに適用されているアクセス制御をすべて実施できるようにスコープされます。 たとえば、ファイルのコンテキストでは、検索要求の一環としてファイルに対するアクセス許可が評価されます。 ユーザーは、同じアクセス許可とアクセス制御を使用して、対応する GET 操作から取得できるアイテムよりも多くのアイテムに検索でアクセスできません。

エンティティ型に基づいた検索の範囲設定

検索要求の範囲は、query 要求ペイロードで entityTypes プロパティを使用することで定義します。 次の表では、クエリに使用できる型とサポートされているデータへのアクセス許可について説明します。

検索結果のページング

検索結果の改ページは、query 要求本文で次の 2 つのプロパティを指定することで制御します。

• from - ページ上に検索結果をリストするための 0 ベースの開始点を示す整数です。 既定値は 0 です。

• size - 1 つのページに返す結果の数を示す整数です。 既定値は 25 件です。 最大値は 1000 件です。

event エンティティまたは message エンティティの検索時には、次の制限がある点に注意してください。

• from は最初のページ要求ではゼロにする必要があります。それ以外の場合は、要求の結果が HTTP 400 Bad request になります。
• ページ毎の最大結果数 (サイズ) は、メッセージおよびイベントに関しては 25 です。

SharePoint または OneDrive アイテムの上限は 1000 です。 妥当なページサイズは200です。 通常、ページサイズを大きくすると、遅延が大きくなります。

ベスト プラクティス:

• 最初の要求では、小さめのページを指定します。 たとえば、from に 0 を指定し、size に 25 を指定します。

• 後続のページは、from プロパティと size プロパティを更新することで改ページします。 後続の要求のたびに、ページのサイズを拡大できます。 次の表に例を示します。

  ページ	from	size
  1	0	25
  2	25	50
  3	75	75
  4	150	100

最も関連性の高いメールの取得

メッセージ エンティティの検索時に、enableTopResultsをtrue を指定すると、メッセージのハイブリッド リストが返されます。このリストでは、応答の最初の 3 つのメッセージは関連性順に並べ替えられ、残りのメッセージは日付/時間の順に並べ替えられます。

選択したプロパティの取得

メッセージ、イベント、ドライブ、driveItem、一覧、listItem、site、externalItem、または人のようなエンティティの種類を検索するときは、フィールド プロパティに特定のエンティティプロパティを検索結果に含めて返すことができます。 これは、REST リクエストで OData システムのクエリオプション、 $selectを使用することと似ています。 動作は POST 本文で表されるため、検索 API はこれらのクエリ オプションを技術的にサポートしていません。

これらのエンティティの種類に関しては、フィールド プロパティを指定することにより、返信で返すプロパティの数が少なくなり、通信料金が最適化されます。

listItem、driveItem、externalItem エンティティは、スキーマで構成された拡張取得可能フィールドを取得できる唯一のサポートされているエンティティです。 検索 API を使用して、他のすべてのエンティティから拡張プロパティを取得することはできません。 たとえば、検索スキーマで externalItem の取得可能なフィールドを作成した場合、または listItem または driveItem に取得可能なカスタム列がある場合は、検索からこれらのプロパティを取得できます。 ファイルの拡張プロパティを取得するには、要求で listItem または driveItem タイプを指定します。

要求で指定された フィールド がスキーマに存在しない場合、または取得可能としてマークされていない場合、それらのフィールドは応答で返されません。 要求の無効なフィールドが無視されます。

要求に フィールド を指定しない場合は、すべての型の既定のプロパティ セットを取得します。 拡張プロパティの場合、要求でフィールドが渡されない場合、listItem、driveItem、externalItem の動作は異なります。

• listItem はカスタム フィールドを返しません。
• driveItem は、空のフィールドを持つ内部の listItem を返します。
• externalItem は、その特定の接続の Copilot コネクタ スキーマで 取得可能 属性でマークされたすべてのフィールドを返します。

キーワード クエリ言語 (KQL) のサポート

自由形式のテキスト キーワード、演算子 (AND や OR など)、およびプロパティ制限を KQL 構文で実際のクエリ文字列 (query 要求本文の query プロパティ) に指定します。 XRANK 演算子は、クエリに一致する項目を変更せずに、一致式内で特定の用語が出現するように、項目の動的なランクを上げます。 構文とコマンドは、同じ query 要求本文でターゲットに指定したエンティティ型 (entityTypes プロパティ) によって異なります。

エンティティ型に応じて、検索可能なプロパティが異なります。 詳細については、以下を参照してください。

• メール プロパティ
• サイト プロパティ

検索結果を折りたたむ

collapseProperties プロパティには、条件、フィールド、および制限サイズのセットが含まれており、応答本文の結果を折りたたむために使用されます。 collapseProperties を使用すると、再現率にのみ影響し、ランク付けや並べ替えには影響しません。

クエリ メソッドを使用すると、collapseProperty オブジェクトのコレクションである requests パラメーターに collapseProperties を指定することにより、折りたたみプロパティをカスタマイズできます。 これにより、1 つ以上の折りたたみプロパティのセットを指定できます。

現在、結果の折りたたみは、以下のエンティティの種類でサポートされています: driveItem、 listItem、 drive、 list、 site、 externalItem。

折りたたみ句が適用されるプロパティは、クエリ可能であり、並べ替え可能または絞り込み可能である必要があります。 マルチレベル折りたたみの場合、マルチレベル要求で指定された後続の各プロパティ制限サイズは、前のプロパティ制限サイズ以下である必要があります。それ以外の場合、応答は HTTP 400 Bad Request エラーを返します。

結果を折りたたむ方法を示す例については、「 検索結果を折りたたむ」を参照してください。

検索結果を並べ替える

回答の検索結果は、次の既定の並べ替え順序で並べ替えられます。

• メッセージ と イベント は日付順に並べ替えられています。
• すべての SharePoint、OneDrive、およびコネクタ型は、関連度によって並べ替えられています。

クエリ メソッドを使用すると、sortProperty オブジェクトのコレクションである requests パラメーターに sortProperties を指定することで、検索順序をカスタマイズできます。 これにより、1つ以上の並べ替え可能なプロパティと並べ替え順序のリストを指定することができます。

結果の並べ替えは、現在、SharePoint および OneDrive の種類 driveItem、 listItem、 list、 site でのみサポートされています。

並べ替え句が適用されるプロパティは、SharePoint 検索スキーマで並べ替え可能である必要があります。 要求に指定されたプロパティが並べ替えられない場合、または存在しない場合、応答はエラー HTTP 400 Bad Request を返します。 sortProperty を使用して、関連性でドキュメントを並べ替えるように指定することはできません。

sortProperty オブジェクトの 名前 を指定する場合は、Microsoft Graph の種類 (たとえば、driveItem注の種類)、または検索インデックスの管理プロパティの名前を使うことができます。

結果を並べ替える方法の例については、検索結果を並び替える を参照してください。

集計を使用して結果を絞り込む

集計 (SharePoint では絞り込み条件とも呼ばれます) は、検索エクスペリエンスを強化するための一般的な方法です。 結果に加えて、検索結果の一致するセットについて、ある程度の集計情報が提供されます。 たとえば、クエリに一致するドキュメントの最も代表的な作成者と、最も代表的なァイルの種類などの情報を提供できます。

searchRequestで、検索結果以外に追加して返される必要がある集計を指定します。 各集計の説明は、aggregationOptionで定義されています。これにより、集計を計算する必要があるプロパティ、回答に返される searchBucket の数を指定します。

集計を必要とするプロパティは、SharePoint 検索スキーマで並べ替え可能である必要があります。 指定されたプロパティが絞り込まれない場合、または存在しない場合、応答は HTTP 400 Bad Request を返します。

searchBucket オブジェクトのコレクションを含む応答が返されたら、検索要求を 1 つの searchBucket に含まれる一致する要素のみに絞り込むことができます。 これを行うには、後続の searchRequest の aggregationFilters プロパティの aggregationsFilterToken 値を返します。

集計は現在、SharePoint と OneDrive の種類の絞り込み可能なプロパティでサポートされています: driveItem、 listItem、 list、 site、および on Copilot コネクタの externalItem。

集計を使用して検索結果を拡大および縮小する例については、「 検索 結果を絞り込む」を参照してください。

スペルの修正を要求する

スペル修正は、ユーザー クエリの入力ミスと一致するコンテンツの正しい単語との不一致を処理する一般的な方法です。 元のユーザー クエリで入力ミスが検出されると、元のユーザー クエリまたは修正された代替クエリの検索結果を取得できます。 searchResponse の queryAlterationResponse プロパティで、入力ミスのスペル修正情報を取得することもできます。

searchRequest で、スペル修正のためにクエリに適用する queryAlterationTopions を指定します。 queryAlterationOptions プロパティの詳細については、「searchAlterationOptions」を参照してください。

スペル修正の使い方の例については、「スペル修正の を要求する」をご覧ください。

画面レイアウトを検索する

検索 API を使用すると、IT 管理者が各コネクタに対して構成した画面レイアウトまたは結果テンプレートを使用して、コネクタから検索結果をレンダリングできます。 結果テンプレートは、レイアウトとデータの意味的に重要な組み合わせのアダプティブ カードです。

searchResponse で結果テンプレートを取得するには、true を enableResultTemplate プロパティに設定する必要があります。これは、searchRequest の resultTemplateOptions で定義されています。 応答には、すべての検索ヒットに対する resultTemplateId が含まれます。これは、応答に含まれる resultTemplates ディクショナリに含まれる画面レイアウトのいずれかにマップされます。

画面レイアウトの検索を使用するページの例を参照してください。

ゲスト検索

Search API を使用すると、ゲスト ユーザーは SharePoint または OneDrive 内で共有されているアイテムを検索できます。 ゲスト ユーザーの一覧にアクセスするには、Microsoft 365 管理センターに移動し、左側のナビゲーションで [ユーザー]、[ゲスト ユーザー] の順に選択します。

エラー処理

検索 API は OData エラー オブジェクト定義によって定義されているエラー応答を返します。この応答は、コードとメッセージが格納されている JSON オブジェクトです。

既知の制限

検索 API には、次の制限事項があります。

• query メソッドは、同時に 1 つ以上の searchRequest インスタンスが含まれるコレクションを渡せるように定義されています。 ただし、現時点では、サービスによって同時にサポートされる searchRequest は 1 つのみです。

• searchRequest リソースは、同時に複数のエンティティ型を渡すことをサポートしています。 次の表は、サポートされている組み合わせの一覧です。

  エンティティの種類	acronym	ブックマーク	message	chatMessage	ドライブ	driveItem	event	externalItem	list	listItem	ユーザー	qna	サイト
  acronym	True	True	-	-	-	-	-	-	-	-	-	True	-
  ブックマーク	True	True	-	-	-	-	-	-	-	-	-	True	-
  chatMessage	-	-	-	True	-	-	-	-	-	-	-	-	-
  ドライブ	-	-	-	-	True	True	-	True	True	True	-	-	True
  driveItem	-	-	-	-	True	True	-	True	True	True	-	-	True
  event	-	-	-	-	-	-	True	-	-	-	-	-	-
  externalItem	-	-	-	-	True	True	-	True	True	True	-	-	True
  list	-	-	-	-	True	True	-	True	True	True	-	-	True
  listItem	-	-	-	-	True	True	-	True	True	True	-	-	True
  message	-	-	True	-	-	-	-	-	-	-	-	-	-
  ユーザー	-	-	-	-	-	-	-	-	-	-	True	-	-
  qna	True	True	-	-	-	-	-	-	-	-	-	True	-
  サイト	-	-	-	-	True	True	-	True	True	True	-	-	True

• contentSource プロパティ (使用する接続を定義するプロパティ) は、entityType が externalItem として指定されている場合にのみ適用できます。

• 検索 API では、 頭字語、 ブックマーク、 メッセージ、 chatMessage、 イベント、 person、 qna、または externalItem のカスタム並べ替えはサポートされていません。

• 検索 API は、 頭字語、 ブックマーク、 メッセージ、 イベント、 サイト、 ユーザー、 qna、 またはドライブの集計をサポートしていません。

• 検索 API では、 頭字語、 ブックマーク、 メッセージ、 chatMessage、 イベント、 person、 qna、または externalItem の xrank はサポートされていません。

• ゲスト検索では、 頭字語、 ブックマーク、 メッセージ、 chatMessage、 イベント、 ユーザー、 qna、または externalItem の検索はサポートされていません。

• カスタム検索スキーマや検索先などの SharePoint 検索のカスタマイズは、Microsoft Search API 操作に干渉する可能性があります。

• 検索 API は、サイトレベルの 検索スキーマをサポートしていません。 テナント レベルまたは既定の 検索スキーマを使用します。

スキーマ変更の廃止警告

2023 年 8 月 31 日以降、Microsoft Graph 名前空間のベータ版 externalItem リソースは非推奨になります。 その後は、 Microsoft.Graph.ExternalConnectors 名前空間のリソースのバージョンを使用します。 指定した日付より前に名前空間の依存関係を更新してください。 または、API の v1.0 バージョンへの移行を検討してください。

ベータ版では、検索要求と応答で使用されるプロパティは名前が変更されたか、削除されています。 ほとんどの場合、次のテーブルに一覧表示されているように、元のプロパティは、廃止されたか、現在のプロパティに変更されています。

既存のアプリを更新して、現在のプロパティ名と型名を使用し、応答で現在のプロパティ名を取得することをお勧めします。 下位互換性を確保するため、元のプロパティと型は 2023 年 9 月 30 日までアクセス可能で機能しており、その後は削除されます。

関連コンテンツ

• いくつかの主要なユース ケースの詳細を参照します。

  • Teams メッセージを検索する
  • Outlook のメッセージを検索する
  • 予定表のイベントを検索する
  • 人の検索
  • OneDrive と SharePoint でコンテンツを検索する
  • コネクタを使用してインポートされたカスタム タイプを検索する
  • 検索結果を折りたたむ
  • 検索結果の並び替え
  • 検索結果を絞り込む
  • スペルの修正を要求する
  • 画面レイアウトの検索を使用する
  • アプリケーションのアクセス許可で検索する
  • XRANK 検索結果
  • インタリーブ結果の検索

• Graph Explorer で検索 API について調べます。