restful接口

SharePoint网站、列表和列表项都属于SecurableObject类型。默认情况下，一个安全对象继承父级的权限。对一个对象设置自定义权限，你需要打破它从父级的继承，通过增删role assignments来自定义权限。

本篇同样会以代码示例来说明如何在列表上设置自定义权限，然后再更改一个组的权限。该示例使用REST服务来：

>获取目标组的ID。该示例通过目标组的ID来获取当前列表上的组所具有的角色绑定，并向列表添加新的角色。

>获取为组定义的新的权限的角色定义的ID，该ID用来向列表添加新的角色。该示例使用已存在的角色定义来定义新的角色，当然你也可以选择创建一个新的角色定义。

>使用BreakRoleInheritance方法打破列表上的权限继承。该示例打破了列表的权限继承并保留当前的权限设置。（在打破权限继承的时候，也可以选择不保留当前的设置而只把当前用户添加到管理权限级别。）

>通过发送DELETE方法请求到role assignment端点来移除列表上的组当前的role assignment。（如果你在打破权限继承的时候没有保留现有设置，可以忽略此步。）

>使用AddRoleAssignment方法向组添加一个role assignment到目标列表，该操作会将组绑定到一个角色定义并将该角色添加到列表上。

前置条件

>SharePoint开发环境

>带有Office Developer Tools的Visual Studio 2013或更高版本

此外还需要设置Add-in在网站范围内的完全控制权限，只有具有足够权限来更改列表权限的用户（如网站所有者）可以执行这个add-in。

示例：使用REST接口在列表上自定义权限

下面的示例展示了一个SharePoint承载的Add-in中的App.js文件的内容。第一个示例使用JavaScript跨域库来构建和发送HTTP请求，第二个示例使用jQuery AJAX请求。在你执行代码之前，需要把占位符的值替换成真实的值。

示例一：跨域库请求

[javascript]  view plain  copy

1. 'use strict';  
2.   
3. // Change placeholder values before you run this code.  
4. var listTitle = 'List 1';  
5. var groupName = 'Group A';  
6. var targetRoleDefinitionName = 'Contribute';  
7. var appweburl;  
8. var hostweburl;  
9. var executor;  
10. var groupId;  
11. var targetRoleDefinitionId;  
12.   
13. $(document).ready( function() {  
14.   
15.     //Get the URI decoded URLs.  
16.     hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));  
17.     appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));  
18.   
19.     // Load the cross-domain library file and continue to the custom code.  
20.     var scriptbase = hostweburl + "/_layouts/15/";  
21.     $.getScript(scriptbase + "SP.RequestExecutor.js", getTargetGroupId);  
22. });  
23.   
24. // Get the ID of the target group.  
25. function getTargetGroupId() {  
26.     executor = new SP.RequestExecutor(appweburl);  
27.     var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/sitegroups/getbyname('";  
28.     endpointUri += groupName + "')/id" + "?@target='" + hostweburl + "'";  
29.   
30.     executor.executeAsync({  
31.         url: endpointUri,  
32.         method: 'GET',  
33.         headers: { 'accept':'application/json;odata=verbose' },  
34.         success: function(responseData) {  
35.             var jsonObject = JSON.parse(responseData.body);  
36.             groupId = jsonObject.d.Id;  
37.             getTargetRoleDefinitionId();  
38.         },  
39.         error: errorHandler  
40.    });  
41. }  
42.   
43. // Get the ID of the role definition that defines the permissions  
44. // you want to assign to the group.  
45. function getTargetRoleDefinitionId() {  
46.     var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/roledefinitions/getbyname('";  
47.     endpointUri += targetRoleDefinitionName + "')/id" + "?@target='" + hostweburl + "'";  
48.   
49.     executor.executeAsync({  
50.         url: endpointUri,  
51.         method: 'GET',  
52.         headers: { 'accept':'application/json;odata=verbose' },  
53.         success: function(responseData) {  
54.             var jsonObject = JSON.parse(responseData.body)  
55.             targetRoleDefinitionId = jsonObject.d.Id;  
56.             breakRoleInheritanceOfList();  
57.         },  
58.         error: errorHandler  
59.     });  
60. }  
61.   
62. // Break role inheritance on the list.  
63. function breakRoleInheritanceOfList() {  
64.     var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";  
65.     endpointUri += listTitle + "')/breakroleinheritance(true)?@target='" + hostweburl + "'";  
66.   
67.     executor.executeAsync({  
68.         url: endpointUri,  
69.         method: 'POST',  
70.         headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },  
71.         success: deleteCurrentRoleForGroup,  
72.         error: errorHandler  
73.     });  
74. }  
75.   
76. // Remove the current role assignment for the group on the list.  
77. function deleteCurrentRoleForGroup() {  
78.     var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";  
79.     endpointUri += listTitle + "')/roleassignments/getbyprincipalid('" + groupId + "')?@target='" + hostweburl + "'";  
80.   
81.     executor.executeAsync({  
82.         url: endpointUri,  
83.         method: 'POST',  
84.         headers: {   
85.             'X-RequestDigest':$('#__REQUESTDIGEST').val(),  
86.             'X-HTTP-Method':'DELETE'  
87.         },  
88.         success: setNewPermissionsForGroup,  
89.         error: errorHandler  
90.     });  
91. }  
92.   
93. // Add the new role assignment for the group on the list.  
94. function setNewPermissionsForGroup() {  
95.     var endpointUri = appweburl + "/_api/SP.AppContextSite(@target)/web/lists/getbytitle('";  
96.     endpointUri += listTitle + "')/roleassignments/addroleassignment(principalid=" + groupId;  
97.     endpointUri += ",roledefid=" + targetRoleDefinitionId + ")?@target='" + hostweburl + "'";  
98.   
99.     executor.executeAsync({  
100.         url: endpointUri,  
101.         method: 'POST',  
102.         headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },  
103.         success: successHandler,  
104.         error: errorHandler  
105.     });  
106. }  
107.   
108. // Get parameters from the query string.  
109. // For production purposes you may want to use a library to handle the query string.  
110. function getQueryStringParameter(paramToRetrieve) {  
111.     var params = document.URL.split("?")[1].split("&");  
112.     for (var i = 0; i < params.length; i = i + 1) {  
113.         var singleParam = params[i].split("=");  
114.         if (singleParam[0] == paramToRetrieve) return singleParam[1];  
115.     }  
116. }  
117.   
118. function successHandler() {  
119.     alert('Request succeeded.');  
120. }   
121.   
122. function errorHandler(xhr, ajaxOptions, thrownError) {  
123.     alert('Request failed: ' + xhr.status + '\n' + thrownError + '\n' + xhr.responseText);  
124. }  

示例二：jQuery AJAX请求

[javascript]  view plain  copy

1. // Change placeholder values before you run this code.  
2. var siteUrl = 'http://server/site';  
3. var listTitle = 'List 1';  
4. var groupName = 'Group A';  
5. var targetRoleDefinitionName = 'Contribute';  
6. var groupId;  
7. var targetRoleDefinitionId;  
8.   
9. $(document).ready( function() {  
10.     getTargetGroupId();  
11. });  
12.   
13. // Get the ID of the target group.  
14. function getTargetGroupId() {  
15.     $.ajax({  
16.         url: siteUrl + '/_api/web/sitegroups/getbyname(\'' + groupName + '\')/id',  
17.         type: 'GET',  
18.         headers: { 'accept':'application/json;odata=verbose' },  
19.         success: function(responseData) {  
20.             groupId = responseData.d.Id;  
21.             getTargetRoleDefinitionId();  
22.         },  
23.         error: errorHandler  
24.    });  
25. }  
26.   
27. // Get the ID of the role definition that defines the permissions  
28. // you want to assign to the group.  
29. function getTargetRoleDefinitionId() {  
30.     $.ajax({  
31.         url: siteUrl + '/_api/web/roledefinitions/getbyname(\''  
32.             + targetRoleDefinitionName + '\')/id',  
33.         type: 'GET',  
34.         headers: { 'accept':'application/json;odata=verbose' },  
35.         success: function(responseData) {  
36.             targetRoleDefinitionId = responseData.d.Id;  
37.             breakRoleInheritanceOfList();  
38.         },  
39.         error: errorHandler  
40.     });  
41. }  
42.   
43. // Break role inheritance on the list.  
44. function breakRoleInheritanceOfList() {  
45.     $.ajax({  
46.         url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle  
47.             + '\')/breakroleinheritance(true)',  
48.         type: 'POST',  
49.         headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },  
50.         success: deleteCurrentRoleForGroup,  
51.         error: errorHandler  
52.     });  
53. }  
54.   
55. // Remove the current role assignment for the group on the list.  
56. function deleteCurrentRoleForGroup() {  
57.     $.ajax({  
58.         url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle  
59.             + '\')/roleassignments/getbyprincipalid(' + groupId + ')',  
60.         type: 'POST',  
61.         headers: {   
62.             'X-RequestDigest':$('#__REQUESTDIGEST').val(),  
63.             'X-HTTP-Method':'DELETE'  
64.         },  
65.         success: setNewPermissionsForGroup,  
66.         error: errorHandler  
67.     });  
68. }  
69.   
70. // Add the new role assignment for the group on the list.  
71. function setNewPermissionsForGroup() {  
72.     $.ajax({  
73.         url: siteUrl + '/_api/web/lists/getbytitle(\'' + listTitle  
74.             + '\')/roleassignments/addroleassignment(principalid='  
75.             + groupId + ',roledefid=' + targetRoleDefinitionId + ')',  
76.         type: 'POST',  
77.         headers: { 'X-RequestDigest':$('#__REQUESTDIGEST').val() },  
78.         success: successHandler,  
79.         error: errorHandler  
80.     });  
81. }  
82.   
83. function successHandler() {  
84.     alert('Request succeeded.');  
85. }   
86.   
87. function errorHandler(xhr, ajaxOptions, thrownError) {  
88.     alert('Request failed: ' + xhr.status + '\n' + thrownError + '\n' + xhr.responseText);  
89. }