Redigera

Dela via


Search for DriveItems within a drive

Namespace: microsoft.graph

Search the hierarchy of items for items matching a query. You can search within a folder hierarchy, a whole drive, or files shared with the current user.

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegated (personal Microsoft account) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All
Application Files.Read.All Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Note: This method does not support the Sites.Selected application permission.

HTTP request

GET /drives/{drive-id}/root/search(q='{search-text}')
GET /groups/{group-id}/drive/root/search(q='{search-text}')
GET /me/drive/root/search(q='{search-text}')
GET /sites/{site-id}/drive/root/search(q='{search-text}')
GET /users/{user-id}/drive/root/search(q='{search-text}')

Optional query parameters

This method supports the $expand, $select, $skipToken, $top, and $orderby OData query parameters to customize the response.

Function parameters

Parameter Type Description
q string The query text used to search for items. Values may be matched across several fields including filename, metadata, and file content.

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.

Example

Request

The following example searches for a match for "Contoso Project" across several fields in the signed-in user's drive items.

GET /me/drive/root/search(q='Contoso Project')

Response

This method returns an object containing an collection of DriveItems that match the search criteria. If no items were found, an empty collection is returned.

If there are too many matches the response will be paged and an @odata.nextLink property will contain a URL to the next page of results. You can use the $top query parameter to specify the number of items in the page.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
      {
        "id": "0123456789abc!123",
        "name": "Contoso Project",
        "folder": {},
        "searchResult": { "onClickTelemetryUrl": "https://bing.com/0123456789abc!123" }
      },
      {
        "id": "0123456789abc!456",
        "name": "Contoso Project 2016",
        "folder": {},
        "searchResult": { "onClickTelemetryUrl": "https://bing.com/0123456789abc!456" }
      }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/root/search(query='contoso project')&skipToken=1asdlnjnkj1nalkm!asd"
}

Searching for items a user can access

In addition to searching for items within a drive, your app can search more broadly to include items shared with the current user. To broaden the search scope, use the search method on the Drive resource.

Example

GET /me/drive/search(q='Contoso Project')

Response

Responses when searching from the drive resource may include items outside of the drive (items shared with the current user). These items will include the remoteItem facet to indicate they are stored outside of the target drive.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
      {
        "id": "0123456789abc!123",
        "name": "Contoso Project",
        "folder": {},
        "searchResult": { "onClickTelemetryUrl": "https://bing.com/0123456789abc!123" },
        "remoteItem": { "id": "!23141901", "parentReference": { "driveId": "s!1020101jlkjl12lx" } }
      },
      {
        "id": "0123456789abc!456",
        "name": "Contoso Project 2016",
        "folder": {},
        "searchResult": { "onClickTelemetryUrl": "https://bing.com/0123456789abc!456" }
      }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/root/search(query='contoso project')&skipToken=1asdlnjnkj1nalkm!asd"
}

Error responses

See Error Responses for more information about how errors are returned.