Microsoft Search API を使用してデータをクエリする
Microsoft Search API を使用して、アプリで Microsoft 365 データをクエリできます。
検索要求は、サインインしているユーザーのコンテキストで実行されます。このユーザーは、委任されたアクセス許可を持つアクセス トークンを使用して識別されます。
一般的なユース ケース
Microsoft Search API には、クエリ 方法が用意されており、Microsoft Searchのデータ中を検索します。います。この方法では、要求本文にsearchRequestを渡し、検索の詳細を定義します。
このセクションでは、 クエリ メソッドの一般的な使用ケースについて、ユーザーが クエリsearchRequest本体で設定するプロパティとパラメーターに基づいて一覧で示します。
検索要求は、ユーザーに代わって実行されます。 検索結果は、アイテムに適用されているアクセス制御をすべて実施できるようにスコープされます。 たとえば、ファイルのコンテキストでは、検索要求の一環としてファイルに対するアクセス許可が評価されます。 ユーザーが検索対象のアイテムにアクセスできるのは、同じアクセス許可とアクセス制御を使用して対応するGETオペレーションから取得できるアイテム数と同じか、それ以下です。
| 使用例 | query 要求本文で定義するプロパティ |
|---|---|
| エンティティ型に基づいた検索の範囲設定 | entityTypes |
| 結果のページング | from および size |
| 最も関連性の高いメールの取得 | enableTopResults |
| 選択したプロパティの取得 | fields |
| クエリ用語での KQL の使用 | query |
| 検索結果の並び替え | 並べ替え |
| 集計を使用して結果を絞り込む | 集計 |
| スペルの修正を要求する | queryAlterationOptions |
| 画面のレイアウトを検索する (プレビュー) | resultTemplateOptions |
エンティティ型に基づいた検索の範囲設定
検索要求の範囲は、query 要求ペイロードで entityTypes プロパティを使用することで定義します。 次の表では、クエリに使用できる型とサポートされているデータへのアクセス許可について説明します。
| EntityType | アイテムにアクセスするために必要なアクセス許可の範囲 | ソース | コメント |
|---|---|---|---|
| message | Mail.Read、Mail.ReadWrite | Exchange Online | 電子メール メッセージ |
| event | Calendars.Read、Calendars.ReadWrite | Exchange Online | カレンダー イベント |
| drive | Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All | SharePoint | ドキュメント ライブラリ。 |
| driveItem | Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All | SharePoint および OneDrive | ファイル、フォルダー、ページ、ニュース。 |
| リスト | Sites.Read.All、Sites.ReadWrite.All | SharePoint および OneDrive | ドキュメント ライブラリもリストとして返されることにご注意ください。 |
| listItem | Sites.Read.All、Sites.ReadWrite.All | SharePoint および OneDrive | アイテムを一覧にする ファイルとフォルダーもリストアイテムとして返されます。listItem は、driveItem のスーパークラスです。 |
| site | Sites.Read.All、Sites.ReadWrite.All | SharePoint | SharePoint のサイト |
検索結果のページング
検索結果の改ページは、query 要求本文で次の 2 つのプロパティを指定することで制御します。
from - ページ上に検索結果をリストするための 0 ベースの開始点を示す整数です。 既定値は 0 です。
size - 1 つのページに返す結果の数を示す整数です。 既定値は 25 件です。 最大値は 1000 件です。
event エンティティまたは message エンティティの検索時には、次の制限がある点に注意してください。
- from は最初のページ要求ではゼロにする必要があります。それ以外の場合は、要求の結果が HTTP 400
Bad requestになります。 - ページ毎の最大結果数 (サイズ) は、メッセージ および イベント に関しては 25 です。
SharePoint または OneDrive のアイテムに上限はありません。 妥当なページサイズは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を使用することと似ています。 動作は、投稿の本文に記載されているため、検索APIは技術的にこのようなクエリオプションをサポートしていません。
これらのエンティティの種類に関しては、フィールド プロパティを指定することにより、返信で返すプロパティの数が少なくなり、通信料金が最適化されます。
listItem および externalItem エンティティは、スキーマに構成されている拡張済みの取得可能フィールドを使用できる唯一のサポートされたエンティティです。 検索 API を使用して、他のすべてのエンティティから拡張プロパティを取得することはできません。 たとえば、検索スキーマで externalItem の取得可能なフィールドを作成した場合、または listItem に取得可能なカスタム列がある場合は、検索からこれらのプロパティを取得できます。 ファイルの拡張プロパティを取得するには、要求に listItem タイプと特定します。
要求に指定されている フィールド がスキーマに存在しないか、取得可能としてマークされない場合は、回答には返されません。 要求の無効なフィールドが無視されます。
要求に フィールド を指定しない場合、すべての種類の既定のプロパティのセットが表示されます。 拡張プロパティの場合、listItem と externalItem は、要求に フィールド が渡されない場合、異なる動作をします。
- listItem は、ユーザー設定フィールドを返しません。
- externalItem は、その特定の接続について、Microsoft Graph のコネクタスキーマの 取得できる 属性を持つすべてのフィールドを返します。
キーワード クエリ言語 (KQL) のサポート
自由形式のテキスト キーワード、演算子 (AND や OR など)、およびプロパティ制限を KQL 構文で実際のクエリ文字列 (query 要求本文の query プロパティ) に指定します。 構文とコマンドは、同じ query 要求本文でターゲットに指定したエンティティ型 (entityTypes プロパティ) によって異なります。
エンティティ型に応じて、検索可能なプロパティが異なります。詳しくは以下をご覧ください:
検索結果を並べ替える
回答の検索結果は、次の既定の並べ替え順序で並べ替えられます。
- メッセージ と イベント は日付順に並べ替えられています。
- すべての SharePoint、OneDrive、およびコネクタ型は、関連度によって並べ替えられています。
クエリメソッドでは、requests パラメーター ( searchRequest オブジェクトのコレクション) に sortProperties を指定して、検索順序をカスタマイズできます。 これにより、1つ以上の並べ替え可能なプロパティと並べ替え順序のリストを指定することができます。
[結果の並べ替え] は現在以下のSharePoint および OneDriveのタイプでのみサポートされています : driveItem、listItem、一覧、サイト
並べ替え句を適用するプロパティは、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、および Microsoft Graph コネクタのexternalItem。
集計を使用して検索結果の精度を向上させ、検索結果を絞り込むための方法については、「検索結果を絞り込む」を参照してください。
スペルの修正を要求する
スペル修正は、ユーザー クエリの入力ミスと一致するコンテンツの正しい単語との不一致を処理する一般的な方法です。 元のユーザー クエリで入力ミスが検出されると、元のユーザー クエリまたは修正された代替クエリの検索結果を取得できます。 searchResponse の queryAlterationResponse プロパティで、入力ミスのスペル修正情報を取得することもできます。
クエリ メソッドの要求本文で、スペル修正のためにクエリに適用する queryAlterationTopions を指定します。 queryAlterationOptions の説明は、searchRequest で定義されています。
スペル修正の使い方の例については、「スペル修正の を要求する」をご覧ください。
画面レイアウトを検索する
検索 API を使用すると、IT 管理者が各コネクタに対して構成した画面レイアウトまたは結果テンプレートを使用して、コネクタから検索結果をレンダリングできます。 結果テンプレートは、レイアウトとデータの意味的に重要な組み合わせのアダプティブ カードです。
searchresponse で結果テンプレートを取得するには、enableResultTemplate プロパティを true に設定する必要があります。これは、searchRequest の resultTemplateOptions で定義されています。 応答には、すべての searchHitに対する resultTemplateId が含まれます。これは、応答の一部である resultTemplates ディクショナリに含まれる画面レイアウトのいずれかにマップされます。
検索結果をレンダリングする方法の例については、「検索画面のレイアウトを使用する」を参照してください。
エラー処理
検索 API は OData エラー オブジェクト定義によって定義されているエラー応答を返します。この応答は、コードとメッセージが格納されている JSON オブジェクトです。
既知の制限
検索 API には、次の制限事項があります。
query メソッドは、同時に 1 つ以上の searchRequest インスタンスが含まれるコレクションを渡せるように定義されています。 ただし、現時点では、サービスによって同時にサポートされる searchRequest は 1 つのみです。
searchRequest リソースは、同時に複数のエンティティ型を渡すことをサポートしています。 ただし、現在サポートされている組み合わせは、SharePoint と OneDrive のエンティティの種類のみです : driveItem、ドライブ、サイト、リスト、listItem。 メッセージ、イベント、SharePoint、OneDrive の種類、externalItem を含む組み合わせは、現在サポートされていません。
contentSource プロパティ (使用する接続を定義するプロパティ) は、entityType が
externalItemとして指定されている場合にのみ適用できます。検索 API は、 メッセージ、 イベント または externalItem のカスタム並べ替えるをサポートしていません。
検索 API は、メッセージ、イベント または サイト または ドライブ の集計をサポートしていません。
SharePoint 検索で、カスタム検索スキーマや検索先などのカスタマイズを行うと、Microsoft Search API の動作を妨げる可能性があります。
関連項目
いくつかの主要なユース ケースの詳細を参照します。
Graph Explorer で検索 API について調べます。
この API セットに関する 最新機能や更新プログラム を検索してください。
フィードバック
フィードバックの送信と表示