使用 REST 接口设置列表上的自定义权限
SharePoint 网站、列表和列表项均属于 SecurableObject 类型。 默认情况下,安全对象将继承其父级的权限。 若要设置对象的自定义权限,需要中断其继承,使其停止从父级继承权限,然后通过添加或删除角色分配定义新的权限。
注意
请参阅另请参阅部分,获取介绍如何设置细化权限的文章链接。
本文中的代码示例设置列表的自定义权限,然后更改某个组对该列表的权限。 本示例使用 REST 接口执行以下操作:
- 获取目标组的 ID。 本示例使用 ID 获取列表中组的当前角色绑定,并将新角色添加到列表中。
- 获取定义组的新权限的角色定义的 ID。 ID 用于将新角色添加到列表中。 本示例使用新角色的现有角色定义,但您可以选择创建新的角色定义。
- 通过使用
BreakRoleInheritance
方法中断列表上的角色继承。 该示例中断角色继承,但保留当前角色集。 也可以选择不复制任何角色分配,并将当前用户添加到“管理”权限级别。 - 通过向角色分配终结点发送 DELETE 请求,删除列表中组的当前角色分配。 (如果选择不复制任何角色分配,请跳过此步骤。)
- 使用
AddRoleAssignment
方法向列表添加组的角色分配,这可将组绑定到角色定义并向列表添加该角色。
使用本文中示例的先决条件
若要使用本文中的示例,需要具备:
- 一个 SharePoint 开发环境(本地方案需要应用隔离)
- Visual Studio 2012 或 Visual Studio 2013(带 Visual Studio 2012 的 Office 开发人员工具)或更高版本
您还需要在 Web 作用域中设置 Full Control外接程序权限。 只有具有更改列表权限的充分权限的用户(如网站所有者)才能运行此外接程序。
示例:使用 REST 接口设置列表上的自定义权限
以下示例显示 SharePoint 托管的外接程序中 App.js 文件的内容。 第一个示例使用 JavaScript 跨域库构建和发送 HTTP 请求。 第二个示例使用 jQuery AJAX 请求。
示例 1:跨域库请求
'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);
}
示例 2:jQuery AJAX 请求
// 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);
}