Referencia de usuarios, grupos y roles de las API de REST

  • Artículo

Obtenga información sobre la API de REST para el User, Group, RoleAssigment, RoleDefinition, UserCustomAction y los recursos relacionados.

Última modificación: jueves, 17 de septiembre de 2015

Hace referencia a: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

Acerca de los ejemplos de solicitudes en este artículo

En los ejemplos de solicitud en este artículo, se supone que está utilizando la biblioteca entre dominios (SP.RequestExecutor.js) para realizar las solicitudes entre dominios, por lo que usan SP.AppContextSite en el URI del extremo. Consulte Cómo obtener acceso a los datos de SharePoint 2013 desde aplicaciones con la biblioteca entre dominios para obtener más información.

Antes de usar un ejemplo de solicitud, realice lo siguiente:

  • Cambie <url de web de aplicación>, <url de web de host> y otros datos de marcador de posición, como cualquier identificador, nombre o ruta de acceso de entidades de SharePoint.

  • Si no está utilizando la biblioteca entre dominios, incluya un encabezado X-RequestDigest para enviar el valor de síntesis de formulario en todas las solicitudes POST y un encabezado content-length para solicitudes POST que envían datos en el cuerpo de la solicitud.

  • Si no realiza solicitudes entre dominios, quite SP.AppContextSite(@target) y ?@target='<host web url>' del extremo del identificador URI.

  • Si está utilizando OAuth, incluya un encabezado Authorization ("Authorization": "Bearer " + <access token>) para enviar el token de acceso OAuth.

  • Quite los saltos de línea de los valores de propiedad url y body en los ejemplos de solicitud. Se agregan saltos de línea a los ejemplos para facilitar la lectura.

  • Si quiere que el servidor devuelva respuestas en formato Atom, quite el encabezado "accept": "application/json; odata=verbose".

Consulte Recursos adicionales para obtener más información acerca del uso de la biblioteca entre dominios, OAuth y el servicio REST de SharePoint. Consulte Cómo difieren las solicitudes REST por entorno y Propiedades usadas en solicitudes de REST para obtener información acerca de formatos de solicitudes.

Sugerencia

El servicio REST de SharePoint Online admite la combinación de varias solicitudes en una sola llamada al servicio mediante el uso de la opción de consulta $batch de OData. Para obtener información detallada y vínculos a los ejemplos de código, vea Realizar solicitudes de lote con las API de REST. Esta opción aún no está disponible para la implementación de SharePoint local.

Exploración de la sintaxis de REST de grupos y usuarios de SharePoint 2013

Explorar los usuarios del servicio REST y la sintaxis de grupos

Explore visualmente la sintaxis de REST de grupos y usuarios de SharePoint 2013.

Exploración de otros diagramas de sintaxis de REST de SharePoint:

Archivos y carpetas | Listas y elementos de lista

Descargue el PDF combinado de todos los diagramas de sintaxis de REST de SharePoint

Recurso de grupo

Representa una colección de usuarios en un sitio de SharePoint. Un grupo es un tipo de SP.Principal.

URI del extremo  |  Propiedades  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/sitegroups(<id. de grupo>)

Métodos HTTP compatibles

GET  |  POST  |  MERGE  |  PUT

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener un grupo

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
});

También puede obtener un grupo mediante LoginName. Consulte el método GetByName.

Ejemplo de solicitud MERGE: cambiar un grupo

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
});

Para agregar un usuario a un grupo, agregue el usuario a la colección de usuarios del grupo, tal como se muestra en los ejemplos de solicitudes UserCollection. Para quitar un usuario de un grupo, use el método RemoveById o el método RemoveByLoginName del recurso UserCollection.

Ejemplo de solicitud PUT: reemplazar un grupo

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
});

Use el método RemoveById o el método RemoveByLoginName para eliminar un grupo. Para crear uno, envíe una solicitud POST al recurso GroupCollection. Vea ejemplos de solicitudes GroupCollection para ver un ejemplo.

Propiedades de grupo

Para obtener una propiedad, envíe una solicitud GET al extremo de la propiedad, tal como se muestra en el siguiente ejemplo.

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
});

Propiedad

Tipo

L/E

Devuelta con recurso

Description

AllowMembersEditMembership

Boolean

LE

Sí

Obtiene o establece un valor que indica si los miembros del grupo pueden editar la pertenencia del grupo.

AllowRequestToJoinLeave

Boolean

LE

Sí

Obtiene o establece un valor que indica si se permite a los usuarios solicitar pertenencia en el grupo y abandonar el grupo.

AutoAcceptRequestToJoinLeave

Boolean

LE

No

Obtiene o establece un valor que indica si se puede aceptar automáticamente la solicitud para unirse a un grupo o para abandonarlo.

CanCurrentUserEditMembership

Boolean

L

No

Obtiene un valor que indica si el usuario actual puede editar la pertenencia del grupo.

CanCurrentUserManageGroup

Boolean

L

No

Obtiene un valor que indica si el usuario actual puede administrar el grupo.

CanCurrentUserViewMembership

Boolean

L

No

Obtiene un valor que indica si el usuario actual puede ver la pertenencia del grupo.

Description

String

LE

Sí

Obtiene o establece la descripción del grupo.

Id

Int32

L

Sí

Obtiene un valor que especifica el identificador de miembro del usuario o grupo.

IsHiddenInUI

Boolean

L

Sí

Obtiene un valor que indica si este miembro debería estar oculto en la interfaz de usuario.

LoginName

String

L

Sí

Obtiene el nombre del grupo.

OnlyAllowMembersViewMembership

Boolean

LE

Sí

Obtiene o establece un valor que indica si solo se permite que los miembros del grupo vean la pertenencia del grupo.

Owner

SP.Principal

LE

No

Obtiene o establece el propietario del grupo, que puede ser un usuario u otro grupo con permisos asignados para controlar la seguridad.

OwnerTitle

String

L

Sí

Obtiene el nombre del propietario de este grupo.

RequestToJoinLeaveEmailSetting

String

LE

Sí

Obtiene o establece la dirección de correo electrónico a la cual se envían las solicitudes de la pertenencia.

PrincipalType

Int32

L

Sí

Obtiene un valor que contiene el tipo de la entidad de seguridad. Representa un valor bit a bit SP.PrincipalType: None = 0; User = 1; DistributionList = 2; SecurityGroup = 4; SharePointGroup = 8; All = 15.

Title

String

LE

Sí

Obtiene o establece un valor que especifica el nombre de la entidad de seguridad.

Users

SP.UserCollection

L

No

Obtiene una colección de objetos de usuario que representa todos los usuarios del grupo.

Representación OData

El siguiente ejemplo representa un recurso Group en formato JSON.

    {"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":""
    }}

Recurso GroupCollection

Representa una colección de recursos Group.

URI del extremo  |  Métodos  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/sitegroups

Métodos HTTP compatibles

GET  |  POST

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener los grupos en el sitio raíz

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
});

Ejemplo de solicitud GET: obtener un grupo

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
});

También puede obtener un grupo mediante LoginName. Consulte el método GetByName.

Ejemplo de solicitud POST: crear un grupo

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
});

Consulte los ejemplos de solicitudes de grupo para ver ejemplos de cómo cambiar un grupo.

Métodos de recolección

GetById
GetByName
RemoveById
RemoveByLoginName

Método GetById

Devuelve un grupo de la colección en función del identificador de miembro del grupo.

Extremo

/getbyid(<id. de grupo>)

Método HTTP

GET

Parámetros

Tipo: Int32
El identificador del grupo que se va a obtener.

Respuesta

Tipo: SP.Group
El grupo especificado.

  Ejemplo de solicitud

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
});

O bien, simplemente puede especificar el id. de grupo del recurso GroupCollection. Ejemplo: …/_api/web/sitegroups(5)

Método GetByName

Devuelve un grupo entre sitios de la colección en función del nombre del grupo.

Extremo

/getbyname('<nombre del grupo>')

Método HTTP

GET

Parámetros

Tipo: String
El nombre del grupo. El nombre del grupo se especifica en su propiedad LoginName.

Respuesta

Tipo: SP.Group
El grupo especificado.

  Ejemplo de solicitud

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
});

Método RemoveById

Quita de la colección el grupo con el identificador de miembro especificado.

Extremo

/removebyid(<id. del grupo>)

HTTP method

POST

Parámetros

Tipo: Int32
El identificador del grupo que se va a quitar.

Respuesta

Ninguna

  Ejemplo de solicitud

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

Método RemoveByLoginName

Quita el grupo de usuarios entre sitios con el nombre especificado de la colección.

Extremo

/removebyloginname('<nombre del grupo>')

HTTP method

POST

Parámetros

Tipo: String
El nombre del grupo que se va a quitar. El nombre del grupo se especifica en su propiedad LoginName.

Respuesta

Ninguna

  Ejemplo de solicitud

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

Representación OData

El siguiente ejemplo representa un recurso GroupCollection en formato JSON.

    {"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":""
        },
        ...
      }]
    }}

Recurso RoleAssignment

Define las asignaciones de roles del objeto protegible para un usuario o grupo del sitio web, la lista o el elemento de lista.

URI del extremo  |  Propiedades  |  Métodos  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/roleassignments(<id. de entidad>)

Métodos HTTP compatibles

GET  |  POST  |  DELETE

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener una asignación de rol

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
});

Ejemplo de solicitud DELETE: eliminar una asignación de rol

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
});

O bien, puede usar el método RemoveRoleAssignment para quitar una asignación de rol. Para crear una asignación de rol, use el método AddRoleAssignment.

Propiedades RoleAssignment

Para obtener una propiedad, envíe una solicitud GET al extremo de la propiedad, tal como se muestra en el siguiente ejemplo.

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
});

Propiedad

Tipo

L/E

Devuelta con recurso

Description

Member

SP.Principal

L

No

Obtiene el usuario o grupo correspondiente a la asignación de roles.

PrincipalId

Int32

L

Sí

El identificador único de la asignación de roles.

RoleDefinitionBindings

SP.RoleDefinitionCollection

L

No

Obtiene la colección de los enlaces de definiciones de roles de la asignación de roles.

Métodos RoleAssignment

DeleteObject

Método DeleteObject

El método recomendado para eliminar una asignación de rol es usar el método RemoveRoleAssignment o enviar una solicitud DELETE al extremo de recurso RoleAssignment, tal como se muestra en los ejemplos de solicitudes RoleAssignment.

Representación OData

El siguiente ejemplo representa un recurso RoleAssignment en formato JSON.

    {"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
    }}

Recurso RoleAssignmentCollection

Representa una colección de recursos RoleAssignmentGroup.

URI del extremo  |  Propiedades  |  Métodos  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/roleassignments

Métodos HTTP compatibles

GET  |  POST

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener una asignación de rol

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
});

Use el método AddRoleAssignment para crear una asignación de rol. Para eliminar una asignación de rol, use el método RemoveRoleAssignment o envíe una solicitud DELETE al extremo del recurso RoleAssignment, tal como se muestra en los ejemplos de solicitudes RoleAssignment.

Propiedades RoleAssignmentCollection

Para obtener una propiedad, envíe una solicitud GET al extremo de la propiedad, tal como se muestra en el siguiente ejemplo.

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
});

Propiedad

Tipo

L/E

Devuelta con recurso

Description

Groups

SP.GroupCollection

L

No

Obtiene los grupos que pertenecen directamente a la lista de control de acceso (ACL) para este objeto protegible.

Métodos RoleAssignmentCollection

AddRoleAssignment
GetByPrincipalId
RemoveRoleAssignment

Método AddRoleAssignment

Agrega una nueva asignación de roles con la entidad de seguridad y las definiciones de roles especificadas a la colección.

Extremo

/addroleassignment(principalid, roledefid)

Parámetros
principalid

Tipo: Int32
El identificador del usuario o grupo al que se van a asignar permisos.

roledefid

Tipo: Int32
El identificador de la definición de rol que define los permisos para asignar.

Consulte los ejemplos de solicitudes RoleDefinitionCollection para ver un ejemplo de cómo crear una definición de rol.

HTTP method

POST

Respuesta

Ninguna

  Ejemplo de solicitud

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
});

Para utilizar este método en un objeto que hereda los permisos, primero tiene que llamar al método BreakRoleInheritance en el objeto. Consulte Establecer permisos personalizados en una lista usando la interfaz REST.

Método GetByPrincipalId

Obtiene la asignación de roles asociada con el identificador de entidad de seguridad especificado de la colección.

Extremo

/getbyprincipalid(<id. de entidad>)

Parámetros

Tipo: Int32
El PrincipalId de la asignación de rol que se va a obtener.

HTTP method

GET

Respuesta

Tipo: SP.RoleAssignment
La asignación de rol especificada.

  Ejemplo de solicitud

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
});

O bien, simplemente puede especificar el id. de entidad de la asignación de rol en el recurso RoleAssignmentCollection. Ejemplo: …/_api/web/roleassignments(3)

Método RemoveRoleAssignment

Quita la asignación de rol con la entidad de seguridad especificada y la definición de rol de la colección.

Extremo

/removeroleassignment(principalid, roledefid)

Parámetros
principalid

Tipo: Int32
El identificador del usuario o grupo en la asignación de rol.

roledefid

Tipo: Int32
El identificador de la definición de rol en la asignación de rol.

HTTP method

POST

Respuesta

Ninguna

  Ejemplo de solicitud

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
});

Representación OData

El siguiente ejemplo representa un recurso RoleAssignmentCollection en formato JSON.

    {"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
        },{
        ...
      }]
    }}

Recurso RoleDefinition

Define una sola definición de roles, incluidos un nombre, una descripción y un conjunto de derechos.

URI del extremo  |  Propiedades  |  Métodos  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/roledefinitions(<id. de definición de rol>)

Métodos HTTP compatibles

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener una definición de rol

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
});

Ejemplo de solicitud MERGE: cambiar una definición de rol

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
});

Ejemplo de solicitud PUT: reemplazar una definición de rol

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
});

Ejemplo de solicitud DELETE: eliminar una definición de rol

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
});

Consulte los ejemplos de solicitudes RoleDefinitionCollection para ver un ejemplo que muestre cómo crear una definición de rol.

Propiedades RoleDefinition

Para obtener una propiedad, envíe una solicitud GET al extremo de la propiedad, tal como se muestra en el siguiente ejemplo.

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
});

Propiedad

Tipo

L/E

Devuelta con recurso

Description

BasePermissions

SP.BasePermissions

LE

Sí

Obtiene o establece un valor que especifica los permisos básicos de la definición de roles.

Description

String

LE

Sí

Obtiene o establece un valor que especifica la descripción de la definición de roles.

Hidden

Boolean

L

Sí

Obtiene un valor que especifica si se muestra la definición de roles.

Id

Int32

L

Sí

Obtiene un valor que especifica el identificador de la definición de roles.

Name

String

LE

Sí

Obtiene o establece un valor que especifica el nombre de la definición de roles.

Order

Int32

LE

Sí

Obtiene o establece un valor que especifica la posición del orden del objeto en la página Niveles de permisos de la colección de sitios.

RoleTypeKind

Int32

L

Sí

Obtiene un valor que especifica el tipo de la definición de roles. Representa un valor SP.RoleType. Consulte RoleType en la referencia de modelo de objetos de cliente .NET para ver una lista de valores de tipos de rol.

Métodos RoleDefinition

DeleteObject

Método DeleteObject

El método recomendado para eliminar una definición de rol es enviar una solicitud DELETE al extremo del recurso RoleDefinition, tal como se muestra en los ejemplos de solicitudes RoleDefinition.

Representación OData

El siguiente ejemplo representa un recurso RoleDefinition en formato JSON.

    {"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
    }}

Recurso RoleDefinitionCollection

Representa la colección de recursos RoleDefinition.

URI del extremo  |  Métodos  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/roledefinitions

Métodos HTTP compatibles

GET  |  POST

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener una definición de rol

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
});

Ejemplo de solicitud POST: crear una definición de rol

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
});

Consulte los ejemplos de solicitudes RoleDefinition para ver ejemplos de cómo cambiar o eliminar una definición de rol.

Métodos RoleDefinitionCollection

GetById
GetByName
GetByType

Método GetById

Obtiene la definición de roles en el identificador especificado de la colección.

Extremo

/getbyid(<id. de definición de rol>)

Parámetros

Tipo: Int32
El identificador de la definición de rol.

HTTP method

GET

Respuesta

Tipo: SP.RoleDefinition
La definición de rol especificada.

  Ejemplo de solicitud

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
});

O bien, simplemente puede especificar el id. de definición de rol en el recurso RoleDefinitionCollection. Ejemplo: …/_api/web/roledefinitions(1073741829)

Método GetByName

Obtiene la definición de roles con el nombre especificado.

Extremo

/getbyname('<nombre de la definición de rol>')

Parámetros

Tipo: String
El nombre de la definición de rol.

HTTP method

GET

Respuesta

Tipo: SP.RoleDefinition
La definición de rol especificada.

  Ejemplo de solicitud

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
});

Método GetByType

Obtiene la definición de roles con el tipo de rol especificado.

Extremo

/getbytype(<tipo de definición de rol>)

Parámetros

Tipo: Int32
El RoleTypeKind de la definición de rol. Consulte RoleType en la referencia de modelo de objetos de cliente .NET para ver una lista de valores de tipos de rol.

HTTP method

GET

Respuesta

Tipo: SP.RoleDefinition
La definición de rol especificada.

  Ejemplo de solicitud

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
});

Representación OData

El siguiente ejemplo representa un recurso RoleDefinitionCollection en formato JSON.

    {"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
        },{
        ...
      }]
    }}

Recurso RoleDefinitionBindingCollection

Define las definiciones de roles enlazadas a un objeto de asignación de roles.

URI del extremo  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/roleassignments(<id. de asignación de rol>)/roledefinitionbindings

Métodos HTTP compatibles

GET

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener los enlaces de definición de rol para una asignación de rol

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});

Para crear una asignación de rol, que enlace una entidad de seguridad (usuario o grupo) con una definición de rol, use el método AddRoleAssignment. Para eliminar una asignación de rol, use el método RemoveRoleAssignment o envíe una solicitud DELETE al extremo del recurso RoleAssignment, tal como se muestra en los ejemplos de solicitudes RoleAssignment.

Representación OData

El siguiente ejemplo representa un recurso RoleDefinitionBindingCollection en formato JSON.

    {"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
      }]
    }}

Recurso de usuario

Representa un usuario de Microsoft SharePoint Foundation. Un usuario es un tipo de SP.Principal.

URI del extremo  |  Propiedades  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/sitegroups(<id. de grupo>)/users(@v)?@v='<nombre de inicio de sesión>'
http://<url del sitio>/_api/web/siteusers(@v)?@v='<nombre de inicio de sesión>'

El formato del nombre de inicio de sesión depende del entorno de SharePoint, tal como se describe en la Tabla 1:

Tabla 1. Formatos de nombre de inicio de sesión

Entorno de SharePoint

Formato de nombre de inicio de sesión de ejemplo

Cómo pasar el nombre de inicio de sesión mediante un alias en la cadena de consulta

SharePoint Online o
SharePoint 2013 local usando formularios

i:0#.f|pertenencia|usuario@dominio.com

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

SharePoint 2013 local mediante notificaciones de Windows

i:0#.w|dominio\usuario

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

SharePoint 2013 local mediante notificaciones de SAML

i:05:t|adfs con roles|usuario@dominio.com

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

Nota

El formato del nombre de inicio de sesión en el ejemplo de autenticación de notificaciones basadas en el lenguaje de marcado de aserción de seguridad (SAML) asume que la notificación de identidad está configurada para usar una dirección de correo electrónico o el nombre de la entidad de seguridad del usuario. La autenticación basada en notificaciones de SAML no se puede usar en aplicaciones hospedas por SharePoint.

Métodos HTTP compatibles

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener un usuario de un sitio por nombre de inicio de sesión

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
});

Ejemplo de solicitud GET: obtener un usuario de un sitio por identificador

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
});

Ejemplo de solicitud GET: obtener un usuario de un grupo por nombre de inicio de sesión

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
});

También puede obtener un usuario de un grupo por dirección de correo electrónico o por identificador. Consulte el método GetByEmail y el método GetById.

Ejemplo de solicitud MERGE: cambiar un usuario

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
});

Ejemplo de solicitud PUT: reemplazar un usuario

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});

Consulte los ejemplos de solicitudes UserCollection para ver un ejemplo de cómo agregar un usuario a un grupo.

Ejemplo de solicitud DELETE: quitar un usuario de un grupo

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
});

Para quitar un usuario mediante el método DELETE en el recurso User, debe obtener el usuario de la colección de usuarios mediante el método GetById o método GetByEmail. O bien, simplemente puede usar el método RemoveById o método RemoveByLoginName del recurso UserCollection.

Propiedades de usuario

Para obtener una propiedad, envíe una solicitud GET al extremo de la propiedad, tal como se muestra en el siguiente ejemplo.

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
});

Propiedad

Tipo

L/E

Devuelta con recurso

Description

Email

String

LE

Sí

Esta propiedad no está disponible en SharePoint Online. Obtiene o establece la dirección de correo electrónico del usuario.

Groups

SP.GroupCollection

L

No

Obtiene la colección de grupos a los que pertenece el usuario.

Id

Int32

L

Sí

Obtiene un valor que especifica el identificador de miembro del usuario o grupo.

IsHiddenInUI

Boolean

L

Sí

Obtiene un valor que indica si este miembro debería estar oculto en la interfaz de usuario.

IsSiteAdmin

Boolean

LE

Sí

Obtiene o establece un valor booleano que especifica si el usuario es administrador de la colección de sitios.

LoginName

String

L

Sí

Obtiene el nombre de inicio de sesión del usuario.

PrincipalType

Int32

L

Sí

Obtiene un valor que contiene el tipo de la entidad de seguridad. Representa un valor bit a bit SP.PrincipalType: None = 0; User = 1; DistributionList = 2; SecurityGroup = 4; SharePointGroup = 8; All = 15.

Title

String

LE

Sí

Obtiene o establece un valor que especifica el nombre de la entidad de seguridad.

UserId

SP.User

L

Sí

Obtiene la información del usuario que contiene el identificador del nombre del usuario y el emisor del identificador del nombre del usuario.

Representación OData

El siguiente ejemplo representa un recurso de usuario en formato JSON.

    {"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" }
    }}

Recurso UserCollection

Representa una colección de recursos User.

URI del extremo  |  Métodos  |  Representación OData

URI del extremo

http://<url de sitio>/_api/web/siteusers
http://<url de sitio>/_api/web/sitegroups(<id. de grupo>)/users

Métodos HTTP compatibles

GET  |  POST

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener un usuario por nombre de inicio de sesión

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
});

Ejemplo de solicitud GET: obtener los usuarios en un grupo

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
});

Ejemplo de solicitud POST: agregar un usuario a un grupo

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
});

Métodos UserCollection

GetByEmail
GetById
GetByLoginName
RemoveById
RemoveByLoginName

Método GetByEmail

Obtiene el usuario con la dirección de correo electrónico especificada.

Extremo

/getbyemail('<dirección de correo electrónico>')

Parámetros

Tipo: String
El correo electrónico del usuario que se va a obtener.

HTTP method

GET

Respuesta

Tipo: SP.User
El usuario especificado.

  Ejemplo de solicitud

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
});

Método GetById

Obtiene el usuario con el identificador de miembro especificado.

Extremo

/getbyid(<id. de usuario>)

Parámetros

Tipo: Int32
El identificador del usuario que se va a obtener.

HTTP method

GET

Respuesta

Tipo: SP.User
El usuario especificado.

  Ejemplo de solicitud

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
});

Método GetByLoginName

Obtiene el usuario con el nombre de inicio de sesión especificado.

Extremo

/getbyloginname(@v)?@v='<nombre de inicio de sesión>'

Parámetros

Tipo: String
El nombre de inicio de sesión el usuario que se va a obtener, pasado como un alias en la cadena de consulta. Por ejemplo:
  SharePoint Online o local mediante formularios: …/getbyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cusuario%40dominio.onmicrosoft.com'
  Local mediante notificaciones de Windows: …/getbyloginname(@v)?@v='i%3A0%23.w%7Cdominio\usuario'
  Local mediante notificaciones de SAML: …/getbyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cusuario%40dominio.com'

HTTP method

GET

Respuesta

Tipo: SP.User
El usuario especificado.

  Ejemplo de solicitud

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
});

O bien, simplemente puede especificar el nombre de inicio de sesión en el recurso UserCollection. Ejemplo: …/_api/web/siteusers(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'

Método RemoveById

Quita el usuario con el identificador especificado.

Extremo

/removebyid(<id. de usuario>)

Parámetros

Tipo: Int32
El identificador del usuario que se va a quitar.

HTTP method

POST

Respuesta

Ninguna

  Ejemplo de solicitud

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
});

Método RemoveByLoginName

Quita al usuario con el nombre de inicio de sesión especificado.

Extremo

/removebyloginname(@v)?@v='<nombre de inicio de sesión>')

Parámetros

Tipo: String
El nombre de inicio de sesión el usuario que se va a quitar, pasado como un alias en la cadena de consulta. Por ejemplo:
  SharePoint Online o local mediante formularios: …/removebyloginname(@v)?@v='i%3A0%23.f%7Cmembership%7Cusuario%40dominio.onmicrosoft.com'
  Local mediante notificaciones de Windows: …/removebyloginname(@v)?@v='i%3A0%23.w%7Cdominio\usuario'
  Local mediante notificaciones de SAML: …/removebyloginname(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cusuario%40dominio.com'

HTTP method

POST

Respuesta

Ninguna

  Ejemplo de solicitud

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
});

Representación OData

El siguiente ejemplo representa un recurso UserCollection en formato JSON.

    {"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"
        }
      }]
    }}

Recurso UserCustomAction

Representa una acción personalizada asociada con una lista, un sitio web o un subsitio de SharePoint.

URI del extremo  |  Propiedades  |  Métodos  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/usercustomactions('<id. de acción personalizada de usuario>')

Métodos HTTP compatibles

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener una acción personalizada

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
});

Ejemplo de solicitud MERGE: cambiar una acción personalizada

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
});

Ejemplo de solicitud DELETE: eliminar una acción personalizada

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
});

Consulte los ejemplos de solicitudes UserCustomActionCollection para ver un ejemplo que muestre cómo crear una acción personalizada.

Propiedades UserCustomAction

Para obtener una propiedad, envíe una solicitud GET al extremo de la propiedad, tal como se muestra en el siguiente ejemplo.

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
});

Propiedad

Tipo

L/E

Devuelta con recurso

Description

CommandUIExtension

String

LE

Sí

Obtiene o establece un valor que especifica un fragmento XML específico de la implementación que determina las propiedades de la interfaz de usuario de la acción personalizada.

Description

String

LE

Sí

Obtiene o establece la descripción de la acción personalizada.

Group

String

LE

Sí

Obtiene o establece un valor que especifica un valor específico de la implementación que determina la posición de la acción personalizada en la página.

Id

GUID

L

Sí

Obtiene un valor que especifica el identificador de la acción personalizada.

ImageUrl

String

LE

Sí

Obtiene o establece la dirección URL de la imagen asociada con la acción personalizada.

Location

String

LE

Sí

Obtiene o establece la ubicación de la acción personalizada.

Name

String

LE

Sí

Obtiene o establece el nombre de la acción personalizada.

RegistrationId

String

LE

Sí

Obtiene o establece el valor que especifica el identificador del objeto asociado con la acción personalizada.

RegistrationType

Int32

LE

Sí

Obtiene o establece el valor que especifica el tipo de objeto asociado con la acción personalizada. Representa un valor SP.UserCustomActionRegistrationType: None = 0; List = 1; ContentType = 2; ProgId = 3; FileType = 4.

Rights

SP.BasePermissions

LE

Sí

Obtiene o establece el valor que especifica los permisos necesarios para la acción personalizada.

Scope

Boolean

L

Sí

Obtiene un valor que especifica el ámbito de la acción personalizada.

ScriptBlock

String

LE

Sí

Obtiene o establece el valor que especifica el ECMAScript que se ejecutará cuando se lleve a cabo la acción personalizada.

ScriptSrc

String

LE

Sí

Obtiene o establece un valor que especifica el URI de un archivo que contiene el ECMAScript para ejecutar en la página.

Sequence

Int32

LE

Sí

Obtiene o establece el valor que especifica un valor específico de la implementación que determina el orden de la acción personalizada que aparece en la página.

Title

String

LE

Sí

Obtiene o establece el título para mostrar de la acción personalizada.

Url

String

LE

Sí

Obtiene o establece la dirección URL, el URI o la función ECMAScript (JScript, JavaScript) asociados con la acción.

VersionOfUserCustomAction

String

L

Sí

Obtiene un valor que especifica un identificador de versión específico de la implementación.

Métodos UserCustomAction

DeleteObject

Método DeleteObject

El método recomendado para eliminar un archivo es enviar una solicitud DELETE al extremo del recurso UserCustomAction, tal como se muestra en los ejemplos de solicitudes UserCustomAction.

Representación OData

El siguiente ejemplo representa un recurso UserCustomAction en formato JSON.

    {"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"
    }}

Recurso UserCustomActionCollection

Representa una colección de recursos UserCustomAction.

URI del extremo  |  Métodos  |  Representación OData

URI del extremo

http://<url del sitio>/_api/web/usercustomactions

Métodos HTTP compatibles

GET  |  POST

Ejemplos de solicitudes

Ejemplo de solicitud GET: obtener todas las acciones personalizadas en un sitio

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
});

Ejemplo de solicitud GET: obtener una acción personalizada

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
});

Ejemplo de solicitud POST: crear una acción personalizada

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
});

Consulte los ejemplos de solicitudes UserCustomAction para ver ejemplos de cómo cambiar o eliminar una acción personalizada.

Métodos UserCustomActionCollection

Clear
GetById

Método Clear

Elimina todas las acciones personalizadas de la colección.

Extremo

/clear

Parámetros

Ninguna

HTTP method

POST

Respuesta

Ninguna

  Ejemplo de solicitud

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

Método GetById

Devuelve la acción personalizada con el identificador especificado.

Extremo

/getbyid(<id. de acción personalizada de usuario>)

Parámetros

Tipo: Guid
El identificador de la acción personalizada del usuario que se va a obtener.

HTTP method

GET

Respuesta

Tipo: SP.UserCustomAction
La acción personalizada del usuario especificado.

  Ejemplo de solicitud

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
});

O bien, simplemente puede especificar el id. de acción en el recurso UserCustomActionCollection. Ejemplo: …/_api/web/usercustomactions('83393b01-0b73-4af5-9f0e-9ab0750a4ec4')

Representación OData

El siguiente ejemplo representa un recurso UserCustomActionCollection en formato JSON.

    {"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"
      }]
    }}

Recursos adicionales