用户、组和角色 REST API 引用

  • 项目

了解 User、Group、RoleAssigment、RoleDefinition、UserCustomAction 及相关资源的 REST API。

上次修改时间：2015年9月17日

适用范围：apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

关于本文中的请求示例

本文中的请求示例假设您正在使用跨域库 (SP.RequestExecutor.js) 发出跨域请求，因此它们在终结点 URI 中使用 SP.AppContextSite。有关详细信息，请参阅使用跨域库从外接程序访问 SharePoint 2013 数据。

使用请求示例之前，请执行下列操作：

  • 更改 <应用程序 Web URL>、<主机 Web URL> 和其他占位符数据，例如 SharePoint 条目的任何 ID、名称或路径。

  • 如果您未使用跨域库，请包括用于在所有 POST 请求中发送表单摘要值的 X-RequestDigest 标头，以及在请求正文中发送数据的 POST 请求的 content-length 标头。

  • 如果您未发出跨域请求，请从终结点 URI 中删除 SP.AppContextSite(@target) 和 ?@target='<host web url>'。

  • 如果您使用 OAuth，请包括 Authorization 标头 ("Authorization": "Bearer " + <access token>) 以发送 OAuth 访问令牌。

  • 在请求示例中，从 url 和 body 属性值中删除换行符。将换行符添加到示例中，使其更易于读取。

  • 如果您希望服务器以 Atom 格式返回响应，请删除 "accept": "application/json; odata=verbose" 标头。

请参阅其他资源获取有关使用跨域库、OAuth 和 SharePoint REST 服务的详细信息的链接。请参阅 REST 请求如何因环境而异和 REST 请求中使用的属性获取有关请求格式的信息。

提示

SharePoint Online REST 服务支持使用 OData $batch 查询选项，将多个请求组合到对服务的单个调用中。有关详细信息和代码示例链接，请参阅使用 REST API 发出批处理请求。内部部署 SharePoint 尚不支持此选项。

浏览 SharePoint 2013 用户和组 REST 语法

浏览 REST 服务用户和组语法

以可视化方式浏览SharePoint 2013 用户和组 REST 语法。

浏览其他 SharePoint REST 语法图表：

文件和文件夹 | 列表和列表项

下载所有 SharePoint REST 语法图表的组合 PDF。

Group 资源

表示 SharePoint 网站中用户的集合。一个组是一种 SP.Principal。

终结点 URI  |  属性  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/sitegroups(<组 ID>)

支持的 HTTP 方法

GET  |  POST  |  MERGE  |  PUT

请求示例

GET 请求示例：获取一个组

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

您也可以通过 LoginName 获取一个组。请参阅 GetByName 方法。

MERGE 请求示例：更改一个组

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Description':'New description of the group' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

若要将用户添加到组，请将用户添加到组的用户集，如 UserCollection 请求示例中所示。若要从组中删除用户，请参阅 UserCollection 资源中的 RemoveById 方法或 RemoveByLoginName 方法。

PUT 请求示例：替换一个组

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(30)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Title':'Training',
    'Description':'Description of new group', 'AllowMembersEditMembership':'false',
    'AllowRequestToJoinLeave':'false', 'AutoAcceptRequestToJoinLeave':'false',
    'OnlyAllowMembersViewMembership':'true', 'RequestToJoinLeaveEmailSetting':'true' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler
});

使用 RemoveById 方法或 RemoveByLoginName 方法删除一个组。若要创建一个组，请发送 POST 请求到 GroupCollection资源。请参阅 GroupCollection 请求示例以获取示例。

组属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性

类型

R/W

返回资源

描述

AllowMembersEditMembership

Boolean

RW

可访问

获取或设置一个值，该值指示组成员是否可编辑组中的成员资格。

AllowRequestToJoinLeave

Boolean

RW

可访问

获取或设置一个值，该值指示是否允许用户请求组成员资格以及请求离开该组。

AutoAcceptRequestToJoinLeave

Boolean

RW

不可访问

获取或设置一个值，该值指示是否可自动接受加入或离开组的请求。

CanCurrentUserEditMembership

Boolean

R

不可访问

获取一个值，该值指示当前用户是否可编辑组成员资格。

CanCurrentUserManageGroup

Boolean

R

不可访问

获取一个值，该值指示当前用户是否可以管理组。

CanCurrentUserViewMembership

Boolean

R

不可访问

获取一个值，该值指示当前用户是否可以查看组成员资格。

Description

String

RW

可访问

获取或设置组的说明。

Id

Int32

R

可访问

获取一个值，该值指定用户或组的成员标识符。

IsHiddenInUI

Boolean

R

可访问

获取一个值，该值指示是否在 UI 中隐藏此成员。

LoginName

String

R

可访问

获取组的名称。

OnlyAllowMembersViewMembership

Boolean

RW

可访问

获取或设置一个值，该值指示是否只允许组成员查看组成员资格。

Owner

SP.Principal

RW

不可访问

获取或设置组的所有者，可以是一个用户，也可以是另一个分配有安全控制权限的组。

OwnerTitle

String

R

可访问

获取该组所有者的姓名。

RequestToJoinLeaveEmailSetting

String

RW

可访问

获取或设置向其发送成员资格请求的电子邮件地址。

PrincipalType

Int32

R

可访问

获取包含主体类型的值。 表示按位 SP.PrincipalType 值：None = 0；User = 1；DistributionList = 2；SecurityGroup = 4；SharePointGroup = 8；All = 15。

Title

String

RW

可访问

获取或设置一个值，该值指定主体的名称。

Users

SP.UserCollection

R

不可访问

获取表示组中的所有用户的用户对象集合。

OData 表示

以下示例表示 JSON 格式的 Group 资源。

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
        "uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
       "type":"SP.Group"
      },
      "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Owner"}},
      "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Users"}},
      "Id":5,
      "IsHiddenInUI":false,
      "LoginName":"Members",
      "Title":"Members",
      "PrincipalType":8,
      "AllowMembersEditMembership":false,
      "AllowRequestToJoinLeave":false,
      "AutoAcceptRequestToJoinLeave":false,
      "Description":"Use this group to grant people contribute permissions to the SharePoint site: ",
      "OnlyAllowMembersViewMembership":false,
      "OwnerTitle":"Owners",
      "RequestToJoinLeaveEmailSetting":""
    }}

GroupCollection 资源

表示 Group 资源的集合。

终结点 URI  |  方法  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/sitegroups

支持的 HTTP 方法

GET  |  POST

请求示例

GET 请求示例：获取根网站的组

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：获取一个组

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

您也可以通过 LoginName 获取一个组。请参阅 GetByName 方法。

POST 请求示例：创建一个组

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Group' }, 'Title':'New Group' }",
  headers: { "content-type": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

请参阅 Group 请求示例获取如何更改组的示例。

GroupCollection 方法

GetById
GetByName
RemoveById
RemoveByLoginName

GetById 方法

基于组的成员 ID 从集合中返回一个组。

终结点

/getbyid(<组 ID>)

HTTP 方法

GET

参数

类型：Int32
要获取的组 ID。

响应

类型：SP.Group
特定的组。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /getbyid(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

或者您可以指定 GroupCollection 资源的组 ID。示例：…/_api/web/sitegroups(5)

GetByName 方法

基于组名从集合中返回一个跨网站组。

终结点

/getbyname('<组名称>')

HTTP 方法

GET

参数

类型：String
组的名称。组的名称在组的 LoginName 属性中指定。

响应

类型：SP.Group
特定的组。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /getbyname('content site owners')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RemoveById 方法

从集合中删除具有指定成员 ID 的组。

终结点

/removebyid(<组 ID>)

HTTP method

POST

参数

类型：Int32
要删除的组 ID。

响应

无

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /removebyid(17)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveByLoginName 方法

从集合中删除具有指定名称 ID 的跨网站组。

终结点

/removebyloginname('<组名称>')

HTTP method

POST

参数

类型：String
要删除的组的名称。组的名称在组的 LoginName 属性中指定。

响应

无

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups
    /removebyloginname('training')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData 表示

以下示例表示 JSON 格式的 GroupCollection 资源。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"https://<site url>/_api/Web/SiteGroups/GetById(7)",
          "uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)",
          "type":"SP.Group"
        },
        "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)/Owner"}},
        "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(7)/Users"}},
        "Id":7,
        "IsHiddenInUI":false,
        "LoginName":"Excel Services Viewers",
        "Title":"Excel Services Viewers",
        "PrincipalType":8,
        "AllowMembersEditMembership":false,
        "AllowRequestToJoinLeave":false,
        "AutoAcceptRequestToJoinLeave":false,
        "Description":"Members of this group can view pages, list items, and documents. If the document has a server rendering available, they can only view the document using the server rendering.",
        "OnlyAllowMembersViewMembership":true,
        "OwnerTitle":"Owners",
        "RequestToJoinLeaveEmailSetting":null
        },{
        "__metadata":{
          "id":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
          "uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)",
          "type":"SP.Group"
        },
        "Owner":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Owner"}},
        "Users":{"__deferred":{"uri":"https://<site url>/_api/Web/SiteGroups/GetById(5)/Users"}},
        "Id":5,
        "IsHiddenInUI":false,
        "LoginName":"Members",
        "Title":"Members",
        "PrincipalType":8,
        "AllowMembersEditMembership":false,
        "AllowRequestToJoinLeave":false,
        "AutoAcceptRequestToJoinLeave":false,
        "Description":"Use this group to grant people contribute permissions to the SharePoint site: ",
        "OnlyAllowMembersViewMembership":false,
        "OwnerTitle":"Owners",
        "RequestToJoinLeaveEmailSetting":""
        },
        ...
      }]
    }}

RoleAssignment 资源

定义网站、列表或列表项上的用户或组的安全对象角色分配。

终结点 URI  |  属性  |  方法  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/roleassignments(<主体 ID>)

支持的 HTTP 方法

GET  |  POST  |  DELETE

请求示例

GET 请求示例：获取一个角色分配

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

DELETE 请求示例：删除一个角色分配

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

或者您可以使用 RemoveRoleAssignment 方法删除角色分配。若要创建角色分配，请使用 AddRoleAssignment 方法。

RoleAssignment 属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /roleassignments(3)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性

类型

R/W

返回资源

描述

Member

SP.Principal

R

不可访问

获取与角色分配对应的用户或组。

PrincipalId

Int32

R

可访问

角色分配的唯一标识符。

RoleDefinitionBindings

SP.RoleDefinitionCollection

R

不可访问

获取角色分配的角色定义绑定的集合。

RoleAssignment 方法

DeleteObject

DeleteObject 方法

删除角色分配的建议方法是使用 RemoveRoleAssignment 方法或发送 DELETE 请求到 RoleAssignment 资源终结点，如 RoleAssignment 请求示例中所示。

OData 表示

以下示例表示 JSON 格式的 RoleAssignment 资源。

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
        "uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
        "type":"SP.RoleAssignment"
      },
      "Member":{"__deferred":{"uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/Member"}},
      "RoleDefinitionBindings":{"__deferred":{"uri":"https://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/RoleDefinitionBindings"}},
      "PrincipalId":3
    }}

RoleAssignmentCollection 资源

表示 RoleAssignment 资源的集合。

终结点 URI  |  属性  |  方法  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/roleassignments

支持的 HTTP 方法

GET  |  POST

请求示例

GET 请求示例：获取一个角色分配

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

使用 AddRoleAssignment 方法创建角色分配。若要删除角色分配，请使用 RemoveRoleAssignment 方法或发送 DELETE 请求到 RoleAssignment 资源终结点，如 RoleAssignment 请求示例中所示。

RoleAssignmentCollection 属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(3)/groups
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性

类型

R/W

返回资源

描述

Groups

SP.GroupCollection

R

不可访问

获取直接属于此安全对象访问控制列表 (ACL) 的组。

RoleAssignmentCollection 方法

AddRoleAssignment
GetByPrincipalId
RemoveRoleAssignment

AddRoleAssignment 方法

将具有指定主体和角色定义的新角色分配添加到集合中。

终结点

/addroleassignment(principalid, roledefid)

参数
principalid

类型：Int32
要为其分配权限的用户或组 ID。

roledefid

类型：Int32
定义要分配的权限的角色定义 ID。

请参阅 RoleDefinitionCollection 请求示例以获取如何创建角色定义的示例。

HTTP method

POST

响应

无

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /addroleassignment(principalid=21, roledefid=1073741827)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

要对继承权限的对象使用此方法，您必须首先在对象上调用 BreakRoleInheritance 方法。请参阅使用 REST 接口设置列表的自定义权限。

GetByPrincipalId 方法

从集合中获取与指定的主体 ID 关联的角色分配。

终结点

/getbyprincipalid(<主体 ID>)

参数

类型：Int32
要获取的角色分配的 PrincipalId。

HTTP method

GET

响应

类型：SP.RoleAssignment
指定的角色分配。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /getbyprincipalid(3)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

或者您可以在 RoleAssignmentCollection 资源中指定角色分配的主体 ID。示例：…/_api/web/roleassignments(3)

RemoveRoleAssignment 方法

从集合中删除包含指定主体和角色定义的角色分配。

终结点

/removeroleassignment(principalid, roledefid)

参数
principalid

类型：Int32
角色分配中的用户或组 ID。

roledefid

类型：Int32
角色分配中角色定义 ID。

HTTP method

POST

响应

无

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments
    /removeroleassignment(principalid=21, roledefid=1073741827)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData 表示

以下示例表示 JSON 格式的 RoleAssignmentCollection 资源。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)",
          "uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)",
          "type":"SP.RoleAssignment"
        },
        "Member":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)/Member"}},
        "RoleDefinitionBindings":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(1)/RoleDefinitionBindings"}},
        "PrincipalId":1
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
          "uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)",
          "type":"SP.RoleAssignment"
        },
        "Member":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/Member"}},
        "RoleDefinitionBindings":{"__deferred":{"uri":"http://<site url>/_api/Web/RoleAssignments/GetByPrincipalId(3)/RoleDefinitionBindings"}},
        "PrincipalId":3
        },{
        ...
      }]
    }}

RoleDefinition 资源

定义单个角色定义，包括名称、说明和权限集。

终结点 URI  |  属性  |  方法  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/roledefinitions(<角色定义 ID>)

支持的 HTTP 方法

GET  |  POST  |  DELETE  |  MERGE  |  PUT

请求示例

GET 请求示例：获取一个角色定义

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE 请求示例：更改一个角色定义

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions':
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '48' } }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

PUT 请求示例：替换一个角色定义

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions':
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '48' }, 
   'Description': 'New description', 'Name': 'New name', 'Order': 170 }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler
});

DELETE 请求示例：删除一个角色定义

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741928)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

请参阅 RoleDefinitionCollection 请求示例以获取说明如何创建角色定义的示例。

RoleDefinition 属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /roledefinitions(1073741829)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性

类型

R/W

返回资源

描述

BasePermissions

SP.BasePermissions

RW

可访问

获取或设置一个值，该值指定角色定义的基本权限。

Description

String

RW

可访问

获取或设置一个值，该值指定角色定义的描述。

Hidden

Boolean

R

可访问

获取一个值，该值指定是否显示角色定义。

Id

Int32

R

可访问

获取一个值，该值指定角色定义的 ID。

Name

String

RW

可访问

获取或设置一个值，该值指定角色定义名称。

Order

Int32

RW

可访问

获取或设置一个值，该值指定网站集"权限级别"页面中对象位置的顺序。

RoleTypeKind

Int32

R

可访问

获取一个值，该值指定角色定义的类型。 表示 SP.RoleType 值。有关角色类型值列表，请参阅 .NET 客户端对象模型引用中的 RoleType。

RoleDefinition 方法

DeleteObject

DeleteObject 方法

删除角色定义的建议方式是发送 DELETE 请求到 RoleDefinition 资源终结点，如 RoleDefinition 请求示例中所示。

OData 表示

以下示例表示 JSON 格式的 RoleDefinition 资源。

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
        "uri":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
        "type":"SP.RoleDefinition"
      },
      "BasePermissions":{"__metadata":{"type":"SP.BasePermissions"}, "High":"2147483647", "Low":"4294967295"},
      "Description":"Has full control.",
      "Hidden":false,
      "Id":1073741829,
      "Name":"Full Control",
      "Order":1,
      "RoleTypeKind":5
    }}

RoleDefinitionCollection 资源

表示 RoleDefinition 资源的集合。

终结点 URI  |  方法  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/roledefinitions

支持的 HTTP 方法

GET  |  POST

请求示例

GET 请求示例：获取一个角色定义

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST 请求示例：创建一个角色定义

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.RoleDefinition' }, 'BasePermissions': 
    { '__metadata': { 'type': 'SP.BasePermissions' }, 'High': '176' , 'Low': '138612801' }, 
    'Description': 'New description', 'Name': 'New role', 'Order': 180 }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

请参阅 RoleDefinition 请求示例以获取如何更改或删除角色定义的示例。

RoleDefinitionCollection 方法

GetById
GetByName
GetByType

GetById 方法

从集合中获取具有指定 ID 的角色定义。

终结点

/getbyid(<角色定义 ID>)

参数

类型：Int32
角色定义 ID。

HTTP method

GET

响应

类型：SP.RoleDefinition
特定的角色定义。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbyid(1073741829)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

或者您可以指定 RoleDefinitionCollection 资源的角色定义 ID。示例：…/_api/web/roledefinitions(1073741829)

GetByName 方法

获取具有指定名称的角色定义。

终结点

/getbyname('<角色定义名称>')

参数

类型：String
角色定义的名称。

HTTP method

GET

响应

类型：SP.RoleDefinition
特定的角色定义。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbyname('contribute')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByType 方法

获取具有指定角色类型的角色定义。

终结点

/getbytype(<角色定义类型>)

参数

类型：Int32
角色定义的 RoleTypeKind。有关角色类型值列表，请参阅 .NET 客户端对象模型引用中的 RoleType。

HTTP method

GET

响应

类型：SP.RoleDefinition
特定的角色定义。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roledefinitions
    /getbytype(5)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData 表示

以下示例表示 JSON 格式的 RoleDefinitionCollection 资源。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "uri":"https://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"2147483647",
          "Low":"4294967295"
        },
        "Description":"Has full control.",
        "Hidden":false,
        "Id":1073741829,
        "Name":"Full Control",
        "Order":1,
        "RoleTypeKind":5
        },{
        ...
      }]
    }}

RoleDefinitionBindingCollection 资源

定义绑定到角色分配对象的角色定义。

终结点 URI  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/roleassignments(<角色分配 ID>)/roledefinitionbindings

支持的 HTTP 方法

GET

请求示例

GET 请求示例：获取角色分配的角色定义绑定

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/roleassignments(7)
    /roledefinitionbindings
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler});

若要创建将主体（用户或组）绑定到角色定义的角色分配，请使用 AddRoleAssignment 方法。若要删除角色分配，请使用 RemoveRoleAssignment 方法或发送 DELETE 请求到 RoleAssignment 资源终结点，如 RoleAssignment 请求示例中所示。

OData 表示

以下示例表示 JSON 格式的 RoleDefinitionBindingCollection 资源。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "uri":"http://<site url>/_api/Web/RoleDefinitions(1073741829)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"2147483647",
          "Low":"4294967295"
        },
        "Description":"Has full control.",
        "Hidden":false,
        "Id":1073741829,
        "Name":"Full Control",
        "Order":1,
        "RoleTypeKind":5
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/RoleDefinitions(1073741827)",
          "uri":"http://<site url>/_api/Web/RoleDefinitions(1073741827)",
          "type":"SP.RoleDefinition"
        },{
        "__metadata":{
          "type":"SP.BasePermissions"},
          "High":"432",
          "Low":"1011028719"
        },
        "Description":"Can view, add, update, and delete list items and documents.",
        "Hidden":false,
        "Id":1073741827,
        "Name":"Contribute",
        "Order":64,
        "RoleTypeKind":3
      }]
    }}

User 资源

表示 Microsoft SharePoint Foundation 中的用户。一个用户是一种 SP.Principal。

终结点 URI  |  属性  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/sitegroups(<组 ID>)/users(@v)?@v='<登录名>'
http://<网站 URL>/_api/web/siteusers(@v)?@v='<登录名>'

用户的登录名格式根据您的 SharePoint 环境而异，如表 1 中的说明：

表 1. 登录名格式

SharePoint 环境

示例登录名格式

如何使用查询字符串中的别名传递登录名

使用表单的 SharePoint Online 或
SharePoint 2013 本地环境

i:0#.f|membership|user@domain.com

…/users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'

使用 Windows 声明的 SharePoint 2013本地环境

i:0#.w|domain\user

…/users(@v)?@v='i%3A0%23.w%7Cdomain\user'

使用 SAML 声明的 SharePoint 2013 本地环境

i:05:t|adfs with roles|user@domain.com

…/users(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'

备注

基于安全声明标记语言 (SAML) 的声明身份验证示例中的登录名格式假定已将身份声明 配置为使用电子邮件地址或用户主体名称。不能在 SharePoint 承载的应用程序中使用 SAML 声明身份验证。

支持的 HTTP 方法

GET  |  POST  |  DELETE  |  MERGE  |  PUT

请求示例

GET 请求示例：通过登录名获取网站的用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/siteusers(@v)
    ?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：通过 ID 获取网站的用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/getuserbyid(16)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：通过登录名获取组的用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

您还可以通过电子邮件地址或 ID 获取组的用户。请参阅 GetByEmail 方法和 GetById 方法。

MERGE 请求示例：更改一个用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.User' }, 'Title':'New display name' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

PUT 请求示例：替换一个用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.User' }, 'Email':'user2@domain.com', 'IsSiteAdmin':false, 'Title':'User 2' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "PUT"
  },
  success: successHandler,
  error: errorHandler});

请参阅 UserCollection 请求示例以获取如何将用户添加到组的示例。

DELETE 请求示例：删除组的用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users/getbyid(18)
    &@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

若要使用 User 资源的 DELETE 方法删除用户，您必须使用 GetById 方法或 GetByEmail 方法获取用户集合的用户。或者您可以使用 UserCollection 资源的 RemoveById 方法或 RemoveByLoginName 方法。

用户属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)
    /users(@v)/<property name>?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性

类型

R/W

返回资源

描述

Email

String

RW

可访问

此属性不能在 SharePoint Online 中使用。获取或设置用户的电子邮件地址。

Groups

SP.GroupCollection

R

不可访问

获取用户所在组的集合。

Id

Int32

R

可访问

获取一个值，该值指定用户或组的成员标识符。

IsHiddenInUI

Boolean

R

可访问

获取一个值，该值指示是否在 UI 中隐藏此成员。

IsSiteAdmin

Boolean

RW

可访问

获取或设置一个布尔值，该值指定用户是否为网站集管理员。

LoginName

String

R

可访问

获取用户的登录名。

PrincipalType

Int32

R

可访问

获取包含主体类型的值。 表示按位 SP.PrincipalType 值：None = 0；User = 1；DistributionList = 2；SecurityGroup = 4；SharePointGroup = 8；All = 15。

Title

String

RW

可访问

获取或设置一个值，该值指定主体的名称。

UserId

SP.UserIdInfo

R

可访问

获取用户的信息，包括用户的名称标识符及其颁发者。

OData 表示

以下示例表示 JSON 格式的 User 资源。

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/GetUserById(16)",
        "uri":"http://<site url>/_api/Web/GetUserById(16)",
        "type":"SP.User"
      },
      "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(16)/Groups"}},
      "Id":16,
      "IsHiddenInUI":false,
      "LoginName":"i:0#.w|domain\\user",
      "Title":"User Display Name",
      "PrincipalType":1,
      "Email":"user@company.com",
      "IsSiteAdmin":false,
      "UserId":{"__metadata":{"type":"SP.UserIdInfo"}, "NameId":"s-0-0-00-000000-0000000000-0000000000-000000", "NameIdIssuer":"issuer id" }
    }}

UserCollection 资源

表示 User 资源的集合。

终结点 URI  |  方法  |  OData 表示

终结点 URI

http://<网站 url>/_api/web/siteusers
http://<网站 url>/_api/web/sitegroups(<组 id>)/users

支持的 HTTP 方法

GET  |  POST

请求示例

GET 请求示例：通过登录名获取用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/siteusers(@v)
    ?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：获取组中的用户

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(7)/users
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST 请求示例：将用户添加到组

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /sitegroups(7)/users
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.User' }, 'LoginName':'i:0#.w|domain\\user' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

UserCollection 方法

GetByEmail
GetById
GetByLoginName
RemoveById
RemoveByLoginName

GetByEmail 方法

获取具有指定电子邮件地址的用户。

终结点

/getbyemail('<电子邮件地址>')

参数

类型：String
要获取的用户的电子邮件。

HTTP method

GET

响应

类型：SP.User
特定的用户。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyemail('user@domain.com'),
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetById 方法

获取具有指定成员标识符 (ID) 的用户。

终结点

/getbyid(<用户 ID>)

参数

类型：Int32
要获取的用户 ID。

HTTP method

GET

响应

类型：SP.User
特定的用户。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyid(23)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByLoginName 方法

获取具有指定登录名的用户。

终结点

/getbyloginname(@v)?@v='<登录名>'

参数

类型：String
要获取的用户的登录名，在查询字符串中作为别名传递。例如：使用以下表单的
  SharePoint Online 或本地环境：…/getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
  使用 Windows 声明的本地环境：…/getbyloginname(@v)?@v='i%3A0%23.w%7C域\用户'
  使用 SAML 声明的本地环境：…/getbyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7C用户%40域.com'

HTTP method

GET

响应

类型：SP.User
特定的用户。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

或者您可以指定 UserCollection 资源的登录名。示例：…/_api/web/siteusers(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'

RemoveById 方法

删除具有指定 ID 的用户。

终结点

/removebyid(<用户 ID>)

参数

类型：Int32
要删除的用户 ID。

HTTP method

POST

响应

无

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /removebyid(24)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveByLoginName 方法

删除指定登录名的用户。

终结点

/removebyloginname(@v)?@v='<登录名>'

参数

类型：String
要删除的用户的登录名，在查询字符串中作为别名传递。例如：使用以下表单的
  SharePoint Online 或本地环境：…/removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7C用户%40domain.onmicrosoft.com'
  使用 Windows 声明的本地环境：…/removebyloginname(@v)?@v='i%3A0%23.w%7C域\用户'
  使用 SAML 声明的本地环境：…/removebyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7C用户%40域.com'

HTTP method

POST

响应

无

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/sitegroups(7)/users
    /removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData 表示

以下示例表示 JSON 格式的 UserCollection 资源。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetUserById(16)",
          "uri":"http://<site url>/_api/Web/GetUserById(16)",
          "type":"SP.User"
        },
        "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(16)/Groups"}},
        "Id":16,
        "IsHiddenInUI":false,
        "LoginName":"i:0#.w|domain\\user1",
        "Title":" User1 Display Name ",
        "PrincipalType":1,
        "Email":"user1@company.com",
        "IsSiteAdmin":false,{
        "__metadata":{
          "type":"SP.UserIdInfo"},
          "NameId":"s-0-0-00-000000-0000000000-0000000000-000000",
          "NameIdIssuer":"issuer id"
        }},{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetUserById(21)",
          "uri":"http://<site url>/_api/Web/GetUserById(21)",
          "type":"SP.User"},
        "Groups":{"__deferred":{"uri":"http://<site url>/_api/Web/GetUserById(21)/Groups"}},
        "Id":21,
        "IsHiddenInUI":false,
        "LoginName":"i:0#.w|domain\\user2",
        "Title":" User2 Display Name ",
        "PrincipalType":1,
        "Email":"user2@company.com",
        "IsSiteAdmin":false,{
        "__metadata":{
          "type":"SP.UserIdInfo"},
          "NameId":"s-0-0-00-000000-0000000000-0000000000-000001",
          "NameIdIssuer":"issuer id"
        }
      }]
    }}

UserCustomAction 资源

表示与 SharePoint 列表、网站或子网站关联的自定义操作。

终结点 URI  |  属性  |  方法  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/usercustomactions('<用户自定义操作 ID>')

支持的 HTTP 方法

GET  |  POST  |  DELETE  |  MERGE  |  PUT

请求示例

GET 请求示例：获取一个自定义操作

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE 请求示例：更改一个自定义操作

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.UserCustomAction' }, 'Title':'New title' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

DELETE 请求示例：删除一个自定义操作

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

请参阅 UserCustomActionCollection 请求示例以获取说明如何创建自定义操作的示例。

UserCustomAction 属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性

类型

R/W

返回资源

描述

CommandUIExtension

String

RW

可访问

获取或设置一个值，该值指定特定于实现的、用于确定自定义操作的用户界面属性的 XML 片段。

Description

String

RW

可访问

获取或设置自定义操作的说明。

Group

String

RW

可访问

获取或设置一个值，该值指定确定自定义操作在页面中的位置的特定于实现的值。

Id

GUID

R

可访问

获取一个值，该值指定自定义操作的标识符。

ImageUrl

String

RW

可访问

获取或设置与自定义操作关联的图像的 URL。

Location

String

RW

可访问

获取或设置自定义操作的位置。

Name

String

RW

可访问

获取或设置自定义操作的名称。

RegistrationId

String

RW

可访问

获取或设置一个值，该值指定与自定义操作关联的对象的标识符。

RegistrationType

Int32

RW

可访问

获取或设置一个值，该值指定与自定义操作关联的对象的类型。 表示 SP.UserCustomActionRegistrationType 值：None = 0；List = 1；ContentType = 2；ProgId = 3；FileType = 4。

Rights

SP.BasePermissions

RW

可访问

获取或设置一个值，该值指定自定义操作所需的权限。

Scope

Boolean

R

可访问

获取一个值，该值指定自定义操作的范围。

ScriptBlock

String

RW

可访问

获取或设置一个值，该值指定在执行自定义操作时要执行的 ECMAScript。

ScriptSrc

String

RW

可访问

获取或设置一个值，该值指定包含要在页面上执行的 ECMAScript 的文件的 URI。

Sequence

Int32

RW

可访问

获取或设置一个值，该值指定确定自定义操作在页面上的显示顺序的特定于实现的值。

Title

String

RW

可访问

获取或设置自定义操作的显示标题。

Url

String

RW

可访问

获取或设置与此操作关联的 URL、URI 或 ECMAScript（JScript、JavaScript）函数。

VersionOfUserCustomAction

String

R

可访问

获取一个值，该值指定特定于实现的版本标识符。

UserCustomAction 方法

DeleteObject

DeleteObject 方法

删除文件的建议方式是发送 DELETE 请求到 UserCustomAction 资源终结点，如 UserCustomAction 请求示例中所示。

OData 表示

以下示例表示 JSON 格式的 UserCustomAction 资源。

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
        "uri":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
        "type":"SP.UserCustomAction"
      },
      "CommandUIExtension":null,
      "Description":"Opens the Shared Documents page",
      "Group":"SiteActions",
      "Id":"98bffbf9-c911-4c59-a807-cac99647f889",
      "ImageUrl":null,
      "Location":"Microsoft.SharePoint.StandardMenu",
      "Name":null,
      "RegistrationId":null,
      "RegistrationType":0,
      "Rights":{"__metadata":{"type":"SP.BasePermissions"}, "High":"0", "Low":"0"},
      "Scope":3,
      "ScriptBlock":null,
      "ScriptSrc":null,
      "Sequence":101,
      "Title":"Open Shared Docs",
      "Url":"http://<site url>/Shared%20Documents/Forms/AllItems.aspx",
      "VersionOfUserCustomAction":"15.0.1.0"
    }}

UserCustomActionCollection 资源

表示 UserCustomAction 资源的集合。

终结点 URI  |  方法  |  OData 表示

终结点 URI

http://<网站 URL>/_api/web/usercustomactions

支持的 HTTP 方法

GET  |  POST

请求示例

GET 请求示例：获取网站的所有自定义操作

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：获取一个自定义操作

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST 请求示例：创建一个自定义操作

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.UserCustomAction' }, 'Location':'Microsoft.SharePoint.StandardMenu',
    'Group':'SiteActions', 'Sequence':'101', 'Title':'Open Shared Docs',
    'Description':'Opens the Shared Documents page', 'Url':'~site/Shared%20Documents/Forms/AllItems.aspx' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

请参阅 UserCustomAction 请求示例以获取如何更改或删除自定义操作的示例。

UserCustomActionCollection 方法

Clear
GetById

Clear 方法

删除集合中的所有自定义操作。

终结点

/clear

参数

无

HTTP method

POST

响应

无

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    /clear
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

GetById 方法

返回具有指定标识符的自定义操作。

终结点

/getbyid(<用户自定义操作 ID>)

参数

类型：Guid
要获取的用户自定义操作 ID。

HTTP method

GET

响应

类型：SP.UserCustomAction
特定的用户自定义操作。

  请求示例

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/usercustomactions
    /getbyid('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

或者您可以指定 UserCustomActionCollection 资源的操作 ID。示例：…/_api/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')

OData 表示

以下示例表示 JSON 格式的 UserCustomActionCollection 资源。

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/UserCustomActions(guid'c38d9d91-c5e8-4fbd-9040-52b03024d2a3')",
          "uri":"http://<site url>/_api/Web/UserCustomActions(guid'c38d9d91-c5e8-4fbd-9040-52b03024d2a3')",
          "type":"SP.UserCustomAction"
        },
        "CommandUIExtension":null,
        "Description":"Opens the Site Contents page",
        "Group":"SiteActions",
        "Id":"c38d9d91-c5e8-4fbd-9040-52b03024d2a3",
        "ImageUrl":null,
        "Location":"Microsoft.SharePoint.StandardMenu",
        "Name":"{c38d9d91-c5e8-4fbd-9040-52b03024d2a3}",
        "RegistrationId":null,
        "RegistrationType":0,{
        "__metadata":{ "type":"SP.BasePermissions"}, "High":"0", "Low":"0" },
        "Scope":3,
        "ScriptBlock":null,
        "ScriptSrc":null,
        "Sequence":102,
        "Title":"Open Site Contents",
        "Url":"~site/_layouts/15/viewlsts.aspx",
        "VersionOfUserCustomAction":"15.0.1.0"},{
        "__metadata":{
          "id":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
          "uri":"http://<site url>/_api/Web/UserCustomActions(guid'98bffbf9-c911-4c59-a807-cac99647f889')",
          "type":"SP.UserCustomAction"},
        "CommandUIExtension":null,
        "Description":"Opens the Shared Documents page",
        "Group":"SiteActions",
        "Id":"98bffbf9-c911-4c59-a807-cac99647f889",
        "ImageUrl":null,
        "Location":"Microsoft.SharePoint.StandardMenu",
        "Name":"{98bffbf9-c911-4c59-a807-cac99647f889}",
        "RegistrationId":null,
        "RegistrationType":0,{
        "__metadata":{ "type":"SP.BasePermissions"}, "High":"0", "Low":"0" },
        "Scope":3,
        "ScriptBlock":null,
        "ScriptSrc":null,
        "Sequence":101,
        "Title":"Open Shared Docs",
        "Url":"http://<site url>/Shared%20Documents/Forms/AllItems.aspx",
        "VersionOfUserCustomAction":"15.0.1.0"
      }]
    }}

其他资源