Microsoft Search API を使用してデータをクエリする
Microsoft Search API を使用して、アプリで Microsoft 365 データをクエリできます。
検索要求は、サインインしているユーザーのコンテキストで実行されます。このユーザーは、委任されたアクセス許可を持つアクセス トークンを使用して識別されます。
一般的なユース ケース
Microsoft Search API には、クエリ 方法が用意されており、Microsoft Searchのデータ中を検索します。います。この方法では、要求本文にsearchRequestを渡し、検索の詳細を定義します。
このセクションでは、クエリsearchRequest 本文で設定したプロパティとパラメーターに基づいて、クエリ メソッドの一般的なユース ケースを示します。
検索要求は、ユーザーに代わって実行されます。 検索結果は、アイテムに適用されているアクセス制御をすべて実施できるようにスコープされます。 たとえば、ファイルのコンテキストでは、検索要求の一環としてファイルに対するアクセス許可が評価されます。 ユーザーが検索対象のアイテムにアクセスできるのは、同じアクセス許可とアクセス制御を使用して対応するGETオペレーションから取得できるアイテム数と同じか、それ以下です。
| 使用例 | query 要求本文で定義するプロパティ |
|---|---|
| エンティティ型に基づいた検索の範囲設定 | entityTypes |
| 結果のページング | from および size |
| 最も関連性の高いメールの取得 | enableTopResults |
| 選択したプロパティの取得 | fields |
| クエリ用語での KQL の使用 | query |
| 検索結果を折りたたむ | collapseProperties |
| 検索結果の並び替え | sortProperties |
| 集計を使用して結果を絞り込む | 集計 |
| スペルの修正を要求する | queryAlterationOptions |
| 画面のレイアウトを検索する (プレビュー) | resultTemplateOptions |
エンティティ型に基づいた検索の範囲設定
検索要求の範囲は、query 要求ペイロードで entityTypes プロパティを使用することで定義します。 次の表では、クエリに使用できる型とサポートされているデータへのアクセス許可について説明します。
| EntityType | アイテムにアクセスするために必要なアクセス許可の範囲 | ソース | コメント |
|---|---|---|---|
| 頭字語 | Acronym.Read.All | Microsoft Search | 組織内の Microsoft Search の頭字語。 |
| bookmark | Bookmark.Read.All | Microsoft Search | 組織内の Microsoft Search のブックマーク。 |
| chatMessage | Chat.Read、Chat.ReadWrite、ChannelMessage.Read.All | Teams | Teams メッセージ。 |
| 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のスーパークラスです。 |
| qna | QnA.Read.All | Microsoft Search | 組織内の Microsoft Search での質問と回答。 |
| 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 項目の上限は 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を使用することと似ています。 動作は、投稿の本文に記載されているため、検索APIは技術的にこのようなクエリオプションをサポートしていません。
これらのエンティティの種類に関しては、フィールド プロパティを指定することにより、返信で返すプロパティの数が少なくなり、通信料金が最適化されます。
listItemおよびexternalItem エンティティは、スキーマに構成されている拡張済みの取得可能フィールドを使用できる唯一のサポートされたエンティティです。 検索 API を使用して、他のすべてのエンティティから拡張プロパティを取得することはできません。 たとえば、検索スキーマで externalItem の取得可能なフィールドを作成した場合、または listItemに取得可能なカスタム列がある場合は、検索からこれらのプロパティを取得できます。 ファイルの拡張プロパティを取得するには、要求に listItemタイプと特定します。
要求に指定されている フィールドがスキーマに存在しないか、取得可能としてマークされない場合は、回答には返されません。 要求の無効なフィールドが無視されます。
要求で フィールド を指定しない場合は、すべての型のプロパティの既定のセットが取得されます。 拡張プロパティの場合、listItem と externalItem は、要求に フィールドが渡されない場合、異なる動作をします。
- listItem は、ユーザー設定フィールドを返しません。
- externalItem は、その特定の接続について、Microsoft Graph のコネクタスキーマの 取得できる 属性を持つすべてのフィールドを返します。
キーワード クエリ言語 (KQL) のサポート
自由形式のテキスト キーワード、演算子 (AND や OR など)、およびプロパティ制限を KQL 構文で実際のクエリ文字列 (query 要求本文の query プロパティ) に指定します。
XRANK 演算子は、クエリに一致する項目を変更することなく、一致式内の特定の用語の出現に基づいて項目の動的ランクを向上させます。 構文とコマンドは、同じ query 要求本文でターゲットに指定したエンティティ型 (entityTypes プロパティ) によって異なります。
エンティティ型に応じて、検索可能なプロパティが異なります。 詳細については、以下を参照してください。
検索結果を折りたたむ
collapseProperties プロパティには、結果を折りたたむ際に使用される条件、フィールド、および制限サイズのセットが応答本文に含まれています。 collapseProperties の使用は、呼び戻しにのみ影響しますが、ランク付け/並べ替えアクションには影響しません。
クエリ メソッドを使用すると、collapseProperty オブジェクトのコレクションである requests パラメーターで collapseProperties を指定することで、collapse プロパティをカスタマイズできます。 これにより、1 つ以上の折りたたみプロパティのセットを指定できます。
現在、結果の折りたたみは、driveItem、listItem、ドライブ、リスト、サイト、externalItem のエンティティの種類でサポートされています。
collapse 句を効果的に使用するには、適用するプロパティをクエリ可能で、並べ替え可能または絞り込み可能である必要があります。
複数レベルの折りたたみを使用する場合は、複数レベルの要求で指定された後続の各プロパティの制限サイズは、前のプロパティと等しいか小さくする必要があることに注意してください。 後続のプロパティの制限サイズが前のプロパティを超えた場合、サーバーは HTTP 400 Bad Request エラーで応答します。
折りたたまれた結果の例については、「検索結果を折りたたむ」を参照してください。
検索結果を並べ替える
回答の検索結果は、次の既定の並べ替え順序で並べ替えられます。
- メッセージ と イベント は日付順に並べ替えられています。
- すべての SharePoint、OneDrive、およびコネクタ型は、関連度によって並べ替えられています。
クエリ メソッドを使用すると、sortProperty オブジェクトのコレクションである requests パラメーターに 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 リソースは、同時に複数のエンティティ型を渡すことをサポートしています。 次の表に、サポートされている組み合わせを示します。
エンティティ型 acronym ブックマーク message chatMessage ドライブ driveItem event externalItem list listItem ユーザー qna サイト acronym True True - - - - - - - - - True - ブックマーク True True - - - - - - - - - True - chatMessage - - - はい - - - - - - - - - ドライブ - - - - True True - True True True - - True driveItem - - - - True True - True True True - - True event - - - - - - はい - - - - - - externalItem - - - - True True - True True True - - True list - - - - True True - True True True - - True listItem - - - - True True - True True True - - True message - - はい - - - - - - - - - - ユーザー - - - - - - - - - - はい - - 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、 イベント、 person、 qna、 externalItem の検索はサポートされていません。
SharePoint 検索のカスタマイズ (カスタム検索スキーマや結果ソースなど) は、Microsoft Search API 操作に干渉する可能性があります。
検索 API では、サイト レベルの 検索スキーマはサポートされていません。 テナント レベルまたは既定の 検索スキーマを使用します。
関連コンテンツ
いくつかの主要なユース ケースの詳細を参照します。
Graph Explorer で検索 API について調べます。
この API セットに関する 最新機能や更新プログラム を検索してください。