You can use the Microsoft Search API to query Microsoft 365 data in your apps.
Search requests run in the context of the signed-in user, identified using an access token with delegated permissions.
Common use cases
The Microsoft Search API provides a query method to search across your data in Microsoft Search, where you pass a searchRequest in the request body, defining the specifics of your search.
This section lists the common use cases of the query method, based on the properties and parameters you set in the query searchRequest body.
Search requests run on behalf of the user. Search results are scoped to enforce any access control applied to the items. For example, in the context of files, permissions on the files are evaluated as part of the search request. Users cannot access more items in a search than they can otherwise obtain from a corresponding GET operation with the same permissions and access control.
Scope search based on entity types
Define the scope of the search request using the entityTypes property in the query request payload. The following table describes the types available to query and the supported permissions to access the data.
Page search results
Control pagination of the search results by specifying the following two properties in the query request body:
from - An integer that indicates the 0-based starting point to list search results on the page. The default value is 0.
size - An integer that indicates the number of results to be returned for a page. The default value is 25.
Note the following limits if you're searching the event or message entity:
from must start at zero in the first page request; otherwise, the request results in an HTTP 400 Bad request.
The maximum results per page (size) is 25 for message and event.
There is no upper limit for SharePoint or OneDrive items. A reasonable page size is 200. A larger page size generally incurs higher latency.
Best practices:
Specify a smaller first page in the initial request. For example, specify from as 0, size as 25.
Paginate subsequent pages by updating the from and size properties. You can increase the page size in each subsequent request. The following table shows an example.
Get the most relevant emails
When searching the message entity, specifying enableTopResults as true returns a hybrid list of messages: the first three messages in the response are sorted by relevance; the remaining messages are sorted by date/time.
Get selected properties
When searching an entity type, such as message, event, drive, driveItem, list, listItem, site, externalItem, you can include in the fields property specific entity properties to return in the search results. This is similar to using the OData system query option, $select in REST requests. The search API does not technically support these query options because the behavior is expressed in the POST body.
For all these entity types, specifying the fields property reduces the number of properties returned in the response, optimizing the payload over the wire.
The listItem and externalItem entities are the only supported entities that allow getting extended fields configured in the schema. You cannot retrieve extended properties from all the other entities. For example, if you created a field for externalItem in the search schema, or if you have a custom column on a listItem, you can retrieve these properties from search. To retrieve an extended property on a file, specify the listItem type in the request.
If the fields specified in the request are not present in the schema, they will not be returned in the response. Invalid fields in the request are silently ignored.
If you do not specify any fields in the request, you will get the default set of properties for all types. For extended properties, listItem and externalItem behave differently when no fields are passed in the request:
listItem will not return any custom field.
externalItem will return all the fields marked with the retrievable attribute in the Microsoft Graph connector schema for that particular connection.
Keyword Query Language (KQL) support
Specify free text keywords, operators (such as AND, OR), and property restrictions in KQL syntax in the actual search query string (query property of the query request body). The syntax and command depend on the entity types (in the entityTypes property) you target in the same query request body.
Depending on the entity type, the searchable properties vary. For details, see:
Error handling
The search API returns error responses as defined by OData error object definition, each of which is a JSON object containing a code and a message.
limitations
The search API has the following limitations:
The query method is defined to allow passing a collection of one or more searchRequest instances at once. However, the service currently supports only a single searchRequest at a time.
The searchRequest resource supports passing multiple types of entities at a time. However, currently the only supported combination is for SharePoint and OneDrive entityTypes: driveItem, drive, site, list, listItem. Any combinations involving message, event, SharePoint and OneDrive types , or externalItem are currently not supported.
The contentSource property, which defines the connection to use, is only applicable when entityType is specified as externalItem.
The search API does not support custom sort for message, event or externalItem.
The search API does not support aggregations for message, event, site or drive.
Source: Microsoft