Completar operaciones básicas con puntos de conexión REST de SharePoint

  • Artículo

Puede realizar operaciones básicas de creación, lectura, actualización y eliminación (CRUD) usando la interfaz de transferencia de estado representacional (REST) que SharePoint proporciona. La interfaz REST expone todas las entidades y operaciones de SharePoint que están disponibles en las demás API de cliente de SharePoint. Una de las ventajas de usar REST es que no tiene que agregar referencias a ninguna biblioteca ni a ningún ensamblado cliente de SharePoint. En su lugar, realizará solicitudes HTTP a los puntos de conexión apropiados para recuperar o actualizar entidades de SharePoint, como webs, listas o elementos de lista.

Para obtener una introducción completa a la interfaz de REST de SharePoint y su arquitectura, vea Introducción al servicio REST para SharePoint.

Para obtener información sobre cómo se trabaja con las entidades de SharePoint principales, vea Trabajar con listas y elementos de lista con REST y Trabajar con carpetas y archivos con REST.

Para obtener un ejemplo de cómo ejecutar varias operaciones de este tipo en el contexto de una aplicación web ASP.NET escrita en C#, vea SharePoint-Add-in-REST-OData-BasicDataOperations.

Para obtener información sobre los conjuntos de API disponibles en la plataforma de SharePoint, vea Choose the right API set in SharePoint (Elegir el conjunto de API correcto en SharePoint).

Para obtener información sobre cómo usar las otras API cliente, vea lo siguiente:

Operaciones HTTP en servicios REST de SharePoint

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. Mediante el uso de solicitudes HTTP, puede usar estos puntos de conexión REST para realizar operaciones CRUD típicas (crear, leer, actualizar y eliminar) en entidades de SharePoint, como listas y sitios.

Normalmente, los puntos de conexión que representan operaciones de lectura se asignan a comandos GET HTTP. Los puntos de conexión que representan operaciones de creación se asignan a comandos POST HTTP, y los puntos de conexión que representan tareas de actualización o inserción se asignan a comandos PUT HTTP.

En SharePoint, use POST para crear entidades tales como listas y sitios. El servicio REST de SharePoint admite el envío de comandos POST que incluyen definiciones de objetos a extremos que representan colecciones. Por ejemplo, podría enviar un comando POST que incluyera una nueva definición de objetos de lista en ATOM a la siguiente dirección URL para crear una lista de SharePoint:

http://<site url>/_api/web/lists

Para tareas POST, toda propiedad innecesaria se establece en sus valores predeterminados. Si trata de establecer una propiedad de solo lectura como parte de una tarea POST, el servicio devuelve una excepción.

Use operaciones PUT y MERGE para actualizar objetos de SharePoint existentes. Los extremos de servicios que representan una operación set de propiedades de objeto admiten tanto solicitudes PUT como solicitudes MERGE. En el caso de las solicitudes MERGE, configurar las propiedades es opcional, de manera que aquellas que no defina explícitamente retendrán la propiedad actual. En el caso de los comandos PUT, sin embargo, las propiedades que no se configuren explícitamente se establecerán en los valores predeterminados. Además, si no especifica todas las propiedades necesarias en actualizaciones de objeto cuando use comandos PUT de HTTP, el servicio REST devolverá una excepción.

Use el comando HTTP DELETE con la dirección URL específica del extremo para eliminar el objeto de SharePoint representado por ese extremo. En el caso de objetos reciclables, como listas, archivos y elementos de lista, esto da como resultado una tarea Recycle.

Lectura de datos con la interfaz de REST de SharePoint

Para usar las capacidades de REST que están integradas en SharePoint, construya una solicitud RESTful HTTP usando el estándar OData, que corresponde a la API del modelo de objetos de cliente que quiere usar. Cada entidad de SharePoint se expone en un extremo del sitio de SharePoint de destino y sus metadatos se representan en formato XML o JSON. Puede efectuar las solicitudes HTTP en cualquier lenguaje, incluidos, entre otros, JavaScript y C#.

Para leer información sobre un extremo de REST, debe conocer tanto la dirección URL del extremo como la representación OData de la entidad de SharePoint que se expone en el extremo. Por ejemplo, para recuperar todas las listas de un sitio de SharePoint específico, realizaría una solicitud GET a http://<site url>/_api/web/lists. Puede desplazarse a esta dirección URL en el explorador y ver el XML que devuelve. Si realiza la solicitud en código, puede especificar si quiere recibir la representación OData de las listas en XML o JSON.

El siguiente código C# muestra cómo hacer esta solicitud GET que devuelve una representación JSON de todas las listas de un sitio usando JQuery. También parte de la base de que el usuario tiene un token de acceso OAuth válido que se almacena en la variable accessToken. No necesita el token de acceso si hace la llamada desde la web del complemento, tal como lo haría en un complemento hospedado en SharePoint. Tenga en cuenta que no puede obtener un token de acceso desde el código que se esté ejecutando en un cliente del explorador. Este token debe obtenerlo desde el código que se esté ejecutando en un servidor.

Para obtener más información sobre cómo se puede obtener un token de acceso, vea Flujo de tokens de contexto de OAuth para complementos para SharePoint y Flujo de código de autenticación de OAuth para aplicaciones en SharePoint.

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http://<site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization",
  "Bearer " + accessToken);
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

Esta solicitud tendría un aspecto un poco diferente si está escribiendo el complemento en JavaScript mientras usa la biblioteca entre dominios de SharePoint. En este caso, no es necesario proporcionar un token de acceso.

El código siguiente muestra el aspecto de esta solicitud si usa la biblioteca entre dominios y quiere recibir la representación OData de las listas como XML en vez de JSON. (Dado que Atom es el formato de respuesta predeterminado, no es necesario incluir un encabezado Accept ). Para obtener más información sobre el uso de la biblioteca entre dominios, vea Acceso a datos de SharePoint desde complementos mediante la biblioteca entre dominios.

var executor = new SP.RequestExecutor(appweburl);
executor.executeAsync(
  {
    url: appweburl +
          "/_api/SP.AppContextSite(@target)/web/lists?@target='" +
          hostweburl + "'",
    method: "GET",
    success: successHandler,
    error: errorHandler
  }
);

El código del ejemplo siguiente muestra cómo solicitar una representación JSON de todas las listas de un sitio usando C#. Se supone que tiene un token de acceso de OAuth que está almacenando en la accessToken variable .

HttpWebRequest endpointRequest = (HttpWebRequest)HttpWebRequest.Create(sharepointUrl.ToString() + "/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " + accessToken);
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

Obtener propiedades que no se devuelven con el recurso

Muchos valores de propiedades se devuelven cuando se recupera un recurso, pero con algunas propiedades, se debe enviar una solicitud GET directamente al extremo de la propiedad. Esto suele ser así con las propiedades que representan entidades de SharePoint.

El siguiente ejemplo muestra cómo obtener una propiedad anexando el nombre de la propiedad al extremo del recurso. El ejemplo obtiene el valor de la propiedad de Author de un recurso File.

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')/author

Para obtener los resultados en formato JSON, incluya un encabezado Accept establecido en "application/json;odata=verbose".

Escritura de datos mediante la interfaz de REST

Puede crear y actualizar entidades de SharePoint creando solicitudes RESTful HTTP en los extremos apropiados igual que cuando lee datos. No obstante, una de las diferencias clave es que se usa una solicitud POST. Cuando actualiza entidades, también pasa un método de solicitud HTTP PUT o MERGE agregando uno de estos términos a los encabezados de la solicitud como valor de la clave X-HTTP-Method. El método MERGE actualiza únicamente las propiedades de la entidad que especifica el usuario, mientras que el método PUT sustituye la entidad existente por otra nueva que se suministra en el cuerpo de POST. Use el método DELETE para eliminar la entidad. Si crea o actualiza una entidad, debe proporcionar una representación OData de la entidad que quiere crear o cambiar en el cuerpo de la solicitud HTTP.

Cuando cree, actualice o elimine entidades de SharePoint, es importante que tenga en cuenta que, si no usa OAuth para autorizar sus solicitudes, estas operaciones también necesitan el valor de resumen de formulario de solicitud del servidor como valor del encabezado X-RequestDigest. Puede recuperar este valor ejecutando una solicitud POST con un cuerpo vacío a http://<site url>/_api/contextinfo y extrayendo el valor del nodo d:FormDigestValue en el XML que el extremo contextinfo devuelve. En el siguiente ejemplo se ve una solicitud HTTP al extremo contextinfo de C#.

HttpWebRequest endpointRequest =(HttpWebRequest)HttpWebRequest.Create(
                                    "http://<site url>/_api/contextinfo");
endpointRequest.Method = "POST";
endpointRequest.Accept = "application/json;odata=verbose";
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

Si usa el flujo de autorización y autenticación descrito en Autorización y autenticación de complementos de SharePoint, no necesita incluir el resumen de solicitud en sus solicitudes.

Si usa la biblioteca entre dominios de JavaScript, SP.RequestExecutor controla la obtención y el envío del valor implícito del formulario.

Si va a crear un complemento de SharePoint hospedado en SharePoint, no tiene que realizar una solicitud HTTP independiente para recuperar el valor implícito del formulario. En su lugar, puede recuperar el valor en código JavaScript de la página de SharePoint (si la página usa la página maestra predeterminada), como se muestra en el ejemplo siguiente, que usa JQuery y crea una lista.

jQuery.ajax({
        url: "http://<site url>/_api/web/lists",
        type: "POST",
        data:  JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,
 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' }
),
        headers: {
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val()
        },
        success: doSuccess,
        error: doError
});

En el ejemplo siguiente se muestra cómo actualizar la lista que se creó en el ejemplo anterior. El ejemplo cambia el título de la lista, usa JQuery y presupone que esta operación se está ejecutando en un complemento hospedado en SharePoint.

jQuery.ajax({
        url: "http://<site url>/_api/web/lists/GetByTitle('Test')",
        type: "POST",
        data: JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'Title': 'New title' }),
        headers: {
            "X-HTTP-Method":"MERGE",
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val(),
            "IF-MATCH": "*"
        },
        success: doSuccess,
        error: doError
});

El valor de la clave IF-MATCH en los encabezados de solicitud es donde se especifica el valor etag de una lista o elemento de lista. Este valor concreto solo se aplica a listas y elementos de lista, y está diseñado para ayudarle a evitar problemas de simultaneidad al actualizar esas entidades. En el ejemplo anterior se usa un asterisco (*) para este valor y puede usarlo siempre que no tenga que preocuparse por problemas de simultaneidad. De lo contrario, deberá obtener el valor etag o una lista o elemento de lista, ejecutando una solicitud GET que recupere la entidad. Los encabezados de respuesta de la respuesta HTTP resultante pasan el etag como el valor de la clave ETag . Este valor se incluye también en los metadatos de la entidad.

En el siguiente ejemplo, se muestra la etiqueta <entry> de apertura del nodo XML que contiene la información de la lista. La propiedad m:etag contiene el valor etag.

<entry xml:base="http://site url/_api/" xmlns=http://www.w3.org/2005/Atom
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
       xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" m:etag=""1"">

Crear un sitio con REST

En el siguiente ejemplo, se muestra cómo crear un sitio en JavaScript.

jQuery.ajax({
    url: "http://<site url>/_api/web/webinfos/add",
    type: "POST",
    data: JSON.stringify(
        {'parameters': {
            '__metadata':  {'type': 'SP.WebInfoCreationInformation' },
            'Url': 'RestSubWeb',
            'Title': 'RestSubWeb',
            'Description': 'REST created web',
            'Language':1033,
            'WebTemplate':'sts',
            'UseUniquePermissions':false}
        }
    ),
    headers: {
        "accept": "application/json; odata=verbose",
        "content-type":"application/json;odata=verbose",
        "content-length": <length of post body>,
        "X-RequestDigest": $("#__REQUESTDIGEST").val()
    },
    success: doSuccess,
    error: doError
});

Nota:

Al establecer WebTemplate en "sts", se creará una página principal moderna. Para crear una página principal clásica, establezca WebTemplate en "sts#0".

Cómo difieren las solicitudes REST por entorno

La creación y el envío de una solicitud HTTP puede variar en función del tipo de lenguaje, de biblioteca y de complemento, por lo que con frecuencia se debe cambiar uno o más componentes de la solicitud cuando se traduce una solicitud de un entorno a otro. Por ejemplo, las solicitudes de jQuery AJAX usan parámetros data y type para especificar el tipo y el cuerpo de la solicitud, pero las solicitudes de biblioteca entre dominios usan parámetros body y method para especificar dichos valores.

Las secciones siguientes describen otras diferencias comunes entre entornos.

La manera de obtener y enviar el valor implícito del formulario depende del complemento

Al enviar una solicitud POST, hay que incluir el valor de síntesis de formulario en el encabezado X-RequestDigest. Sin embargo, la forma de obtener y enviar el valor difiere según el complemento:

  • En complementos hospedados en SharePoint, solo es necesario pasar el encabezado siguiente:

    "X-RequestDigest": $("#__REQUESTDIGEST").val()

  • En los complementos hospedados en la nube que usen OAuth, primero recupere el valor de síntesis de formulario enviando una solicitud al extremo de contextinfo y luego agréguelo a las solicitudes, tal como se muestra en Escritura de datos mediante la interfaz de REST.

  • En los complementos hospedados en la nube que usan la biblioteca entre dominios de JavaScript, no es necesario especificar el valor de síntesis de formulario. De manera predeterminada, SP.RequestExecutor lo hace automáticamente. (También controla el valor content-length).

Los complementos que usan OAuth deben pasar tokens de acceso en las solicitudes

Los complementos hospedados en la nube usan OAuth o la biblioteca entre dominios para autorizar el acceso a los datos de SharePoint. Los componentes de complemento con código que se ejecutan en un servidor web remoto deben usar OAuth para autorizar el acceso a los datos de SharePoint. En este caso, debe incluir un encabezado de autorización para enviar el token de acceso. Para obtener un ejemplo que agrega un encabezado de autorización a un objeto HTTPWebRequest , vea Lectura de datos con la interfaz REST de SharePoint.

Nota:

Los componentes de complemento hospedados en la nube que se escriben en JavaScript deben usar el SP. Objeto RequestExecutor en la biblioteca entre dominios para acceder a los datos de SharePoint. Las solicitudes de biblioteca entre dominios no necesitan incluir un token de acceso.

Para leer más información sobre los tokens de acceso OAuth y sobre cómo obtenerlos, vea Flujo de tokens de contexto de OAuth para complementos para SharePoint y Flujo de código de autenticación de OAuth para aplicaciones en SharePoint.

Los URI de punto de conexión en solicitudes entre dominios usan SP.AppContextSite para cambiar el contexto

Las solicitudes se envían al extremo del recurso que se especifica en la propiedad url de la solicitud. Los URI de extremo usan el siguiente formato:

<site url>/_api/<context>/<resource> (por ejemplo, https://contoso.com/_api/web/lists)

Las solicitudes de biblioteca entre dominios usan este formato cuando acceden a datos en la web de complemento, que es el contexto predeterminado para las solicitudes de biblioteca entre dominios. Pero para acceder a datos en la web de hospedaje o en otra colección de sitios, las solicitudes deben inicializar la web de hospedaje u otra colección de sitios como contexto. Para ello, usan el extremo SP.AppContextSite del URI, tal como se muestra en la Tabla 1. Los URI de ejemplo de la Tabla 1 usan el alias @target para enviar la dirección URL de destino de la cadena de consulta porque la dirección URL contiene un carácter especial (':').

Nota:

Se necesita una instancia web de complemento para que un complemento hospedado en la nube pueda acceder a los datos de SharePoint cuando se use la biblioteca entre dominios.

Tabla 1. Uso del extremo SP.AppContextSite para cambiar el contexto de la solicitud

Tipo de complemento Escenario de acceso a datos entre dominios URI de punto de conexión de ejemplo
Hospedado en la nube Acceso de componentes de complemento de JavaScript a datos de web de host con la biblioteca entre dominios <app web url>/_api/SP.AppContextSite(@target)/web/lists?@target='<host web url>'
Hospedado en la nube Acceso de componentes de complemento de JavaScript a datos en una colección de sitios distinta de la web de host con la biblioteca entre dominios (solo complementos con ámbito de espacio empresarial) <app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'
Hospedado en SharePoint Acceso de componentes web de complemento a datos en otra colección de sitios (solo complementos con ámbito de espacio empresarial) <app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'

Nota:

Los escenarios de acceso a datos entre dominios también requieren permisos de complemento adecuados. Para obtener más información, vea Acceder a datos de web de hospedaje y Acceder a datos en colecciones de sitios.

Las Complementos de SharePoint pueden obtener la dirección URL de la web de complemento y la dirección URL de la web de hospedaje de la cadena de consulta de la página del complemento, tal como se muestra en el ejemplo de código siguiente. El ejemplo también muestra cómo se hace referencia a la biblioteca entre dominios, lo que se define en el archivo SP.RequestExecutor.js de la web de hospedaje. El ejemplo asume que su complemento se inicia desde SharePoint. Para obtener instrucciones sobre cómo establecer el contexto de SharePoint correctamente cuando el complemento no se inicia desde SharePoint, vea Flujo de OAuth de código de autorización para complementos de SharePoint.

var hostweburl;
var appweburl;

// Get the URLs for the add-in web the host web URL from the query string.
$(document).ready(function () {
  //Get the URI decoded URLs.
  hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
  appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));

  // Load the SP.RequestExecutor.js file.
  $.getScript(hostweburl + "/_layouts/15/SP.RequestExecutor.js", runCrossDomainRequest);
});

// Build and send the HTTP request.
function runCrossDomainRequest() {
  var executor = new SP.RequestExecutor(appweburl);
  executor.executeAsync({
      url: appweburl + "/_api/SP.AppContextSite(@target)/web/lists?@target='" + hostweburl + "'",
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success: successHandler,
      error: errorHandler
  });
}

// Get a query string value.
// For production add-ins, you may want to use a library to handle the query string.
function getQueryStringParameter(paramToRetrieve) {
  var params = document.URL.split("?")[1].split("&amp;");
  var strParams = "";
  for (var i = 0; i < params.length; i = i + 1) {
    var singleParam = params[i].split("=");
    if (singleParam[0] == paramToRetrieve) return singleParam[1];
  }
}
??? // success and error callback functions

Propiedades usadas en solicitudes REST

En la tabla 2, se muestran propiedades que se suelen usar en solicitudes HTTP para el servicio REST de SharePoint.

Tabla 2. Cuándo usar propiedades de solicitud de REST en solicitudes HTTP

Propiedades Cuándo se requiere Descripción
url Todas las solicitudes La dirección URL del extremo del recurso de REST. Ejemplo: http://<site url>/_api/web/lists
method (o type) Todas las solicitudes El método de solicitud HTTP: GET para operaciones de lectura y POST para operaciones de escritura. Las solicitudes POST pueden realizar operaciones de actualización o eliminación especificando un verbo DELETE, MERGE o PUT en el encabezado X-HTTP-Method.
body (o data) Solicitudes POST que envían datos en el cuerpo de la solicitud El cuerpo de la solicitud POST. Envía datos (como tipos complejos) que no se pueden enviar en el URI de extremo. Se usa con el encabezado content-length.
Encabezado Authentication Complementos remotos que usan OAuth para autenticar usuarios. No se aplica cuando se usa JavaScript o la biblioteca entre dominios. Envía el token de acceso de OAuth (obtenido desde un servidor de tokens seguro del servicio de control de acceso (ACS) de Microsoft) que se usa para autenticar al usuario en la solicitud. Ejemplo: "Authorization": "Bearer " + accessToken, donde accessToken representa la variable que almacena el token. Los tokens se deben recuperar usando código del servidor.
Encabezado de X-RequestDigest Solicitudes POST (excepto las solicitudes SP.RequestExecutor) Los complementos remotos que usan OAuth pueden obtener el valor de resumen del formulario del http://<site url>/_api/contextinfo punto de conexión. Los complementos hospedados por SharePoint pueden obtener el valor del control de página #__REQUESTDIGEST, siempre que esté disponible en la página de SharePoint. Vea Escritura de datos mediante la interfaz de REST.
Encabezado accept Solicitudes que devuelven metadatos de SharePoint Especifica el formato de los datos de respuesta recibidos del servidor. El formato predeterminado es application/atom+xml. Ejemplo: "accept":"application/json;odata=verbose"
Encabezado content-type Solicitudes POST que envían datos en el cuerpo de la solicitud Especifica el formato de los datos que el cliente está enviando al servidor. El formato predeterminado es application/atom+xml. Ejemplo: "content-type":"application/json;odata=verbose"
Encabezado content-length Solicitudes POST que envían datos en el cuerpo de la solicitud (excepto las solicitudes SP.RequestExecutor) Especifica la longitud del contenido. Ejemplo: "content-length":requestBody.length
Encabezado IF-MATCH Solicitudes POST para las operaciones DELETE, MERGE o PUT, principalmente para cambiar listas y bibliotecas. Ofrece una forma de comprobar que el objeto que se está modificando no ha cambiado desde la última vez que se recuperó. O bien, le permite especificar que sobrescriba los cambios, como se muestra en el ejemplo siguiente: "IF-MATCH":"*"
Encabezado X-HTTP-Method Solicitudes POST para las operaciones DELETE, MERGE o PUT Se usa para especificar que la solicitud haga una operación de actualización o eliminación. Ejemplo: "X-HTTP-Method":"PUT"
binaryStringRequestBody Solicitudes POST SP.RequestExecutor que envían datos binarios en el cuerpo Especifica si el cuerpo de la solicitud es una cadena binaria. Boolean.
binaryStringResponseBody Solicitudes SP.RequestExecutor que devuelven datos binarios Especifica si la respuesta es una cadena binaria. Boolean.

Compatibilidad con trabajos por lotes

El servicio REST de SharePoint Online (y SharePoint 2016 local y versiones posteriores) admite la combinación de varias solicitudes en una sola llamada al servicio mediante la opción de consulta OData $batch . Para obtener información detallada y vínculos a los ejemplos de código, vea Realizar solicitudes de lote con las API de REST.

Vea también