SharePoint 2013 - REST Service
0. SharePoint 2013使用_api来标识出 REST SERVICE，REST Service其实是 client.svc web service的一部分，但为了简化 REST URI的构造以及缩短REST URI的长度，使用 _api 来替代 _vti_bin/client.svc，例如, 你可以使用 http://server/site/_vti_bin/client.svc/web/lists 来替代 http://server/site/_api/web/lists；然而URL有256字符长度的限制，所以建议使用 _api 惯例；可参考此文章中的 Reference the SharePoint 2013 REST service in your endpoint URI 章节；
SharePoint 2013 REST Syntax Posters.pdf
工具：Chrome浏览器中的 Advanced Rest Client Application插件
1. Search REST API的query(GET)可以设置返回json格式的结果，存储在data.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results中，results是个数据集合，序号从0开始；
2. 使用REST API获取(GET)数据时，若返回多条记录，则返回值存储在data.d.results中，results是个数据集合，序号从0开始，每一个result包含一个对象单元信息，例如：一个List Item的所有属性，如代码所示；若返回单条记录，则返回值存储在data.d中；
{ "__metadata":{"id":"b719e719-e4cc-445c-9c7c-0250aba4338a", "uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)", "etag":"\"4\"","type":"SP.Data.TasksListItem"}, "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/FirstUniqueAncestorSecurableObject"}}, "RoleAssignments":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/RoleAssignments"}}, "AttachmentFiles":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/AttachmentFiles"}}, "ContentType":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/ContentType"}}, "FieldValuesAsHtml":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/FieldValuesAsHtml"}}, "FieldValuesAsText":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/FieldValuesAsText"}}, "FieldValuesForEdit":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/FieldValuesForEdit"}}, "File":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/File"}}, "Folder":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/Folder"}}, "ParentList":{"__deferred":{"uri":"https://gjq-11683d04060f3b.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'b44e6daf-ee1e-4249-987f-2f9305cdc884')/Items(1)/ParentList"}}, "FileSystemObjectType":0, "Id":1, "ContentTypeId":"0x0108005943A401D04CAD47AE81ABAA54AA39A3", "Title":"Test", "PredecessorsId":{"__metadata":{"type":"Collection(Edm.Int32)"},"results":[]}, "Priority":"(2) Normal", "Status":"Not Started", "PercentComplete":0.79, "AssignedToId":11, "TaskGroupId":null, "Body":"<div></div>", "StartDate":"2014-08-10T16:00:00Z", "DueDate":"2014-08-27T16:00:00Z", "RelatedItems":null, "WorkflowLink":null, "OffsiteParticipant":null, "OffsiteParticipantReason":null, "WorkflowOutcome":null, "WorkflowName":null, "GUID":"2c618f60-7fae-4689-a652-52458ae60dd6", "ID":1, "Modified":"2014-08-12T03:41:59Z", "Created":"2014-08-11T01:57:18Z", "AuthorId":11, "EditorId":11, "OData__UIVersionString":"4.0", "Attachments":false }
3. 使用REST API的一些建议：
-
If you’re not using the cross-domain library, include an X-RequestDigest header to send the form digest value in all POST requests and a content-lengthheader for POST requests that send data in the request body.
-
If you're not making cross-domain requests, remove SP.AppContextSite(@target) and ?@target='<host web url>' from the endpoint URI.
-
If you’re using OAuth, include an Authorization header ("Authorization": "Bearer " + <access token>) to send the OAuth access token.
-
If you want the server to return responses in Atom format, remove the "accept": "application/json; odata=verbose" header.
4. 使用REST API获取对象信息时，只能获取到当前级别信息，类似于Client Object Model，比如 /_api/web/lists可以获得所有list信息，但没有list item的信息；例如：一个List的所有属性，
{ "__metadata": { "id":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')", "uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')", "etag":"\"3\"", "type":"SP.List" }, "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/FirstUniqueAncestorSecurableObject"}}, "RoleAssignments":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/RoleAssignments"}}, "ContentTypes":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/ContentTypes"}}, "CreatablesInfo":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/CreatablesInfo"}}, "DefaultView":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/DefaultView"}}, "DescriptionResource":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/DescriptionResource"}}, "EventReceivers":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/EventReceivers"}}, "Fields":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/Fields"}}, "Forms":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/Forms"}}, "InformationRightsManagementSettings":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/InformationRightsManagementSettings"}}, "Items":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/Items"}}, "ParentWeb":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/ParentWeb"}}, "RootFolder":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/RootFolder"}}, "TitleResource":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/TitleResource"}}, "UserCustomActions":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/UserCustomActions"}}, "Views":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/Views"}}, "WorkflowAssociations":{"__deferred":{"uri":"https://gjq-11683d04060f3f.sharepoint.com/BasicOperationApp/_api/Web/Lists(guid'9b64f833-6b28-4bf4-b02d-31e6f1d649e6')/WorkflowAssociations"}}, "AllowContentTypes":true,"BaseTemplate":100,"BaseType":0,"ContentTypesEnabled":false,"CrawlNonDefaultViews":false,"Created":"2014-08-12T05:22:25Z", "DefaultContentApprovalWorkflowId":"00000000-0000-0000-0000-000000000000", "Description":"", "Direction":"none", "DocumentTemplateUrl":null, "DraftVersionVisibility":0, "EnableAttachments":true, "EnableFolderCreation":false, "EnableMinorVersions":false, "EnableModeration":false, "EnableVersioning":false, "EntityTypeName":"AccordionList", "ForceCheckout":false, "HasExternalDataSource":false, "Hidden":false, "Id":"9b64f833-6b28-4bf4-b02d-31e6f1d649e6", "ImageUrl":"/_layouts/15/images/itgen.png?rev=37", "IrmEnabled":false, "IrmExpire":false, "IrmReject":false, "IsApplicationList":false, "IsCatalog":false, "IsPrivate":false, "ItemCount":3, "LastItemDeletedDate":"2014-08-12T05:22:25Z", "LastItemModifiedDate":"2014-08-13T06:16:41Z", "ListItemEntityTypeFullName":"SP.Data.AccordionListItem", "MultipleDataList":false, "NoCrawl":false, "ParentWebUrl":"/", "ParserDisabled":false, "ServerTemplateCanCreateFolders":true, "TemplateFeatureId":"00bfea71-de22-43b2-a848-c05709900100", "Title":"Accordion" }
5. REST Search API时，默认的rowlimit是10，即默认返回10条记录；
6. 使用REST API的POST方法创建新内容时，返回的信息存储在data.d中，比如data.d.Id；
7. REST API 不能修改文件夹的Name，详情请参考此处或者此处；
8. REST API在更新file内容时，只能使用PUT，更新文件的metadata时，需要将文件看作一个item;
If you want to update a file's metadata, you'll have to construct an endpoint that reaches the file as a list item. You can do this because each folder is also a list, and each file is also a list item. Construct an endpoint that looks like this: https://<site url>/_api/web/lists/getbytitle('Documents')/items(<item id>). Working with lists and list items with REST explains how to update a list item's metadata.
9. 使用REST API获取item信息时，Look Up字段会发生一些变化，比如：有一个内部名称为Zone的列，查询出来的数据中找不到Zone列，而会有个ZoneId字段，值为被查询item的ID值；如果想得到Zone的显示名称，可使用$expand来获取：
1. 在$select=中可以写上Zone/Id,Zone/ColumnX;
2. 在$expand=中必须写上Zone;
注：Zone为当前列表的Look up字段；ColumnX为被查询列表的任何字段的内部名称；
10. 如果不使用cross-domain类库，在进行POST操作时，都要在headers中添加X-RequestDigest参数，默认赋值是$("#__REQUESTDIGEST").val()；
11. 过滤操作需要使用$filter，例如，只需要Title字段以“B”开头的数据：$filter=startswith(Title, 'B')；只需要Title字段包含“B”的数据：$filter=substringof('B',Title)；
12. REST API - GET
$.ajax({ url: "https://XXX.sharepoint.com/_api/web/lists/GetByTitle('XXX')/items", type: "GET", headers: {"Accept": "application/json;odata=verbose"}, success: function(data){ if(data.d.results){ var $selectObj = $("<select id='deptSelect'></select>"); $.each(data.d.results, function(index, item){ $selectObj.append($("<option></option>").attr("value", item.ID + item.Title).text(item.Title)); }); $("#getDiv").append($selectObj); $("#getDiv").append("<br/>"+JSON.stringify(data.d.results)); } }, error: function(xhr){ alert(xhr.status+': '+xhr.statusText); } });
注意：由于服务器端分页的限制，默认情况下，每次只能获取100条数据，但可以使用$top参数来指定一次要获取多少条数据，但最大不能超过5000；还可以使用__next来获取下一页的100条数据，请参考此处；
13. REST API - POST (create)
var newItem={ "__metadata":{"type": "SP.Data.Region_x0020_ApproversListItem"}, "Title": "Test Dept", "Region": "GCN" }; $.ajax({ url: "https://XXX.sharepoint.com/_api/web/lists/GetByTitle('XXX')/items", type: "POST", contentType: "application/json;odata=verbose", data: JSON.stringify(newItem), headers: { "Accept": "application/json;odata=verbose", "X-RequestDigest": $("#__REQUESTDIGEST").val() }, success: function(data){ alert(JSON.stringify(data.d.Id)); }, error: function(xhr){ alert(xhr.status+': '+xhr.statusText); } });
14. REST API - POST (update)
var updatedItem={ "__metadata":{"type":"SP.Data.Region_x0020_ApproversListItem"}, "Title": "Test Dept Again" }; $.ajax({ url: "https://XXX.sharepoint.com/_api/web/lists/GetByTitle('XXX')/items(40)", type: "POST", contentType: "application/json;odata=verbose", data: JSON.stringify(updatedItem), headers:{ "ACCEPT": "application/json;odata=verbose", "X-RequestDigest": $("#__REQUESTDIGEST").val(), "X-HTTP-METHOD": "MERGE", "IF-MATCH": "*" }, success: function(){ //此处没有data参数 getListItem(); }, error: function(xhr){ alert(xhr.status+': '+xhr.statusText); } });
15. REST API - DELETE
$.ajax({ url: "https://XXX.sharepoint.com/_api/web/lists/GetByTitle('XXX')/items(43)", type: "POST", headers:{ "Accept": "application/json;odata=verbose", "X-Http-Method": "DELETE", "X-RequestDigest": $("#__REQUESTDIGEST").val(), "If-Match": "*" }, success: function(data){ alert(JSON.stringify(data)); }, error: function(xhr){ alert(xhr.status+': '+xhr.statusText); } });
16. 在进行POST操作时，需要先得到metadata中的type属性值，方法是：http://XXXX/sites/XXX/_api/web/lists/getbytitle('listName')?$select=ListItemEntityTypeFullName
17. SharePoint 2016及 Office 365支持 REST API批量操作（Batch），可参考此处；
18. REST API 使用的uri中，SharePoint名称（比如，列表名，列名）是大小写敏感的，oData的名称是大小写不敏感；在使用$filter等条件语句进行筛选对比时，非数字类型值需要添加单引号，比如 userName eq 'ABC'；
19. 使用REST API获取当前用户的登录名：
<script type="text/javascript"> var userid= _spPageContextInfo.userId; var requestUri = _spPageContextInfo.webAbsoluteUrl + "/_api/web/getuserbyid(" + userid + ")"; var requestHeaders = { "accept" : "application/json;odata=verbose" }; $.ajax({ url : requestUri, contentType : "application/json;odata=verbose", headers : requestHeaders, success : onSuccess, error : onError }); function onSuccess(data, request){ var loginName = data.d.LoginName; alert(loginName); } function onError(error) { alert("error"); } </script>
20. 创建一个 Custom REST Service，可参考此文章；重要一点是：无需修改Web Config文件，只需要在.svc文件声明中加入以下代码即可：
<%@ ServiceHost Language="C#" Debug="true" Service="SPRESTService.CustomRESTService, $SharePoint.Project.AssemblyFullName$" CodeBehind="CustomRESTService.svc.cs" Factory="Microsoft.SharePoint.Client.Services.MultipleBaseAddressWebServiceHostFactory, Microsoft.SharePoint.Client.ServerRuntime, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"%>
如需在声明中使用 token 符 "$SharePoint.Project.AssemblyFullName$"，需要在project文件(.csproj文件) 中加入以下代码：
<PropertyGroup> ... <SandboxedSolution>False</SandboxedSolution> <TokenReplacementFileExtensions>svc</TokenReplacementFileExtensions> </PropertyGroup>
21. 在Custom REST Service时， 每个 OperationContract的 Name属性用于标识这个操作，是唯一的，在返回值中可以体现出来，返回值为 Name + 'Result'，例如，在ajax回调函数中使用时即为 response.GetAllPresidentsResult ；UriTemplate属性是访问此操作的路径，也是唯一的；
22. 若要获取一个web根目录下的所有folder，可以使用一下REST API:
http://site url/_api/web/folders
得到的结果即是在SPD中看到的样子：
REST返回的结果可能还会包含一下以"_vti_"开头的文档库或列表地址，这些是FrontPage的遗产物，无需在意，详情可参考此文章；
23. SharePoint REST API中的 /folders 和 /files 接口都只能得到当前文件夹下的 子文件夹 或者 文件，而不能递归读取所有 子文件夹 或 文件；
http://host url/sites/jacky/_api/Web/GetFolderByServerRelativeUrl('/sites/jacky/Documents')/Files http://host url/sites/jacky/_api/Web/GetFolderByServerRelativeUrl('/sites/jacky/Documents')/Folders
而 /items 接口却可以得到一个 list 或者 library 所有item，包括文件和文件夹；
http://host url/sites/jacky/_api/Web/Lists(guid'9957f1e6-a35a-4888-a770-d5325c5cfe74')/Items
24. $expand 相当于扩展查询，将子查询对象的结果集成到当前这次调用中来，比如：
使用 http://host url/sites/jacky/_api/Web/GetFolderByServerRelativeUrl('/sites/jacky/Documents') 接口我们可以得到Documents 这个文件夹的一些信息，返回结果如下：
如果加上$expand 对象，将 REST URI 改为：http://host url/sites/jacky/_api/Web/GetFolderByServerRelativeUrl('/sites/jacky/Documents')?$expand=Folders,Files 即 加上了 查询Folders 和 Files的子语句，返回的结果为：
相当于，在查询当前文件夹信息的同时，也进行了下面两个查询，并将结果一次性返回：
http://host url/sites/jacky/_api/Web/GetFolderByServerRelativeUrl('/sites/jacky/Documents')/Files http://host url/sites/jacky/_api/Web/GetFolderByServerRelativeUrl('/sites/jacky/Documents')/Folders
25. 在使用$select时，如果需要选择的属性位于一个集合(例如 results)中，那么在路径中可以忽略掉 results (此为虚拟节点)，直接写需要的属性，比如下图，如果需要选择 Title属性，不需要写成：$select=ListItemAllFields/RoleAssignments/results/Member/Users/results/Title，直接写成 $select=ListItemAllFields/RoleAssignments/Member/Users/Title 即可；
26.
