Introducción al servicio REST de SharePoint

SharePoint incluye un servicio de transferencia de estado representacional (REST), comparable a los modelos de objetos de cliente de SharePoint existentes. Ahora los desarrolladores pueden interactuar de manera remota con los datos de SharePoint con cualquier tecnología que admita solicitudes web REST. Esto significa que los desarrolladores pueden realizar 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).

Requisitos previos

En este tema, se presupone que tiene un conocimiento básico de REST y de cómo crear solicitudes REST.

Descripción del funcionamiento del servicio REST de SharePoint

SharePoint agrega la posibilidad de interactuar de manera remota con sitios de SharePoint a través de REST. Ahora puede interactuar directamente con objetos de SharePoint a través de cualquier tecnología compatible con las capacidades estándar de REST.

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. Por ejemplo:

CSOM

var items = List.GetByTitle(listname).GetItems();

http

GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

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). Después, la aplicación cliente debe analizar esa respuesta. En la siguiente ilustración, se muestra una vista general de la arquitectura de REST de SharePoint.

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 .NET Framework, Silverlight (ahora en desuso) o JavaScript (JSOM).

Uso de comandos HTTP con el servicio REST de SharePoint

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. El servicio web client.svc controla la solicitud HTTP y emite la respuesta adecuada en formato Atom o JSON. Después, la aplicación cliente debe analizar esa respuesta.

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. Si usa solicitudes HTTP, puede usar estos extremos REST para realizar las operaciones CRUD típicas en entidades de SharePoint, como listas y sitios.

Si quiere realizar esto en un punto de conexión	Use esta solicitud HTTP	Recuerde
Leer un recurso	GET
Crear o actualizar un recurso	POST	Use POST para crear entidades como listas y sitios. 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. Para operaciones POST, cualquier propiedad que no se necesite se establece en sus valores predeterminados. Si trata de establecer una propiedad de solo lectura como parte de una operación POST, el servicio devuelve una excepción.
Actualizar o insertar un recurso	PUT	Use operaciones PUT y MERGE para actualizar objetos de SharePoint existentes. Cualquier punto de conexión de servicios que represente una operación set de propiedades de objeto admite tanto solicitudes PUT como solicitudes MERGE. Para las solicitudes MERGE, configurar las propiedades es opcional; de manera que aquellas que no establezca explícitamente conservarán la propiedad actual. Para solicitudes PUT, si no especifica todas las propiedades requeridas en actualizaciones de objetos, el servicio REST devuelve una excepción. Además, cualquier propiedad opcional que no configure explícitamente se establecerá en sus valores predeterminados.
Eliminar un recurso	DELETE	Use el comando DELETE HTTP con la dirección URL específica del extremo para eliminar el objeto de SharePoint representado por dicho extremo. Para objetos reciclables, como listas, archivos y elementos de lista, esto da como resultado una operación Recycle.

Crear direcciones URL de REST para obtener acceso a recursos de SharePoint

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.

Para obtener acceso a una colecci?n de sitios espec?fica, use la siguiente construcci?n:

https://{site_url}/_api/site

Para obtener acceso a un sitio específico, use la siguiente construcción:

https://{site_url}/_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.

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 (/).

Esta sintaxis no se aplica a las API de REST SocialFeedManager o SocialFollowingManager. Para obtener más información, vea:

• Referencia a API de REST de fuente social para SharePoint
• Referencia a la API de REST para seguir a personas y contenido para SharePoint

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.

Ejemplos de puntos de conexión de REST de SharePoint

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. 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. 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. Los elementos entre comillas representan las variables que debe reemplazar con sus valores.

Descripción	Punto de conexión de la dirección URL	Método HTTP	Contenido del cuerpo
Recupera el título de un sitio	web/title	GET	No disponible
Recupera todas las listas de un sitio	lists	GET	No aplicable
Recupera los metadatos de una sola lista	lists/getbytitle('listname')	GET	No disponible
Recupera los elementos de una lista	lists/getbytitle('listname')/items	GET	No aplicable
Recupera una propiedad específica de una lista (en este caso, el título de la lista)	lists/getbytitle('listname')?select=Title	GET	No disponible
Crea una lista	lists	POST	Ver ejemplo
Agrega un elemento a una lista	lists/getbytitle('listname')/items	POST	Ver ejemplo

Crea una lista de datos de muestra:

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

{
  "__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.

Compatibilidad con trabajos por lotes

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. Para obtener información detallada y vínculos a los ejemplos de código, vea Realizar solicitudes de lote con las API de REST.

Recursos de OData

• Desarrollar aplicaciones orientadas a servicios mediante WCF
• Open Data Protocol
• Convenciones de URI del protocolo OData
• Operaciones del servicio de direcciones
• Operaciones del protocolo OData
• Condiciones de error

Temas del servicio REST de SharePoint

Use los siguientes recursos para obtener más información sobre el uso del servicio REST de SharePoint.

Título	Descripción
Completar operaciones básicas con puntos de conexión REST de SharePoint	Realice operaciones básicas de creación, lectura, actualización y eliminación (CRUD) con la interfaz REST de SharePoint.
Trabajar con listas y elementos de lista con REST	Realice operaciones CRUD básicas en listas y elementos de listas con la interfaz REST de SharePoint.
Trabajar con carpetas y archivos con REST	Realice operaciones CRUD básicas en carpetas y archivos con la interfaz REST de SharePoint.
Navegar por la estructura de datos de SharePoint representada en el servicio REST	Empiece en 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.
Determinar los URI de punto de conexión de servicio REST de SharePoint	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.
Usar operaciones de consulta de OData en solicitudes REST de SharePoint	Use una amplia variedad de operadores de cadena de consulta OData para seleccionar, filtrar y ordenar los datos solicitados del servicio REST de SharePoint.
Realizar solicitudes de lote con las API de REST	Combine varias solicitudes en una sola llamada al servicio REST.
Sincronizar elementos de SharePoint con el servicio REST	Sincronice elementos entre SharePoint y los complementos o servicios con el recurso GetListItemChangesSinceToken, que forma parte del servicio REST de SharePoint.
Cargar un archivo con la API de REST y 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.
Establecer permisos personalizados en una lista usando la interfaz REST	Los elementos de lista, las listas y los sitios de SharePoint son tipos de SecurableObject, que hereda los permisos de su elemento primario. 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.
Conceptos básicos del flujo de trabajo en SharePoint	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.
Referencia a API de REST de fuente social para SharePoint	Puntos de conexión de REST de SharePoint para tareas relacionadas con fuentes.
Referencia a la API de REST para seguir a personas y contenido para SharePoint	Puntos de conexión de REST de SharePoint para seguir a personas y contenido.
Desarrollar complementos de SharePoint	Encuentre artículos y recursos de ayuda detallados para agregar funciones avanzadas a sus complementos de SharePoint.