Skip to content

Commit 1a585bb

Browse files
DanipocketDanipocket
authored
Merge pull request #28875 from microsoftgraph/main
Merge to publish.
2 parents e40c35d + 1c5c640 commit 1a585bb

391 files changed

Lines changed: 2124 additions & 720 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎api-reference/beta/api/accessreviewhistorydefinition-list-instances.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,4 +126,4 @@ Content-Type: application/json
126126
}
127127
]
128128
}
129-
```
129+
```

‎api-reference/beta/api/filestoragecontainer-patch-permissions.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
---
2+
title: "Upsert permissions"
3+
description: "Upsert (create or update) up to 10 permissions on a fileStorageContainer in a single request."
4+
author: "RushwantKoppolu"
5+
ms.localizationpriority: medium
6+
ms.subservice: "onedrive"
7+
doc_type: apiPageType
8+
ms.date: 05/11/2026
9+
---
10+
11+
# Upsert permissions
12+
13+
Namespace: microsoft.graph
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Upsert (create or update) up to 10 [permission](../resources/permission.md) objects on a [fileStorageContainer](../resources/filestoragecontainer.md) in a single request. Delta patch allows the caller to perform multiple operations (create, update) on multiple permissions with a single request.
18+
19+
> [!IMPORTANT]
20+
> Permissions added to a [fileStorageContainer](../resources/filestoragecontainer.md) apply to all its [driveItem](../resources/driveitem.md) objects, regardless of any unique or restrictive permissions applied to those items.
21+
22+
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
23+
24+
## Permissions
25+
26+
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](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
27+
28+
<!-- { "blockType": "permissions", "name": "filestoragecontainer_patch_permissions" } -->
29+
[!INCLUDE [permissions-table](../includes/permissions/filestoragecontainer-patch-permissions-permissions.md)]
30+
31+
[!INCLUDE [app-permissions](../includes/sharepoint-embedded-app-permissions.md)]
32+
33+
## HTTP request
34+
35+
<!-- {
36+
"blockType": "ignored"
37+
}
38+
-->
39+
```HTTP
40+
PATCH /storage/fileStorage/containers/{containerId}/permissions
41+
```
42+
43+
## Request headers
44+
45+
|Name|Description|
46+
|:---|:---|
47+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
48+
|Content-Type|application/json. Required.|
49+
50+
## Request body
51+
52+
In the request body, supply a JSON object with the following properties.
53+
54+
|Name|Type|Description|
55+
|:---|:---|:---|
56+
|@context|String|OData annotation that identifies the payload type. Must be set to `#$delta` to signal a delta patch operation. Required.|
57+
|value|[permission](../resources/permission.md) collection|A collection of up to 10 **permission** objects to process. Required.|
58+
59+
Each entry in the **value** collection represents one operation on a [permission](../resources/permission.md). The presence of the **id** property determines how the entry is interpreted. Include the ID of an existing permission to update it, or omit the ID to create a new permission.
60+
61+
Each entry supports the following properties and annotations:
62+
63+
|Name|Type|Description|
64+
|:---|:---|:---|
65+
|id|String|The ID of the existing permission. When the ID is present, the item is treated as an update. When the ID is omitted, the item is treated as a create operation. Optional.|
66+
|grantedToV2|[sharePointIdentitySet](../resources/sharepointidentityset.md)|For user-type permissions, specify the details of the user for this permission. Required for create operations. Don't specify for update operations.|
67+
|roles|String collection|The type of permission to grant. The possible values are: `reader`, `writer`, `manager`, `owner`. Required for both create and update operations.|
68+
|@microsoft.graph.conflictBehavior|String|An annotation parameter that controls behavior when the target identity is already a member of the container with a different role. Possible values are: `fail`, `replace`. The default value is `fail`. Applies only to create operations. Optional.|
69+
70+
The **@microsoft.graph.conflictBehavior** annotation is per item. The default value `fail` causes the item to fail with a per-item `409 Conflict` response code. The value `replace` replaces the existing role for the identity with the role specified in the item, and the item succeeds. Any other value causes the item to fail with a per-item `400 Bad Request` response code.
71+
72+
Update items must not include properties other than ID and roles. The **roles** property is required. Items that violate either rule fail with a per-item `400 Bad Request` response code.
73+
74+
## Response
75+
76+
If successful, this method returns a `200 OK` response code and a collection of [permission](../resources/permission.md) objects in the response body. Permissions that are processed successfully include a **permission** object. Failed items include a **@Core.DataModificationException** annotation with error details.
77+
78+
This API might also return the following error response codes for the entire request:
79+
80+
|HTTP code|Description|
81+
|:---|:---|
82+
|400|Bad request.|
83+
|401|Request lacks valid authentication credentials.|
84+
|403|Provided authentication credentials are valid but insufficient to perform requested operation. Example scenarios: The calling app doesn't have permission to manage permissions for containers of this type, or the calling user has no permissions on this container instance, or their role doesn't allow container permission management.|
85+
|404|Container doesn't exist.|
86+
|423|Container is locked. For example, the container is archived.|
87+
88+
## Examples
89+
90+
### Request
91+
92+
The following example shows a single delta patch request that mixes create and update items in one call. Items without an ID are treated as create operations; items with an ID are treated as update operations. Items that fail are reported inline with a **@Core.DataModificationException** annotation. The remaining items still succeed.
93+
94+
<!-- {
95+
"blockType": "request",
96+
"name": "patch_permissions_beta"
97+
}
98+
-->
99+
```http
100+
PATCH https://graph.microsoft.com/beta/storage/fileStorage/containers/b!ISJs1WRro0y0EWgkUYcktDa0mE8zSlFEqFzqRn70Zwp1CEtDEBZgQICPkRbil_5Z/permissions
101+
Content-Type: application/json
102+
103+
{
104+
"@context": "#$delta",
105+
"value": [
106+
{
107+
"roles": ["reader"],
108+
"grantedToV2": {
109+
"user": {
110+
"userPrincipalName": "alex@contoso.com"
111+
}
112+
}
113+
},
114+
{
115+
"@microsoft.graph.conflictBehavior": "replace",
116+
"roles": ["writer"],
117+
"grantedToV2": {
118+
"user": {
119+
"userPrincipalName": "kate@contoso.com"
120+
}
121+
}
122+
},
123+
{
124+
"roles": ["owner"],
125+
"grantedToV2": {
126+
"user": {
127+
"userPrincipalName": "mike@contoso.com"
128+
}
129+
}
130+
},
131+
{
132+
"id": "X2k6MCMuZnxtZW1iZXJzaGlwfGFsZXhAY29udG9zby5jb20",
133+
"roles": ["manager"]
134+
},
135+
{
136+
"id": "X2k6MCMuZnxtZW1iZXJzaGlwfG5vdGFmb3VuZEBjb250b3NvLmNvbQ",
137+
"roles": ["manager"]
138+
}
139+
]
140+
}
141+
```
142+
143+
### Response
144+
145+
The following example shows the response. The first two create operations succeed. The second operation replaces the existing role for the target user. The third create operation fails because the identity is already a member of the container with a different role. The first update operation succeeds. The second update operation fails because no permission with that ID exists.
146+
147+
>**Note:** The response object shown here might be shortened for readability.
148+
149+
<!-- {
150+
"blockType": "response",
151+
"truncated": true,
152+
"@odata.type": "Collection(microsoft.graph.permission)"
153+
}
154+
-->
155+
```http
156+
HTTP/1.1 200 OK
157+
Content-Type: application/json
158+
159+
{
160+
"@odata.context": "https://graph.microsoft.com/beta/$metadata#storage/fileStorage/containers('b%21ISJs1WRro0y0EWgkUYcktDa0mE8zSlFEqFzqRn70Zwp1CEtDEBZgQICPkRbil_5Z')/permissions/$delta",
161+
"value": [
162+
{
163+
"id": "X2k6MCMuZnxtZW1iZXJzaGlwfGFsZXhAY29udG9zby5jb20",
164+
"roles": [
165+
"reader"
166+
],
167+
"grantedToV2": {
168+
"user": {
169+
"displayName": "Alex Wilson",
170+
"id": "1a2b3c4d-1111-2222-3333-444455556666",
171+
"userPrincipalName": "alex@contoso.com"
172+
}
173+
}
174+
},
175+
{
176+
"id": "X2k6MCMuZnxtZW1iZXJzaGlwfGthdGVAY29udG9zby5jb20",
177+
"roles": [
178+
"writer"
179+
],
180+
"grantedToV2": {
181+
"user": {
182+
"displayName": "Kate Brown",
183+
"id": "2b3c4d5e-2222-3333-4444-555566667777",
184+
"userPrincipalName": "kate@contoso.com"
185+
}
186+
}
187+
},
188+
{
189+
"@Core.DataModificationException": {
190+
"@odata.type": "#Org.OData.Core.V1.DataModificationExceptionType",
191+
"failedOperation": "Create",
192+
"responseCode": 409,
193+
"info": {
194+
"code": "Conflict",
195+
"message": "Conflict: this identity is a [Reader] member of the container and cannot be added to the [Owner] role."
196+
}
197+
},
198+
"id": "00000000-0000-0000-0000-000000000000",
199+
"roles": [
200+
"owner"
201+
],
202+
"grantedToV2": {
203+
"user": {
204+
"userPrincipalName": "mike@contoso.com"
205+
}
206+
}
207+
},
208+
{
209+
"id": "X2k6MCMuZnxtZW1iZXJzaGlwfGFsZXhAY29udG9zby5jb20",
210+
"roles": [
211+
"manager"
212+
],
213+
"grantedToV2": {
214+
"user": {
215+
"displayName": "Alex Wilson",
216+
"id": "1a2b3c4d-1111-2222-3333-444455556666",
217+
"userPrincipalName": "alex@contoso.com"
218+
}
219+
}
220+
},
221+
{
222+
"@Core.DataModificationException": {
223+
"@odata.type": "#Org.OData.Core.V1.DataModificationExceptionType",
224+
"failedOperation": "Update",
225+
"responseCode": 404,
226+
"info": {
227+
"code": "NotFound",
228+
"message": "Item not found."
229+
}
230+
},
231+
"id": "X2k6MCMuZnxtZW1iZXJzaGlwfG5vdGFmb3VuZEBjb250b3NvLmNvbQ"
232+
}
233+
]
234+
}
235+
```

‎api-reference/beta/api/group-list.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ List all the [groups](../resources/group.md) available in an organization, exclu
1919

2020
This operation returns by default only a subset of the more commonly used properties for each group. These _default_ properties are noted in the [Properties](../resources/group.md#properties) section. To get properties that are _not_ returned by default, do a [GET operation](group-get.md) for the group and specify the properties in a `$select` OData query option. The **hasMembersWithLicenseErrors** and **isArchived** properties are an exception and are not returned in the `$select` query.
2121

22+
> [!NOTE]
23+
> This request might have replication delays for groups that were recently created, updated, or deleted. Recently created or updated groups might not appear in results immediately, and recently deleted groups might still appear in results briefly. Retry the request after a brief delay. For more information, see [Designing for Eventual Consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
24+
2225
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
2326

2427
## Permissions

‎api-reference/beta/api/group-post-members.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,14 @@ Namespace: microsoft.graph
1717

1818
Add a member to a security or Microsoft 365 [group](../resources/group.md). When using the API to add multiple members in one request, you can add up to only 20 members.
1919

20+
> [!NOTE]
21+
> This request might have replication delays for groups that were recently created. When a group is created, it can take a short time for the object to fully replicate across Microsoft Entra ID directory replicas. During this window, requests to add members to the group might return a `400 Bad Request` error with the message: *"The source resource object or one of the objects being referenced do not exist."*
22+
>
23+
> To mitigate this behavior:
24+
> - **Retry after a brief delay** — wait a few seconds and retry the request. The delay is typically brief.
25+
>
26+
> For more information, see [Designing for Eventual Consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
27+
2028
[!INCLUDE [groups-allowed-member-types](../../../concepts/includes/groups-allowed-member-types.md)]
2129

2230
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
@@ -80,7 +88,7 @@ When using the `PATCH /groups/{group-id}` syntax, supply a JSON object that cont
8088

8189
## Response
8290

83-
If successful, this method returns a `204 No Content` response code. It returns a `400 Bad Request` response code when the object is already a member of the group or is unsupported as a group member. It returns a `404 Not Found` response code when the object being added doesn't exist. It returns `403 Unauthorized` in one of the following scenarios:
91+
If successful, this method returns a `204 No Content` response code. It returns a `400 Bad Request` response code when the object is already a member of the group, is unsupported as a group member, or when the group was recently created and hasn't fully replicated (error message: *"The source resource object or one of the objects being referenced do not exist."* — retry after a brief delay). It returns a `404 Not Found` response code when the object being added doesn't exist. It returns `403 Forbidden` in one of the following scenarios:
8492
- You're attempting to add a member to a [group that can't be managed through Microsoft Graph](../resources/groups-overview.md#types-of-groups-supported-in-microsoft-graph). This API supports only security and Microsoft 365 groups.
8593
- You're attempting to add a member you don't have permissions to add. Refer to the preceding [Permissions](#permissions) section for the permissions required to add different member types.
8694
- You're attempting to add a member to a role-assignable group and you don't have the required permissions.

‎api-reference/beta/api/group-update.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,14 @@ Namespace: microsoft.graph
1717

1818
Update the properties of a [group](../resources/group.md) object.
1919

20+
> [!NOTE]
21+
> When you use `members@odata.bind` to add members via `PATCH`, this request might have replication delays for groups that were recently created. It can take a short time for the group object to fully replicate across Microsoft Entra ID directory replicas. During this window, requests to add members to the group might return a `400 Bad Request` error with the message: *"The source resource object or one of the objects being referenced do not exist."*
22+
>
23+
> To mitigate this behavior:
24+
> - **Retry after a brief delay** — wait a few seconds and retry the request. The delay is typically brief.
25+
>
26+
> For more information, see [Designing for Eventual Consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
27+
2028
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
2129

2230
## Permissions
@@ -81,6 +89,12 @@ Use this API to manage the [directory, schema, and open extensions](/graph/exten
8189

8290
If successful, this method returns a `204 No Content` response code—except a `200 OK` response code when updating the following properties: **allowExternalSenders**, **autoSubscribeNewMembers**, **hideFromAddressLists**, **hideFromOutlookClients**, **isSubscribedByMail**, **unseenCount**, **welcomeMessageEnabled**.
8391

92+
### Errors
93+
94+
| Status code | Error code | Error message | Description |
95+
|-------------|------------|---------------|-------------|
96+
| `400 Bad Request` | `Request_BadRequest` | "The source resource object or one of the objects being referenced do not exist." | The group was recently created and hasn't fully replicated across all directory replicas. This error is specific to link-write operations (adding members via `members@odata.bind`). Retry the request after a brief delay. |
97+
8498
## Examples
8599

86100
### Example 1: Update display name and description of a group

‎api-reference/beta/api/oauth2permissiongrant-get.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Retrieve the properties of a single delegated permission grant represented by an
1919
An **oAuth2PermissionGrant** represents delegated permissions which have been granted for a client application to access an API on behalf of a signed-in user.
2020

2121
> [!NOTE]
22-
> This request might have replication delays for delegated permission grants that were recently created, updated, or deleted.
22+
> This request might have replication delays for delegated permission grants that were recently created, updated, or deleted. Learn more in [Designing for eventual consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
2323
2424

2525
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]

‎api-reference/beta/api/oauth2permissiongrant-list.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Namespace: microsoft.graph
1717
Retrieve a list of [oAuth2PermissionGrant](../resources/oauth2permissiongrant.md) objects, representing delegated permissions which have been granted for client applications to access APIs on behalf of signed-in users.
1818

1919
> [!NOTE]
20-
> This request might have replication delays for delegated permission grants that were recently created, updated, or deleted. This delay will be minimized if a filter on `clientId` is specified.
20+
> This request might have replication delays for delegated permission grants that were recently created, updated, or deleted. This delay will be minimized if a filter on `clientId` is specified. Learn more in [Designing for eventual consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
2121
2222
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
2323

‎api-reference/beta/api/rbacapplication-list-transitiveroleassignments.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Get the list of direct and transitive [unifiedRoleAssignment](../resources/unifi
2020
For more information, see [Use Microsoft Entra groups to manage role assignments](/azure/active-directory/roles/groups-concept).
2121

2222
> [!NOTE]
23-
> This request might have replication delays for role assignments that were recently created, updated, or deleted.
23+
> This request might have replication delays for role assignments that were recently created, updated, or deleted. Learn more in [Designing for eventual consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
2424
2525
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
2626

‎api-reference/beta/api/serviceprincipal-list-approleassignedto.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Retrieve all clients (users, groups, or client service principals) that have an
1818

1919
For example, if the resource service principal is the service principal for the Microsoft Graph API, this API returns all service principals that have been granted any app-only permissions to Microsoft Graph. If the resource service principal is an application with app roles granted to users and groups, this API returns all the users and groups assigned app roles for this application.
2020

21-
>**Note** This request might have replication delays for app role assignments that were recently granted or removed.
21+
>**Note** This request might have replication delays for app role assignments that were recently granted or removed. Learn more in [Designing for eventual consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
2222
2323
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
2424

‎api-reference/beta/api/serviceprincipal-list-approleassignments.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Retrieve the list of [appRoleAssignment](../resources/approleassignment.md) that
1919
App roles that are assigned to service principals are also known as [application permissions](/azure/active-directory/develop/v2-permissions-and-consent#permission-types). Application permissions can be granted directly by creating app role assignments, or through a [consent experience](/azure/active-directory/develop/application-consent-experience).
2020

2121

22-
>**Note** This request might have replication delays for app role assignments that were recently granted or removed.
22+
>**Note** This request might have replication delays for app role assignments that were recently granted or removed. Learn more in [Designing for eventual consistency for Microsoft Entra](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/).
2323
2424
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
2525

0 commit comments

Comments
 (0)