適用対象: Developer
アプリで SharePoint Embedded コンテナーまたはコンテンツをキーワード (keyword)検索する必要がある場合は、Microsoft Graph で Microsoft Search を使用します。 検索 API は、一致する結果をランク付けし、コンテナーの drive リソースまたはファイルとフォルダーの driveItem リソースを返します。
注:
SharePoint Embedded 検索はプレビュー段階です。 Microsoft Graph には v1.0 検索 API が用意されていますが、この記事の例で使用される sharePointOneDriveOptions.includeHiddenContent プロパティ はベータ版のみです。 非表示の SharePoint Embedded コンテンツを含めることができるように、これらの要求を /beta 上に保持します。 SharePoint Embedded 検索では、委任されたアクセス許可のみがサポートされ、 例外的なアクセス パターンに従います。
検索範囲を選択する
すべての要求を、アプリに属するコンテナーの種類またはコンテナーにスコープを設定します。 検索はサインイン ユーザーのコンテキストで実行されるため、サービスはユーザーがアクセスできるコンテンツに結果をトリミングします。 また、アプリは、返されたコンテナーまたはファイルを開く前に、対応するコンテナーの種類にアクセスできる必要があります。
queryStringでは、次の管理プロパティを使用します。
| 範囲 | エンティティの種類 | クエリ パターン |
|---|---|---|
| 1 つの種類のすべてのコンテナー | drive |
ContainerTypeId:{containerTypeId} |
| タイトル別の 1 つのコンテナー | drive |
Title:'contoso' AND ContainerTypeId:{containerTypeId} |
| 説明別の 1 つのコンテナー | drive |
Description:'Everything' AND ContainerTypeId:{containerTypeId} |
| 1 つのコンテナー内の Files | driveItem |
Title:'contoso' AND ContainerId:{containerId} |
| Files across a container type | driveItem |
'contoso' AND ContainerTypeId:{containerTypeId} |
アプリケーションが Microsoft 365 のコンテンツ検出可能性をオプトアウトした場合は、要求本文で sharePointOneDriveOptions.includeHiddenContent を [ true ] に設定します。
コンテナーの検索
Microsoft Graph 検索に POST 要求を送信し、 drive リソースを要求します。
POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": ["drive"],
"query": {
"queryString": "ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae"
},
"sharePointOneDriveOptions": {
"includeHiddenContent": true
},
"from": 0,
"size": 25
}
]
}
応答には hitsContainers が含まれます。 各ヒットには、hitId、rank、summary、および@odata.typeが #microsoft.graph.drive のresourceが含まれています。
ファイルとフォルダーを検索する
ユーザーがファイル名またはファイル コンテンツを検索するときに driveItem リソースを要求します。 ユーザーが既にコンテナー内にいる場合は、 ContainerId を使用して特定のコンテナーにスコープを設定します。
{
"requests": [
{
"entityTypes": ["driveItem"],
"query": {
"queryString": "Title:'contoso' AND ContainerId:b!UBoDBcfpTEeInnz0Rlmlsp6EC-DsPN5Kj3uW0fD1mPp9ptYmB71GRpxbhbDlGdb0"
},
"sharePointOneDriveOptions": {
"includeHiddenContent": true
},
"from": 0,
"size": 25
}
]
}
driveItem結果には、id、name、size、createdDateTime、lastModifiedDateTime、parentReference、createdBy、lastModifiedBy、webUrl などのファイル メタデータを含めることができます。
選択したフィールドを返し、並べ替え結果を返す
fields コレクションを使用して、応答で特定の管理プロパティを要求します。
sortProperties は並べ替え可能なプロパティでのみ使用してください。
{
"requests": [
{
"entityTypes": ["driveItem"],
"query": { "queryString": "Everything about contoso" },
"sharePointOneDriveOptions": { "includeHiddenContent": true },
"fields": ["SampleOWSText", "id", "name", "parentReference", "webUrl", "createdDateTime", "lastModifiedDateTime", "size"],
"sortProperties": [
{ "name": "Created", "isDescending": false }
]
}
]
}
from と size を使用して、ランク付けされた結果をページングします。 別のページを要求するかどうかを決定するには、 hitsContainers[].total と hitsContainers[].moreResultsAvailable を読んでください。
カスタム プロパティの検索
コンテナーのカスタム プロパティの場合は、クエリ文字列のカスタム プロパティ名に OWSTEXT を追加します。
customPropertyNameOWSTEXT:customPropertyValue AND ContainerTypeId:498c6855-8f0e-0de7-142e-4e9ff86af9ae
ユーザーがフリーテキスト用語を入力し、コンテナー間での関連性ランク付けが必要な場合は、フルテキスト検索 (上記の /beta/search/query エンドポイント) を使用します。 アプリが関連性ランク付けなしで既知のメタデータ値をフィルター処理する必要がある場合は、検索ではなく直接列挙を使用します。 たとえば、 $filter、 $expand、 $orderby を使用してドライブ項目を照会します。
GET https://graph.microsoft.com/v1.0/drives/{container-id}/items?$filter=startswith(listitem/fields/{column}, '{value}')&$expand=listitem($expand=fields)
コンテナーに 5,000 を超えるアイテムがあり、 $orderby で列挙する場合は、大規模な順序付けの列挙に必要な Prefer: HonorNonIndexedQueriesWarningMayFailRandomly ヘッダーを含めます。
既知の制限
検索によって、サインインしているユーザーのアクセスが強制されますが、アプリの承認ではありません。 結果には、クエリに一致するすべてのコンテナーと項目が含まれます。アプリが使用するコンテナーの種類を許可されていないコンテナーも含まれます。 常に ContainerTypeId を queryString に含め、結果をアプリに限定します。
検索によって返されるコンテナーまたはファイルを開くには、アプリに対応するコンテナーの種類へのアクセス許可が必要です。