Introducción al servicio REST de SharePointGet to know the SharePoint REST service

SharePoint presenta un servicio de transferencia de estado representacional (REST), comparable a los modelos de objetos de cliente de SharePoint existentes.SharePoint introduces a Representational State Transfer (REST) service that is comparable to the existing SharePoint client object models. Ahora los desarrolladores pueden interactuar de manera remota con los datos de SharePoint con cualquier tecnología que admita solicitudes web REST.Now, developers can interact remotely with SharePoint data by using any technology that supports REST web requests. Esto significa que los desarrolladores pueden realizar las operaciones Create, Read, Update y Delete (CRUD) desde los complementos de SharePoint, las soluciones y las aplicaciones cliente con las tecnologías web de REST y la sintaxis estándar de Open Data Protocol (OData) syntax.</span>This means that developers can perform Create, Read, Update, and Delete (CRUD) operations from their SharePoint Add-ins, solutions, and client applications, using REST web technologies and standard Open Data Protocol (OData) syntax.

Requisitos previosPrerequisites

En este tema, se presupone que tiene un conocimiento básico de REST y de cómo crear solicitudes REST.This topic assumes you have a basic familiarity with REST and how to construct REST requests.

Descripción del funcionamiento del servicio REST de SharePointHow the SharePoint REST service works

SharePoint agrega la posibilidad de interactuar de manera remota con sitios de SharePoint a través de REST.SharePoint adds the ability for you to remotely interact with SharePoint sites by using REST. Ahora puede interactuar directamente con objetos de SharePoint a través de cualquier tecnología compatible con las características estándar de REST.Now you can interact directly with SharePoint objects by using any technology that supports standard REST capabilities.

Para obtener acceso a los recursos de SharePoint mediante REST, construya una solicitud HTTP RESTful mediante el estándar OData, que corresponde a la API deseada de modelo de objetos de cliente.To access SharePoint resources using REST, construct a RESTful HTTP request by using the OData standard, which corresponds to the desired client object model API. Por ejemplo:For example:

Método de modelo de objetos de cliente:Client object model method:

List.GetByTitle(listname)

Punto de conexión de REST:REST endpoint:

http://server/site/_api/lists/getbytitle('listname')

El servicio web client.svc controla la solicitud HTTP en SharePoint y envía la respuesta correspondiente en formato Atom o de notación de objetos JavaScript (JSON).The client.svc web service in SharePoint handles the HTTP request, and serves the appropriate response in either Atom or JavaScript Object Notation (JSON) format. Después, la aplicación cliente debe analizar esa respuesta.Your client application must then parse that response. En la siguiente ilustración, se muestra una vista general de la arquitectura de REST de SharePoint.The following figure shows a high-level view of the SharePoint REST architecture.

Arquitectura de servicio REST de SharePointSharePoint REST service architecture

Arquitectura de servicio REST de SharePoint

Dadas las funciones y la facilidad de uso que los modelos de objetos de clientes proporcionan, continúan siendo la opción primaria de desarrollo para comunicarse con sitios de SharePoint a través de código administrado .NET Framework, Silverlight o JavaScript.Because of the functionality and ease of use that client object models provide, they remain the primary development option for communicating with SharePoint sites by using .NET Framework managed code, Silverlight, or JavaScript.

Uso de comandos HTTP con el servicio REST de SharePointUse HTTP commands with the SharePoint REST service

Para usar las características REST que están integradas en SharePoint, cree una solicitud HTTP RESTful mediante el estándar OData, que corresponde a la API del modelo de objetos de cliente que quiere usar.To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request by using the OData standard, which corresponds to the client object model API you want to use. El servicio web client.svc controla la solicitud HTTP y emite la respuesta adecuada en formato Atom o JSON.The client.svc web service handles the HTTP request and serves the appropriate response in either Atom or JSON format. Después, la aplicación cliente debe analizar esa respuesta.The client application must then parse that response.

Los puntos de conexión del servicio REST de SharePoint corresponden a los tipos y miembros de los modelos de objetos de cliente de SharePoint. Al usar solicitudes HTTP, puede usar estos puntos de conexión REST para realizar operaciones típicas CRUD en entidades de SharePoint, como listas y sitios.The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. By using HTTP requests, you can use these REST endpoints to perform typical CRUD operations against SharePoint entities, such as lists and sites.

Si quiere realizar esto en un punto de conexiónIf you want to do this to an endpoint Use esta solicitud HTTPUse this HTTP request RecuerdeKeep in mind
Leer un recursoRead a resource GETGET
Crear o actualizar un recursoCreate or update a resource POSTPOST
  • Use POST para crear entidades como listas y sitios.Use POST to create entities such as lists and sites.
  • El servicio REST de SharePoint admite el envío de comandos POST que incluyen definiciones de objetos a puntos de conexión que representan colecciones.The SharePoint REST service supports sending POST commands that include object definitions to endpoints that represent collections.
  • Para tareas POST, toda propiedad innecesaria se establece en sus valores predeterminados.For POST operations, any properties that are not required are set to their default values.
  • Si trata de establecer una propiedad de solo lectura como parte de una operación POST, el servicio devuelve una excepción.If you attempt to set a read-only property as part of a POST operation, the service returns an exception.
Actualizar o insertar un recursoUpdate or insert a resource PUTPUT
  • Use operaciones PUT y MERGE para actualizar objetos de SharePoint existentes.Use PUT and MERGE operations to update existing SharePoint objects.
  • Cualquier punto de conexión de servicios que represente una operación set de propiedades de objeto admite tanto solicitudes PUT como solicitudes MERGE.Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests.
  • Para las solicitudes MERGE, configurar las propiedades es opcional; de manera que aquellas que no establezca explícitamente conservarán la propiedad actual.For MERGE requests, setting properties is optional; any properties that you do not explicitly set retain their current property.
  • Para solicitudes PUT, si no especifica todas las propiedades requeridas en actualizaciones de objetos, el servicio REST devuelve una excepción.For PUT requests, if you do not specify all required properties in object updates, the REST service returns an exception.
  • Además, cualquier propiedad opcional que no configure explícitamente se establecerá en sus valores predeterminados.In addition, any optional properties you do not explicitly set are set to their default properties.
Eliminar un recursoDelete a resource DELETEDELETE
  • Use el comando DELETE HTTP con la dirección URL específica del extremo para eliminar el objeto de SharePoint representado por dicho extremo.Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint.
  • En el caso de objetos reciclables, como listas, archivos y elementos de lista, esto da como resultado una tarea Recycle.In the case of recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

Crear direcciones URL de REST para obtener acceso a recursos de SharePointConstruct REST URLs to access SharePoint resources

Cada vez que sea posible, el URI de estos extremos de REST imita rigurosamente la firma de la API del recurso en el modelo de objetos de cliente de SharePoint. Los puntos de entrada principales para el servicio REST representan la colección de sitios y el sitio del contexto especificado.Whenever possible, the URI for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model. The main entry points for the REST service represent the site collection and site of the specified context.

Para obtener acceso a una colección de sitios específica, use la siguiente construcción:To access a specific site collection, use the following construction:

http://server/site/_api/site

Para obtener acceso a un sitio específico, use la siguiente construcción:To access a specific site, use the following construction:

http://server/site/_api/web

En cada caso, server representa el nombre del servidor y site representa el nombre del sitio específico o la ruta de acceso a este sitio.In each case, server represents the name of the server, and site represents the name of, or path to, the specific site.

Desde este punto de partida, puede construir URI de REST más específicas al ampliar el "camino" del modelo de objetos, con los nombres de las API del modelo de objetos de cliente separadas por una barra diagonal (/).From this starting point, you can then construct more specific REST URIs by "walking" the object model, using the names of the APIs from the client object model separated by a forward slash (/).

Esta sintaxis no se aplica a las API de REST SocialFeedManager o SocialFollowingManager.This syntax doesn't apply to the SocialFeedManager or SocialFollowingManager REST APIs. Para obtener más información, vea:For more information, see:

Para obtener más instrucciones para determinar los URI de puntos de conexión de REST de SharePoint a partir de la firma de las API del modelo de objetos de cliente correspondiente, vea Determinar los URI de punto de conexión de servicio REST de SharePoint.For more guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs, see Determine SharePoint REST service endpoint URIs.

Ejemplos de puntos de conexión de REST de SharePointSharePoint REST endpoint examples

En la tabla siguiente, se incluyen ejemplos típicos de direcciones URL de punto de conexión de REST para que empiece a trabajar con datos de SharePoint.The following table contains typical REST endpoint URL examples to get you started working with SharePoint data. Anteponga http://server/site/_api/ a los fragmentos de URL que se muestran en la tabla para crear una dirección URL de REST completa.Prepend http://server/site/_api/ to the URL fragments shown in the table to construct a fully qualified REST URL. Cuando es necesario para los comandos POST, la tabla contiene datos de ejemplo que debe pasar en el cuerpo de la solicitud HTTP para crear el elemento de SharePoint especificado.Where necessary for POST commands, the table contains sample data you must pass in the HTTP request body to create the specified SharePoint item. Los elementos entre comillas representan las variables que debe reemplazar con sus valores.Items in quotes represent variables that you must replace with your values.

DescripciónDescription Punto de conexión de la dirección URLURL endpoint Método HTTPHTTP method Contenido del cuerpoBody content
Recupera el título de una listaRetrieves the title of a list web/title GETGET No disponibleNot applicable
Recupera todas las listas de un sitioRetrieves all lists on a site lists GETGET No aplicableNot applicable
Recupera los metadatos de una sola listaRetrieves a single list's metadata lists/getbytitle('listname') GETGET No disponibleNot applicable
Recupera los elementos de una listaRetrieves items within a list lists/getbytitle('listname')/items GETGET No aplicableNot applicable
Recupera una propiedad específica de un documentoRetrieves a specific property of a document
(en este caso, el título del documento)(in this case, the document title)
lists/getbytitle('listname')?select=Title OBTENERGET No disponibleNot applicable
Crea una listaCreates a list lists POSTPOST Ver ejemploSee sample
Agrega un elemento a una listaAdds an item to a list lists/getbytitle('listname')/items POSTPOST Ver ejemploSee sample

Crea una lista de datos de muestra: Creates a list sample data

{
  '__metadata': {
    'type': 'SP.List'
  },
  'AllowContentTypes': true,
  'BaseTemplate': 104 ,
  'ContentTypesEnabled': true,
  'Description': 'My list description ',
  'Title': 'RestTest '
}

Agrega un elemento a una lista de datos de muestra: Adds an item to a list sample data

{
  '__metadata': {
    'type': 'SP.Data.listname.ListItem'
  },
  'Title': 'MyItem'
}

En el JSON anterior, reemplace ListName por el nombre de la lista de SharePoint omitiendo los espacios.In the above JSON, replace listname with the name of your SharePoint list by omitting the spaces.

Compatibilidad con trabajos por lotesBatch job support

El servicio REST de SharePoint Online (y SharePoint 2016 local o versiones posteriores) 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.The SharePoint Online (and on-premises SharePoint 2016 or later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. Para obtener información detallada y vínculos a los ejemplos de código, vea Realizar solicitudes de lote con las API de REST.For details and links to code samples, see Make batch requests with the REST APIs.

Recursos de ODataOData resources

Temas del servicio REST de SharePointSharePoint REST service topics

Use los siguientes recursos para obtener más información sobre el uso del servicio REST de SharePoint.To learn more about using the SharePoint REST service, use the following resources.

TítuloTitle DescripciónDescription
Completar operaciones básicas con puntos de conexión REST de SharePointComplete basic operations using SharePoint REST endpoints Realice operaciones básicas de creación, lectura, actualización y eliminación (CRUD) con la interfaz REST de SharePoint.Perform basic create, read, update, and delete (CRUD) operations with the SharePoint REST interface.
Trabajar con listas y elementos de lista con RESTWorking with lists and list items with REST Realice operaciones CRUD básicas en listas y elementos de listas con la interfaz REST de SharePoint.Perform basic CRUD operations on lists and list items with the SharePoint REST interface.
Trabajar con carpetas y archivos con RESTWorking with folders and files with REST Realice operaciones CRUD básicas en carpetas y archivos con la interfaz REST de SharePoint.Perform basic CRUD operations on folders and files with the SharePoint REST interface.
Navegar por la estructura de datos de SharePoint representada en el servicio RESTNavigate the SharePoint data structure represented in the REST service Inicie desde un punto de conexión de REST para un elemento de SharePoint determinado y vaya hasta elementos relacionados y obtenga acceso a ellos, por ejemplo, sitios primarios o la estructura de biblioteca en la que reside ese elemento.Start from a REST endpoint for a given SharePoint item, and navigate to and access related items, such as parent sites or the library structure where that item resides.
Determinar los URI de punto de conexión de servicio REST de SharePointDetermine SharePoint REST service endpoint URIs Instrucciones generales para determinar los URI de punto de conexión de REST de SharePoint a partir de la firma de las API del modelo de objetos de cliente correspondiente.General guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs.
Usar operaciones de consulta de OData en solicitudes REST de SharePointUse OData query operations in SharePoint REST requests Use una amplia variedad de operadores de cadena de consulta OData para seleccionar, filtrar y ordenar los datos solicitados del servicio REST de SharePoint.Use a wide range of OData query string operators to select, filter, and order the data you request from the SharePoint REST service.
Realizar solicitudes de lote con las API de RESTMake batch requests with the REST APIs Combine varias solicitudes en una sola llamada al servicio REST.Combine multiple requests into a single call to the REST service.
Sincronizar elementos de SharePoint con el servicio RESTSynchronize SharePoint items using the REST service Sincronice elementos entre SharePoint y los complementos o servicios con el recurso GetListItemChangesSinceToken, que forma parte del servicio REST de SharePoint.Synchronize items between SharePoint and your add-ins or services by using the GetListItemChangesSinceToken resource, part of the SharePoint REST service.
Cargar un archivo con la API de REST y jQueryUpload a file by using the REST API and jQuery En los ejemplos de código de este artículo se usa la interfaz de REST y las solicitudes AJAX de jQuery para agregar un archivo local a la biblioteca de documentos y luego cambiar las propiedades del elemento de lista que representa al archivo cargado.The code examples in this article use the REST interface and jQuery AJAX requests to add a local file to the Documents library, and then change properties of the list item that represents the uploaded file.
Establecer permisos personalizados en una lista usando la interfaz RESTSet custom permissions on a list by using the REST interface Los elementos de lista, las listas y los sitios de SharePoint son tipos de SecurableObject, que hereda los permisos de su elemento primario.SharePoint sites, lists, and list items are types of SecurableObject, which inherits the permissions of its parent. Para establecer permisos personalizados en un objeto, tiene que romper su herencia para que deje de heredar permisos del elemento primario y, luego, definir permisos nuevos al agregar o eliminar asignaciones de roles.To set custom permissions for an object, you need to break its inheritance so that it stops inheriting permissions from its parent, and then define new permissions by adding or removing role assignments.
Conceptos básicos del flujo de trabajo en SharePointSharePoint workflow fundamentals Agregue la función de búsqueda al cliente y aplicaciones móviles mediante el servicio de búsqueda REST en SharePoint Server 2013 y de cualquier tecnología que sea compatible con las solicitudes web de REST.Add search functionality to client and mobile applications using the Search REST service in SharePoint Server 2013 and any technology that supports REST web requests.
Referencia a API de REST de fuente social para SharePointSocial feed REST API reference for SharePoint Puntos de conexión de REST de SharePoint para tareas relacionadas con fuentes.SharePoint REST endpoints for feed-related tasks.
Referencia a la API de REST para seguir a personas y contenido para SharePointFollowing people and content REST API reference for SharePoint Puntos de conexión de REST de SharePoint para seguir a personas y contenido.SharePoint REST endpoints for following people and content.
Desarrollar complementos de SharePointDevelop SharePoint Add-ins Encuentre artículos y recursos de ayuda detallados para agregar funciones avanzadas a sus complementos de SharePoint.Find in-depth articles and resources to help you build advanced capabilities into your SharePoint Add-ins.