Upsert permissions

Namespace: microsoft.graph

Upsert (create or update) up to 10 permission objects on a fileStorageContainer in a single request. Delta patch allows the caller to perform multiple operations (create, update) on multiple permissions with a single request.

This API is available in the following national cloud deployments.

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.

In addition to Microsoft Graph permissions, your app also must have the necessary container-type level permission or permissions to call this API. For details about container types, see Container Types. To learn more about container-type level permissions, see SharePoint Embedded Authorization.

HTTP request

PATCH /storage/fileStorage/containers/{containerId}/permissions

Request headers

Request body

In the request body, supply a JSON object with the following properties.

Each entry in the value collection represents one operation on a permission. 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.

Each entry supports the following properties and annotations:

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.

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.

Response

If successful, this method returns a 200 OK response code and a collection of permission objects in the response body. Permissions that are processed successfully include a permission object. Failed items include a @Core.DataModificationException annotation with error details.

This API might also return the following error response codes for the entire request:

Examples

Request

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.

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containers/b!ISJs1WRro0y0EWgkUYcktDa0mE8zSlFEqFzqRn70Zwp1CEtDEBZgQICPkRbil_5Z/permissions
Content-Type: application/json

{
  "@context": "#$delta",
  "value": [
    {
      "roles": ["reader"],
      "grantedToV2": {
        "user": {
          "userPrincipalName": "alex@contoso.com"
        }
      }
    },
    {
      "@microsoft.graph.conflictBehavior": "replace",
      "roles": ["writer"],
      "grantedToV2": {
        "user": {
          "userPrincipalName": "kate@contoso.com"
        }
      }
    },
    {
      "roles": ["owner"],
      "grantedToV2": {
        "user": {
          "userPrincipalName": "mike@contoso.com"
        }
      }
    },
    {
      "id": "X2k6MCMuZnxtZW1iZXJzaGlwfGFsZXhAY29udG9zby5jb20",
      "roles": ["manager"]
    },
    {
      "id": "X2k6MCMuZnxtZW1iZXJzaGlwfG5vdGFmb3VuZEBjb250b3NvLmNvbQ",
      "roles": ["manager"]
    }
  ]
}

Response

The following example shows the response. The first two create items succeed (the second item replaces the existing role for the target user). The third create item fails because the identity is already a member of the container with a different role. The first update item succeeds; the second fails because no permission with that id exists.

Note: The response object shown here might be shortened for readability.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#storage/fileStorage/containers('b%21ISJs1WRro0y0EWgkUYcktDa0mE8zSlFEqFzqRn70Zwp1CEtDEBZgQICPkRbil_5Z')/permissions/$delta",
  "value": [
    {
      "id": "X2k6MCMuZnxtZW1iZXJzaGlwfGFsZXhAY29udG9zby5jb20",
      "roles": [
        "reader"
      ],
      "grantedToV2": {
        "user": {
          "displayName": "Alex Wilson",
          "id": "1a2b3c4d-1111-2222-3333-444455556666",
          "userPrincipalName": "alex@contoso.com"
        }
      }
    },
    {
      "id": "X2k6MCMuZnxtZW1iZXJzaGlwfGthdGVAY29udG9zby5jb20",
      "roles": [
        "writer"
      ],
      "grantedToV2": {
        "user": {
          "displayName": "Kate Brown",
          "id": "2b3c4d5e-2222-3333-4444-555566667777",
          "userPrincipalName": "kate@contoso.com"
        }
      }
    },
    {
      "@Core.DataModificationException": {
        "@odata.type": "#Org.OData.Core.V1.DataModificationExceptionType",
        "failedOperation": "Create",
        "responseCode": 409,
        "info": {
          "code": "Conflict",
          "message": "Conflict: this identity is a [Reader] member of the container and cannot be added to the [Owner] role."
        }
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "roles": [
        "owner"
      ],
      "grantedToV2": {
        "user": {
          "userPrincipalName": "mike@contoso.com"
        }
      }
    },
    {
      "id": "X2k6MCMuZnxtZW1iZXJzaGlwfGFsZXhAY29udG9zby5jb20",
      "roles": [
        "manager"
      ],
      "grantedToV2": {
        "user": {
          "displayName": "Alex Wilson",
          "id": "1a2b3c4d-1111-2222-3333-444455556666",
          "userPrincipalName": "alex@contoso.com"
        }
      }
    },
    {
      "@Core.DataModificationException": {
        "@odata.type": "#Org.OData.Core.V1.DataModificationExceptionType",
        "failedOperation": "Update",
        "responseCode": 404,
        "info": {
          "code": "NotFound",
          "message": "Item not found."
        }
      },
      "id": "X2k6MCMuZnxtZW1iZXJzaGlwfG5vdGFmb3VuZEBjb250b3NvLmNvbQ"
    }
  ]
}