Merge pull request #28218 from microsoftgraph/main

Merge to publish.

Author: Danipocket

api-reference/beta/api/restorepoint-search.md

@@ -217,12 +217,13 @@ Content-Type: application/json
 
 {
   "artifactQuery": {
-    "queryExpression": "(Sender -like 'abc@contoso.com') -and (Subject -like '*Check email*' -or Subject -like ' Important') -and (HasAttachment -eq 'true') -and (PitrDumpsterActionTriggeredTime -gt '2024-09-21T08:20:00.0000000Z')",
+    "queryExpression": "(Sender -like 'abc@contoso.com') -and (Subject -like '*Check email*' -or Subject -like ' Important') -and (HasAttachment -eq 'true')",
     "artifactType": "message"
   },
   "protectionUnitIds": ["23014d8c-71fe-4d00-a01a-31850bc5b42a"],
   "protectionTimePeriod": {
-    "startDateTime": "2021-01-01T00:00:00Z"
+    "startDateTime": "2021-01-01T00:00:00Z",
+    "endDateTime": "2021-01-30T00:00:00Z"
   },
   "restorePointPreference": "oldest"
 }

api-reference/beta/resources/artifactquery.md

@@ -14,7 +14,7 @@ Namespace: microsoft.graph
 
 [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
 
-Contains an expression that specifies the criteria for search.
+Contains an expression that specifies the criteria for search. For more information, see [Filtering mailbox artifacts with granular search queries](/graph/concepts/backup-restore-granular-search.md).
 
 ## Properties
 |Property|Type|Description|

api-reference/v1.0/api/driveitem-createlink.md

@@ -56,7 +56,7 @@ The request should be a JSON object with the following properties.
 |   Name       |  Type  |                                 Description                                  |
 | :------------| :----- | :--------------------------------------------------------------------------- |
 | **type**     | string | The type of sharing link to create. Either `view`, `edit`, or `embed`.       |
-| **password** | string | The password of the sharing link that is set by the creator. Optional and OneDrive Personal only.
+| **password** | string | The password of the sharing link set by the creator. Optional and OneDrive Personal only.
 | **expirationDateTime** | string | A String with format of yyyy-MM-ddTHH:mm:ssZ of DateTime indicates the expiration time of the permission. |
 | **retainInheritedPermissions** |  Boolean          | Optional. If `true` (default), any existing inherited permissions are retained on the shared item when sharing this item for the first time. If `false`, all existing permissions are removed when sharing for the first time.  |
 | **scope** | string | Optional. The scope of link to create. Either `anonymous`, `organization`, or `users`. |
@@ -74,11 +74,11 @@ The following values are allowed for the **type** parameter.
 ### Scope types
 
 The following values are allowed for the **scope** parameter.
-If the **scope** parameter is not specified, the default link type for the organization is created.
+If the **scope** parameter isn't specified, the default link type for the organization is created.
 
 | Value          | Description
 |:---------------|:------------------------------------------------------------
-| `anonymous`    | Anyone with the link has access, without needing to sign in. This may include people outside of your organization. Anonymous link support may be disabled by an administrator.
+| `anonymous`    | Anyone with the link has access, without needing to sign in. It may include people outside of your organization. Anonymous link support may be disabled by an administrator.
 | `organization` | Anyone signed into your organization (tenant) can use the link to get access. Only available in OneDrive for Business and SharePoint.
 | `users`        | Share only with people you choose inside or outside the organization.
 
@@ -87,15 +87,17 @@ If the **scope** parameter is not specified, the default link type for the organ
 
 If successful, this method returns a single [Permission](../resources/permission.md) resource in the response body that represents the requested sharing permissions.
 
-The response will be `201 Created` if a new sharing link is created for the item or `200 OK` if an existing link is returned.
+The response is `201 Created` if a new sharing link is created for the item or `200 OK` if an existing link is returned.
 
-## Example
+## Examples
 
-The following example requests a sharing link to be created for the DriveItem specified by {itemId} in the user's OneDrive.
+### Example 1: Creating sharable links
+
+The following example requests a sharing link to be created for the DriveItem specified by {item-id} in the user's OneDrive.
 The sharing link is configured to be read-only and usable by anyone with the link.
 All existing permissions are removed when sharing for the first time if `retainInheritedPermissions` is false.
 
-### Request
+#### Request
 
 
 # [HTTP](#tab/http)
@@ -146,7 +148,7 @@ Content-type: application/json
 
 ---
 
-### Response
+#### Response
 
 <!-- { "blockType": "response", "@odata.type": "microsoft.graph.permission" } -->
 
@@ -170,13 +172,13 @@ Content-Type: application/json
 }
 ```
 
-## Creating company sharable links
+### Example 2: Creating company sharable links
 
 OneDrive for Business and SharePoint support company sharable links.
-These are similar to anonymous links, except they only work for members of the owning organization.
+They are similar to anonymous links, except they only work for members of the owning organization.
 To create a company sharable link, use the **scope** parameter with a value of `organization`.
 
-### Request
+#### Request
 
 
 # [HTTP](#tab/http)
@@ -222,7 +224,7 @@ Content-Type: application/json
 
 ---
 
-### Response
+#### Response
 
 <!-- { "blockType": "response", "@odata.type": "microsoft.graph.permission" } -->
 
@@ -245,14 +247,14 @@ Content-Type: application/json
 }
 ```
 
-## Creating embeddable links
+### Example 3: Creating embeddable links
 
 When using the `embed` link type, the webUrl returned can be embedded in an `<iframe>` HTML element.
 When an embed link is created the `webHtml` property contains the HTML code for an `<iframe>` to host the content.
 
 **Note:** Embed links are only supported for OneDrive personal.
 
-### Request
+#### Request
 
 
 # [HTTP](#tab/http)
@@ -297,7 +299,7 @@ Content-Type: application/json
 
 ---
 
-### Response
+#### Response
 
 <!-- { "blockType": "response", "@odata.type": "microsoft.graph.permission" } -->
 

api-reference/v1.0/api/driveitem-list-thumbnails.md

@@ -68,7 +68,11 @@ This is currently only supported on OneDrive Personal.
 
 If successful, this method returns a `200 OK` response code and collection of [ThumbnailSet](../resources/thumbnailset.md) objects in the response body.
 
-## Example
+## Examples
+
+### Example 1: Retrieve available thumbnails for an item in the current user's OneDrive
+
+#### Request
 
 The following example shows a request which retrieves available thumbnails for an item in the current user's OneDrive.
 
@@ -117,7 +121,7 @@ Any item in a drive can have zero or more thumbnails.
 For example, `/thumbnails?select=medium` retrieves only the medium sized thumbnails.
 
 
-### Response
+#### Response
 
 <!-- { "blockType": "response", "@odata.type": "Collection(microsoft.graph.thumbnailSet)" } -->
 
@@ -137,11 +141,11 @@ Content-type: application/json
 }
 ```
 
-## Get a single thumbnail
+### Example 2: Get a single thumbnail
 
 Retrieve the metadata for a single thumbnail and size by addressing it directly in a request.
 
-### HTTP request
+#### Request
 
 
 # [HTTP](#tab/http)
@@ -181,14 +185,15 @@ GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}
 
 ---
 
-### Path parameters
+##### Path parameters
 
 | Name         | Type   | Description                                                                              |
 |:-------------|:-------|:-----------------------------------------------------------------------------------------|
 | **item-id**  | string | The unique identifier for the item referenced.                                           |
 | **thumb-id** | number | The index of the thumbnail, usually 0-4. If there is a custom thumbnail, its index is 0. |
 | **size**     | string | The size of the thumbnail requested. This can be one of the standard sizes listed below or a custom size. |
 
+#### Response#
 <!-- { "blockType": "response", "@odata.type": "microsoft.graph.thumbnail" } -->
 
 ```http
@@ -202,11 +207,11 @@ Content-Type: application/json
 }
 ```
 
-## Retrieve thumbnail binary content
+### Example 3: Retrieve thumbnail binary content
 
 You can directly retrieve the content of the thumbnail by requesting the **content** property of the thumbnail.
 
-### HTTP request
+#### Request
 
 
 # [HTTP](#tab/http)
@@ -246,7 +251,7 @@ GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content
 
 ---
 
-### Response
+#### Response
 
 The service responds with a redirect to the thumbnail URL.
 
@@ -260,12 +265,12 @@ Location: https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi
 Thumbnail URLs are cache-safe. The URL will change, if the item changes in a way that requires a new thumbnail to be generated.
 
 
-## Getting thumbnails while listing DriveItems
+### Example 4: Getting thumbnails while listing DriveItems
 
 If you are retrieving a list of DriveItem resources to display, you can use the _$expand_ query string parameter to also include the thumbnails for those resources.
 This enables your app to retrieve thumbnails and items in a single request, instead of issuing many requests.
 
-### HTTP request
+#### Request
 
 
 # [HTTP](#tab/http)
@@ -305,7 +310,7 @@ GET /me/drive/items/{item-id}/children?$expand=thumbnails
 
 ---
 
-### Response
+#### Response
 
 The service responses with the list of DriveItems and their thumbnails.
 
@@ -345,8 +350,6 @@ Content-type: application/json
 }
 ```
 
-## Size options
-
 This table defines the possible thumbnail sizes.
 While you can request any arbitrary thumbnail size, the defined values are likely to exist and return a value quickly:
 
@@ -359,11 +362,12 @@ While you can request any arbitrary thumbnail size, the defined values are likel
 | `mediumSquare` | 176x176     | Square Crop  | Small square thumbnail                                               |
 | `largeSquare`  | 800x800     | Square Crop  | Large square thumbnail                                               |
 
-## Requesting custom thumbnail sizes
+### Example 5: Requesting custom thumbnail sizes
 
 In addition to the defined sizes, your app can request a custom thumbnail size by specifying the dimensions of the thumbnail prefixed with `c`.
 For example if your app needs thumbnails that are 300x400, it can request that size like this:
 
+#### Request
 
 # [HTTP](#tab/http)
 <!-- { "blockType": "request", "name": "get-thumbnail-custom-size", "scopes": "files.read", "tags": "service.graph" } -->
@@ -402,6 +406,8 @@ GET /me/drive/items/{item-id}/thumbnails?select=c300x400_crop
 
 ---
 
+#### Response
+
 Which responds with just the custom thumbnail size selected:
 
 <!-- { "blockType": "response", "@odata.type": "Collection(microsoft.graph.thumbnailSet)" } -->
@@ -445,8 +451,7 @@ Thumbnails are not supported on SharePoint Server 2016.
 
 ### Error responses
 
-See [Error Responses][error-response] for more info about
-how errors are returned.
+See [Error Responses][error-response] for more info about how errors are returned.
 
 [error-response]: /graph/errors
 

concepts/backup-restore-granular-search.md

@@ -0,0 +1,60 @@
+---
+title: "Filtering mailbox artifacts with granular search queries"
+description: "Learn how to create granular search expressions to filter mailbox artifacts during backup and restore operations with Microsoft Graph APIs."
+author: "subham-rkb"
+ms.date: 02/04/2026
+ms.localizationpriority: medium
+ms.subservice: "m365-backup-storage"
+---
+
+# Granular search queries for backup and restore APIs
+
+Use granular search queries to filter and search for specific mailbox artifacts when using the Microsoft Graph backup and restore APIs. Granular search enables you to construct precise query expressions to find emails, calendar events, contacts, tasks, and notes based on various criteria such as sender, subject, participants, and attachments.
+
+## Overview
+
+The [artifactQuery](../api-reference/beta/resources/artifactquery.md) resource contains a `queryExpression` property that allows you to specify search criteria for mailbox artifacts. You can combine multiple properties using logical operators to create complex search expressions that filter restore points based on your specific requirements.
+
+## Supported properties
+
+The following table describes the properties you can use in query expressions.
+
+| Property | Description | Value type | Supported operators | Wildcard support |
+|----------|-------------|------------|---------------------|------------------|
+| Subject | The subject of the message or primary searchable string for other item types | String | -like, -and (up to 3) | * (after string) |
+| Sender | Messages from the specified sender | Display name, Alias, SMTP address, or LegacyDN | -like | * (after string) |
+| Participants | Messages with specified recipient in To, Bcc, or Cc fields | Display name, Alias, SMTP address, or LegacyDN | -like, -and (up to 3) | * (after string) |
+| HasAttachment | Whether the message has an attachment | Boolean (true or false) | -eq | No |
+| MessageKind | The mailbox item type for which to search | Enum: Email, Note, Task, Contact, Calendar | -eq | No |
+
+#### Examples
+
+Search for emails from a specific sender with attachments
+
+```
+(Sender -like 'abc@contoso.com') -and (HasAttachment -eq 'true')
+```
+
+Search for emails with specific subject keywords and multiple participants
+
+```
+(Subject -like 'Project Alpha*') -and (Participants -like 'john@contoso.com' -and Participants -like 'sarah@contoso.com')
+```
+
+Search for calendar events organized by a specific user
+
+```
+(MessageKind -eq 'Calendar') -and (Sender -like 'admin@contoso.com')
+```
+
+Search for contacts by name pattern
+
+```
+(MessageKind -eq 'Contact') -and (Subject -like 'Smith*')
+```
+
+Search for emails combining multiple criteria including message type, subject, sender, and attachments
+
+```
+(MessageKind -eq 'Email') -and (Subject -like 'Invoice*') -and (Sender -like 'vendor*') -and (HasAttachment -eq 'true')
+```

concepts/toc.yml

@@ -350,6 +350,8 @@ items:
       href: backup-storage-concept-overview.md
     - name: Managing information barriers for file storage containers
       href: information-barrier-for-file-storage-containers.md
+    - name: Filtering mailbox artifacts with granular search queries
+      href: backup-restore-granular-search.md
     - name: Error codes
       href: backup-storage-error-codes.md
   - name: Calendar