SharePoint REST API - 基本操作（一）

博客地址：http://blog.csdn.net/FoxDave

本文讲述如何应用SharePoint的REST接口完成基本的增删查改操作。

使用SharePoint客户端API和REST服务进行开发

你可以使用SharePoint提供的REST接口执行基本的增删查改操作。REST接口暴露了所有的SharePoint客户端API中可操作的对象和操作。使用REST的优势是你可以不添加SharePoint类库或客户端的引用，而是使用HTTP请求访问特定的终结点来获取或更新SharePoint对象，如网站，列表和列表项。可以查看之前的文章了解SharePoint REST接口和架构的概述。

在之后的文章中也会对每个操作进行细致的介绍。

在SharePoint REST服务中的HTTP操作

SharePoint REST服务的终结点与客户端对象模型是对应的关系。通过使用HTTP请求，你可以使用REST终结点来对SharePoint对象执行经典的增删查改操作，如列表和网站。

通常情况下，终结点的读取操作对应HTTP的GET方法，更新对应POST，更新或添加操作对应PUT。在SharePoint中，使用POST来创建如列表或网站的SharePoint对象，方式是通过SharePoint REST服务发送包含对象定义的POST命令到集合终结点来创建对象，比如发送请求到http://<site url>/_api/web/lists来创建一个列表。

对于POST操作，任何不必填的属性都会被设置为它们的默认值。如果你想要通过POST操作设置只读属性，服务会返回异常。

使用PUT和MERGE操作来更新已经存在的SharePoint对象。任何一个表示设置属性的服务终结点都支持PUT和MERGE两种请求。对于MERGE请求，设置属性是可选的，任何没在请求中显式声明的属性都将保留当前的属性值。但是对于PUT操作，相当于刷新，任何没在请求中显式声明的属性都将被设置为默认值。而且，如果你不指定所有必填的属性，服务会返回异常。

使用HTTP的DELETE操作请求指定的终结点来删除SharePoint对象，对于能够回收的对象如列表、文件和列表项，执行的是删除到回收站的操作。

通过SharePoint REST接口来读取数据

使用SharePoint内置的REST，你可以构建一个使用OData标准的REST的HTTP请求，跟你想要使用的客户端对象模型是对应的。每个SharePoint对象都暴露在一个SharePoint网站的终结点，它们的数据是XML或者JSON格式。你可以使用任何语言构建HTTP请求，不只限于JavaScript和C#。

从REST终结点读取信息，你必须了解终结点的URL和暴露在其上的SharePoint对象的OData描述。例如，获取SharePoint网站的所有列表信息，你可以使用GET操作的请求到http://<site url>/_api/web/lists。你可以在浏览器中访问这个URL来查看返回的XML。当你在代码中执行请求的时候，你可以指定获取JSON还是XML格式的数据。

下面的代码展示了如何通过JQuery使用GET请求来返回一个网站的所有列表数据JSON数据。这里假设你有一个可用的OAuth访问令牌存储在accessToken变量中。当你在网站内部进行调用是不需要这个令牌的。注意你是不能通过运行在客户端的浏览器来获取访问令牌的，而是必须在服务器上获取。关于如何获取访问令牌，我们将在之后的文章中进行介绍。

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

如果使用SharePoint跨域库的话，代码会有一些不同。在这种情况下你不需要提供访问令牌。下面的代码展示了在使用跨域库时请求的样子，取而代之的会获取XML类型的返回数据。关于跨域库的使用以后有机会也会给大家进行分享。

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

下面的代码展示了如何用C#获取相关数据的示例，同样假定你已经获取到了访问令牌。

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

获取资源未返回的属性

在你获取一个资源时会返回许多属性值，但是有些属性你必须显示地调用REST终结点进行获取，就像CSOM中有些属性需要显示声明来Load。比如从一个文件资源获取Author属性：

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

使用REST接口进行写入数据

你可以通过REST形式的HTTP请求更新SharePoint对象，和读取数据类似。一个关键的不同是写数据时需要使用POST请求，在更新SharePoint对象时，还要传递PUT或MERGE到X-HTTP-Method属性中。

另一个在创建、更新和删除SharePoint对象时需要的重要考虑是如果你使用的不是OAuth来授权你的请求的话，这些操作需要服务器的请求表单摘要值作为请求头中X-RequestDigest的值。你可以通过一个空白主体的POST请求到链接http://<siteurl>/_api/contextinfo来获取这个值（d:FormDigestValue节点），下面的代码展示了如何通过C#请求contextinfo。

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

如果你使用了脚本跨域库，SP.RequestExecutor会负责获取和发送摘要值。

如果你创建的是SharePoint托管的Add-in，你就不需要创建额外的HTTP请求来获取表单摘要值了，你可以通过在SharePoint页面上通过脚本来获取，如下代码，使用JQuery来创建一个列表。

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

下面的示例展示了如何更新上面创建的列表，更新了列表的标题。

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

下面的代码展示了如何创建一个网站。

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