Blog address: http://blog.csdn.net/FoxDave
SharePoint sites, lists, and list items all belong to the SecurableObject type. By default, a secure object inherits the privileges of its parent. To set custom permissions for an object, you need to break its inheritance from the parent and customize permissions by adding or deleting role assignments.
This article also uses code examples to illustrate how to set custom permissions on a list and then change permissions for a group. This example uses REST services to:
Get the ID of the target group. This example uses the ID of the target group to get the role bindings of the groups on the current list and add new roles to the list.
> Gets the ID defined for the role of the new permission defined for the group, which is used to add new roles to the list. This example uses existing role definitions to define new roles, but you can also choose to create a new role definition.
BreakRoleInheritance method is used to break the privilege inheritance on the list. This example breaks the list's permission inheritance and preserves the current permission settings. (When breaking permission inheritance, you can also choose to add the current user to the administrative permission level without retaining the current settings.)
Remove the current role assignment of the group on the list by sending a DELETE method request to the role assignment endpoint. (If you don't keep the existing settings when you break permission inheritance, you can ignore this step.)
Add a role assignment to the target list using the AddRoleAssignment method, which binds the group to a role definition and adds the role to the list.
Precondition
SharePoint development environment
Visual Studio 2013 or later with Office Developer Tools
Additionally, you need to set the full control rights of Add-in within the scope of the website, which can be executed only by users (such as website owners) who have sufficient permissions to change the list permissions.
Example: Customize permissions on lists using REST interfaces
The following example shows the contents of an App.js file in an Add-in hosted by SharePoint. The first example uses JavaScript cross-domain libraries to build and send HTTP requests, and the second example uses jQuery AJAX requests. Before you execute the code, you need to replace the placeholder value with the real value.
Example 1: Cross-domain library requests
'use strict';
// Change placeholder values before you run this code.
var listTitle = 'List 1';
var groupName = 'Group A';
var targetRoleDefinitionName = 'Contribute';
var appweburl;
var hostweburl;
var executor;
var groupId;
var targetRoleDefinitionId;
$(document).ready( function() {
//Get the URI decoded URLs.
hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));
// Load the cross-domain library file and continue to the custom code.
var scriptbase = hostweburl + "/_layouts/15/";
$.getScript(scriptbase + "SP.RequestExecutor.js", getTargetGroupId);
});
// Get the ID of the target group.
function getTargetGroupId() {
executor = new SP.RequestExecutor(appweburl);
var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/sitegroups/getbyname('";
endpointUri += groupName + "')/id" + "?@target='" + hostweburl + "'";
executor.executeAsync({
url: endpointUri,
method: 'GET',
headers: { 'accept':'application/json;odata=verbose' },
success: function(responseData) {
var jsonObject = JSON.parse(responseData.body);
groupId = jsonObject.d.Id;
getTargetRoleDefinitionId();
},
error: errorHandler
});
}
// Get the ID of the role definition that defines the permissions
// you want to assign to the group.
function getTargetRoleDefinitionId() {
var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/roledefinitions/getbyname('";
endpointUri += targetRoleDefinitionName + "')/id" + "?@target='" + hostweburl + "'";
executor.executeAsync({
url: endpointUri,
method: 'GET',
headers: { 'accept':'application/json;odata=verbose' },
success: function(responseData) {
var jsonObject = JSON.parse(responseData.body)
targetRoleDefinitionId = jsonObject.d.Id;
breakRoleInheritanceOfList();
},
error: errorHandler
});
}
// Break role inheritance on the list.
function breakRoleInheritanceOfList() {
var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";
endpointUri += listTitle + "')/breakroleinheritance(true)?@target='" + hostweburl + "'";
executor.executeAsync({
url: endpointUri,
method: 'POST',
headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
success: deleteCurrentRoleForGroup,
error: errorHandler
});
}
// Remove the current role assignment for the group on the list.
function deleteCurrentRoleForGroup() {
var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";
endpointUri += listTitle + "')/roleassignments/getbyprincipalid('" + groupId + "')?@target='" + hostweburl + "'";
executor.executeAsync({
url: endpointUri,
method: 'POST',
headers: {
'X-RequestDigest':$('#__REQUESTDIGEST').val(),
'X-HTTP-Method':'DELETE'
},
success: setNewPermissionsForGroup,
error: errorHandler
});
}
// Add the new role assignment for the group on the list.
function setNewPermissionsForGroup() {
var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";
endpointUri += listTitle + "')/roleassignments/addroleassignment(principalid=" + groupId;
endpointUri += ",roledefid=" + targetRoleDefinitionId + ")?@target='" + hostweburl + "'";
executor.executeAsync({
url: endpointUri,
method: 'POST',
headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
success: successHandler,
error: errorHandler
});
}
// Get parameters from the query string.
// For production purposes you may want to use a library to handle the query string.
function getQueryStringParameter(paramToRetrieve) {
var params = document.URL.split("?")[1].split("&");
for (var i = 0; i < params.length; i = i + 1) {
var singleParam = params[i].split("=");
if (singleParam[0] == paramToRetrieve) return singleParam[1];
}
}
function successHandler() {
alert('Request succeeded.');
}
function errorHandler(xhr, ajaxOptions, thrownError) {
alert('Request failed: ' + xhr.status + '\n' + thrownError + '\n' + xhr.responseText);
}// Change placeholder values before you run this code.
var siteUrl = 'http://server/site';
var listTitle = 'List 1';
var groupName = 'Group A';
var targetRoleDefinitionName = 'Contribute';
var groupId;
var targetRoleDefinitionId;
$(document).ready( function() {
getTargetGroupId();
});
// Get the ID of the target group.
function getTargetGroupId() {
$.ajax({
url: siteUrl + '/_api/web/sitegroups/getbyname(\'' + groupName + '\')/id',
type: 'GET',
headers: { 'accept':'application/json;odata=verbose' },
success: function(responseData) {
groupId = responseData.d.Id;
getTargetRoleDefinitionId();
},
error: errorHandler
});
}
// Get the ID of the role definition that defines the permissions
// you want to assign to the group.
function getTargetRoleDefinitionId() {
$.ajax({
url: siteUrl + '/_api/web/roledefinitions/getbyname(\''
+ targetRoleDefinitionName + '\')/id',
type: 'GET',
headers: { 'accept':'application/json;odata=verbose' },
success: function(responseData) {
targetRoleDefinitionId = responseData.d.Id;
breakRoleInheritanceOfList();
},
error: errorHandler
});
}
// Break role inheritance on the list.
function breakRoleInheritanceOfList() {
$.ajax({
url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle
+ '\')/breakroleinheritance(true)',
type: 'POST',
headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
success: deleteCurrentRoleForGroup,
error: errorHandler
});
}
// Remove the current role assignment for the group on the list.
function deleteCurrentRoleForGroup() {
$.ajax({
url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle
+ '\')/roleassignments/getbyprincipalid(' + groupId + ')',
type: 'POST',
headers: {
'X-RequestDigest':$('#__REQUESTDIGEST').val(),
'X-HTTP-Method':'DELETE'
},
success: setNewPermissionsForGroup,
error: errorHandler
});
}
// Add the new role assignment for the group on the list.
function setNewPermissionsForGroup() {
$.ajax({
url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle
+ '\')/roleassignments/addroleassignment(principalid='
+ groupId + ',roledefid=' + targetRoleDefinitionId + ')',
type: 'POST',
headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },
success: successHandler,
error: errorHandler
});
}
function successHandler() {
alert('Request succeeded.');
}
function errorHandler(xhr, ajaxOptions, thrownError) {
alert('Request failed: ' + xhr.status + '\n' + thrownError + '\n' + xhr.responseText);
}