コンテナーとファイルの検索

適用対象: 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 に含め、結果をアプリに限定します。

検索によって返されるコンテナーまたはファイルを開くには、アプリに対応するコンテナーの種類へのアクセス許可が必要です。

次の手順