driveItem: assignSensitivityLabel

Namespace: microsoft.graph

Asynchronously assign a sensitivity label to a driveItem.

This API is part of the Microsoft SharePoint and OneDrive APIs that perform advanced premium administrative functions, and is considered a protected API. Protected APIs require you to have more validation, beyond permission and consent, before you can use them.

This API applies sensitivity labels to files at rest. Office clients don't apply watermarks, headers, or footers to files that contain the label information. For more information about sensitivity labels from an administrator's perspective, see Enable sensitivity labels for Office files in SharePoint and OneDrive.

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.

HTTP request

POST /drives/{drive-id}/items/{item-id}/assignSensitivityLabel
POST /drives/{drive-id}/root:/{item-path}:/assignSensitivityLabel
POST /groups/{group-id}/drive/items/{item-id}/assignSensitivityLabel
POST /groups/{group-id}/drive/root:/{item-path}:/assignSensitivityLabel
POST /me/drive/items/{item-id}/assignSensitivityLabel
POST /me/drive/root:/{item-path}:/assignSensitivityLabel
POST /sites/{site-id}/drive/items/{item-id}/assignSensitivityLabel
POST /sites/{site-id}/drive/root:/{item-path}:/assignSensitivityLabel
POST /users/{user-id}/drive/items/{item-id}/assignSensitivityLabel
POST /users/{user-id}/drive/root:/{item-path}:/assignSensitivityLabel

Request headers

Request body

In the request body, provide the ID for the sensitivity label that is to be assigned to a given file. The following table lists the required and optional input parameters.

Response

If successful, the API returns a 202 Accepted HTTP response code with an empty response body. The Location header provides the URL to get operation details. For more information about how to monitor the progress of an assign sensitivity label operation, see monitoring long-running operations.

In addition to general errors that apply to Microsoft Graph, this API returns the 423 Locked response code, which indicates that the file being accessed is locked. In such cases, the code property of the response object indicates the error type that blocks the operation. Also, Few Irm Protected sensitivity labels can't be updated by Application and need delegated user access to validate if the user has proper rights. For these scenarios, the API throws Not Supported response code.

The following table lists the possible values for the error types.

Examples

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/drive/root/items/016GVDAP3RCQS5VBQHORFIVU2ZMOSBL25U/assignSensitivityLabel
Content-Type: application/json

{
  "sensitivityLabelId": "5feba255-812e-446a-ac59-a7044ef827b5",
  "assignmentMethod": "standard",
  "justificationText": "test_justification"
}

const options = {
	authProvider,
};

const client = Client.init(options);

const assignSensitivityLabel = {
  sensitivityLabelId: '5feba255-812e-446a-ac59-a7044ef827b5',
  assignmentMethod: 'standard',
  justificationText: 'test_justification'
};

await client.api('/drive/root/items/016GVDAP3RCQS5VBQHORFIVU2ZMOSBL25U/assignSensitivityLabel')
	.version('beta')
	.post(assignSensitivityLabel);

Response

The following example shows the response.

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/QXNzaWduU2Vuc2l0aXZpdHlMYWJlbCxiMzc3ODY3OS04OWQ3LTRkYmYtYjg0MC1jYWM1NzRhY2FlNmE?tempAuth=eyJ0eXAiOiJKV1QiLCJhb....

The value of the Location header provides a URL for a service that will return the current state of the assign sensitivity label operation. You can use this information to determine when the assign sensitivity label operation has finished.

Remarks

The response from the API only indicates that the assign sensitivity label operation was accepted or rejected. The operation might be rejected, for example, if the file type isn't supported, or the file is double encrypted.