Microsoft Search API を使用してデータをクエリする
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
Microsoft Search API を使用して、アプリで Microsoft 365 データをクエリできます。
検索要求は、サインインしているユーザーのコンテキストで実行されます。このユーザーは、委任されたアクセス許可を持つアクセス トークンを使用して識別されます。
注意
Microsoft Search API の要求および応答で使用されたリソースの名前が変更されたか、削除された、または廃止されています。 廃止についての詳細は、 「詳細情報」でご確認ください。 検索 API クエリは、以前のいずれかのアプリで適宜更新します。
一般的なユース ケース
Microsoft Search API には、クエリ 方法が用意されており、Microsoft Searchのデータ中を検索します。います。この方法では、要求本文にsearchRequestを渡し、検索の詳細を定義します。
このセクションでは、クエリsearchRequest 本文で設定したプロパティとパラメーターに基づいて、クエリ メソッドの一般的なユース ケースを示します。
検索要求は、ユーザーに代わって実行されます。 検索結果は、アイテムに適用されているアクセス制御をすべて実施できるようにスコープされます。 たとえば、ファイルのコンテキストでは、検索要求の一環としてファイルに対するアクセス許可が評価されます。 ユーザーは、同じアクセス許可とアクセス制御を持つ対応する GET 操作から取得できるアイテムよりも多くのアイテムにアクセスできません。
| ユース ケース | query 要求本文で定義するプロパティ |
|---|---|
| エンティティ型に基づいた検索の範囲設定 | entityTypes |
| 結果のページング | from および size |
| 最も関連性の高いメールの取得 | enableTopResults |
| 選択したプロパティの取得 | fields |
| クエリ用語での KQL の使用 | query |
| 検索結果を折りたたむ | collapseProperties |
| 検索結果の並び替え | sortProperties |
| 集計を使用して結果を絞り込む | 集計 |
| コネクタを使用してインポートされたカスタム タイプを検索する | contentSources |
| スペルの修正を要求する | 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 のスーパー クラスです。 |
| externalItem | ExternalItem.Read.All | Microsoft Graph コネクタの概要 | すべてのコンテンツは、Microsoft Graph コネクタ API によって取得されました。 |
| 人 | People.Read | Exchange Online | 組織内の個人用連絡先と連絡先、またはアドレス指定可能なオブジェクト。 |
| 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 では、動作が POST 本文で表されるため、これらのクエリ オプションは技術的にサポートされていません。
これらのエンティティの種類に関しては、フィールド プロパティを指定することにより、返信で返すプロパティの数が少なくなり、通信料金が最適化されます。
listItem、driveItem、externalItem エンティティは、スキーマで構成された拡張取得可能なフィールドを取得できる唯一のサポートされるエンティティです。 検索 API を使用して、他のすべてのエンティティから拡張プロパティを取得することはできません。 たとえば、検索スキーマで externalItem の取得可能なフィールドを作成した場合、または listItem または driveItem に取得可能なカスタム列がある場合は、検索からこれらのプロパティを取得できます。 ファイルの拡張プロパティを取得するには、要求で listItem または driveItem の種類を指定します。
要求で指定された フィールド がスキーマに存在しないか、取得可能としてマークされていない場合、応答では返されません。 要求の無効なフィールドが無視されます。
要求で フィールド を指定しない場合は、すべての型のプロパティの既定のセットが取得されます。 拡張プロパティの場合、要求でフィールドが渡されない場合、listItem、driveItem、externalItem の動作が異なります。
- listItem はユーザー設定フィールドを返しません。
- driveItem は、空のフィールドを持つ内部 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、 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、および Microsoft Graph コネクタの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 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 では、サイト レベルの 検索スキーマはサポートされていません。 テナント レベルまたは既定の 検索スキーマを使用します。
スキーマ変更の廃止警告
2023 年 8 月 31 日より、Microsoft Graph 名前空間の externalItem リソースのベータ 版は非推奨になります。 今後は、 Microsoft.Graph.ExternalConnectors 名前空間のリソースのバージョンを使用します。 指定した日付より前に名前空間の依存関係を更新してください。 または、v1.0 バージョンの API への移行を検討してください。
ベータ版では、検索要求と応答で使用されるプロパティは名前が変更されたか、削除されています。 ほとんどの場合、次のテーブルに一覧表示されているように、元のプロパティは、廃止されたか、現在のプロパティに変更されています。
既存のアプリを更新して、現在のプロパティ名と型名を使用し、応答で現在のプロパティ名を取得することをお勧めします。 下位互換性のために、元のプロパティと型は 2023 年 9 月 30 日までアクセス可能で機能し、その後削除されます。
| リソース | 種類を変更する | 元の プロパティ | 現在のプロパティ |
|---|---|---|---|
| searchRequest | プロパティの名前を変更する | stored_fields | fields |
| SearchQuery | プロパティの名前を変更する | query_string | QueryString |
| searchQueryString | リソースの廃止 | 該当なし | 該当なし |
| searchHit | プロパティの名前を変更する | _id | hitId |
| searchHit | プロパティの名前を変更する | _score | rank |
| searchHit | プロパティの削除 | _sortField | 該当なし |
| searchHit | プロパティの名前を変更する | _source | resource |
| searchHit | プロパティの名前を変更する | _summary | summary |
| entityTypes | 列挙型の値の名前を変更する | unknownfuturevalue | unknownFutureValue |
関連コンテンツ
いくつかの主要なユース ケースの詳細を参照します。
Graph Explorer で検索 API について調べます。