使用 REST 处理列表和列表项

提示

SharePoint Online（和本地 SharePoint 2016 及更高版本）REST 服务支持使用 OData $batch 查询选项，将多个请求合并到一个服务调用中。 有关详细信息和代码示例链接，请参阅使用 REST API 发出批处理请求。

先决条件

若要更好地理解本主题，需要已熟悉主题了解 SharePoint REST 服务和使用 SharePoint REST 端点完成基本操作。 本主题不随附代码片段。

使用 REST 检索列表和列表属性

以下示例演示在知道特定列表的 GUID 时如何检索该列表。

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

注意

如果想要以 JSON 格式响应，请在 Accept 标头中使用 application/json;odata=verbose。

如果想要以 Atom 格式响应，请在 Accept 标头中使用 application/atom+xml。

以下示例演示在知道特定列表的标题时如何检索该列表。

GET https://{site_url}/_api/web/lists/GetByTitle('List Title')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

以下 XML 显示了 请求 XML 内容类型时返回的列表属性 的示例。

<content type="application/xml">
  <m:properties>
    <d:AllowContentTypes m:type="Edm.Boolean">true</d:AllowContentTypes>
    <d:BaseTemplate m:type="Edm.Int32">100</d:BaseTemplate>
    <d:BaseType m:type="Edm.Int32">0</d:BaseType>
    <d:ContentTypesEnabled m:type="Edm.Boolean">false</d:ContentTypesEnabled>
    <d:Created m:type="Edm.DateTime">2012-06-26T23:15:58Z</d:Created>
    <d:DefaultContentApprovalWorkflowId m:type="Edm.Guid">00000000-0000-0000-0000-000000000000</d:DefaultContentApprovalWorkflowId>
    <d:Description>A list created by Project Based Retention used to store Project Policy Items.</d:Description>
    <d:Direction>none</d:Direction>
    <d:DocumentTemplateUrl m:null="true" />
    <d:DraftVersionVisibility m:type="Edm.Int32">0</d:DraftVersionVisibility>
    <d:EnableAttachments m:type="Edm.Boolean">true</d:EnableAttachments>
    <d:EnableFolderCreation m:type="Edm.Boolean">false</d:EnableFolderCreation>
    <d:EnableMinorVersions m:type="Edm.Boolean">false</d:EnableMinorVersions>
    <d:EnableModeration m:type="Edm.Boolean">false</d:EnableModeration>
    <d:EnableVersioning m:type="Edm.Boolean">false</d:EnableVersioning>
    <d:EntityTypeName>ProjectPolicyItemList</d:EntityTypeName>
    <d:ForceCheckout m:type="Edm.Boolean">false</d:ForceCheckout>
    <d:HasExternalDataSource m:type="Edm.Boolean">false</d:HasExternalDataSource>
    <d:Hidden m:type="Edm.Boolean">true</d:Hidden>
    <d:Id m:type="Edm.Guid">74de3ff3-029c-42f9-bd2a-1e9463def69d</d:Id>
    <d:ImageUrl>/_layouts/15/images/itgen.gif</d:ImageUrl>
    <d:IrmEnabled m:type="Edm.Boolean">false</d:IrmEnabled>
    <d:IrmExpire m:type="Edm.Boolean">false</d:IrmExpire>
    <d:IrmReject m:type="Edm.Boolean">false</d:IrmReject>
    <d:IsApplicationList m:type="Edm.Boolean">false</d:IsApplicationList>
    <d:IsCatalog m:type="Edm.Boolean">false</d:IsCatalog>
    <d:IsPrivate m:type="Edm.Boolean">false</d:IsPrivate>
    <d:ItemCount m:type="Edm.Int32">0</d:ItemCount>
    <d:LastItemDeletedDate m:type="Edm.DateTime">2012-06-26T23:15:58Z</d:LastItemDeletedDate>
    <d:LastItemModifiedDate m:type="Edm.DateTime">2012-06-26T23:15:59Z</d:LastItemModifiedDate>
    <d:ListItemEntityTypeFullName>SP.Data.ProjectPolicyItemListItem</d:ListItemEntityTypeFullName>
    <d:MultipleDataList m:type="Edm.Boolean">false</d:MultipleDataList>
    <d:NoCrawl m:type="Edm.Boolean">true</d:NoCrawl>
    <d:ParentWebUrl>/</d:ParentWebUrl>
    <d:ServerTemplateCanCreateFolders m:type="Edm.Boolean">true</d:ServerTemplateCanCreateFolders>
    <d:TemplateFeatureId m:type="Edm.Guid">00bfea71-de22-43b2-a848-c05709900100</d:TemplateFeatureId>
    <d:Title>Project Policy Item List</d:Title>
  </m:properties>
</content>

注意

如果您要创建和更新列表中的项，ListItemEntityTypeFullName 属性（前面示例中的 SP.Data.ProjectPolicyItemListItem）特别重要。 每当您创建和更新列表项时，此值必须作为在您的 HTTP 请求的正文中传递的元数据中的 type 属性传递。

通过 REST 使用列表

以下示例演示如何创建列表。

POST https://{site_url}/_api/web/lists
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.List"
  },
  "AllowContentTypes": true,
  "BaseTemplate": 100,
 "ContentTypesEnabled": true,
 "Description": "My list description",
 "Title": "Test"
}

以下示例演示如何 使用 MERGE 方法更新列表。

POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.List"
  },
  "Title": "New title"
}

以下示例演示如何 为列表创建自定义字段。

POST https://{site_url}/_api/web/lists(guid'{list_guid}')/Fields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.Field"
  },
  "Title": "field title",
  "FieldTypeKind": FieldType value,
  "Required": "true/false",
  "EnforceUniqueValues": "true/false",
  "StaticName": "field name"
}

以下示例演示如何删除列表。

POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"

查找列更改

使用 REST API 列表在列表中引用查找列时，使用查找列的显示名称，而不是内部名称。

GET https://{site_url}/_api/web/lists/getbytitle('ListName')/Items?&$filter=LookupColumnId eq 1
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

使用 REST 处理列表项

检索所有列表项

以下示例显示如何检索列表的所有项。

注意

• 查询列表项时 OData $skip 查询参数无效。 在很多情况下，可改用 $skiptoken 选项。
• 默认情况下，这将返回前 100 个项。 要详细了解如何控制项目和分页等的数量，请参阅 OData 查询选项相关文档

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

检索特定列表项

以下示例演示如何检索特定列表项。

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

以下 XML 显示请求 XML 内容类型时返回的列表项属性的示例。

<content type="application/xml">
  <m:properties>
    <d:FileSystemObjectType m:type="Edm.Int32">0</d:FileSystemObjectType>
    <d:Id m:type="Edm.Int32">1</d:Id>
    <d:ID m:type="Edm.Int32">1</d:ID>
    <d:ContentTypeId>0x010049564F321A0F0543BA8C6303316C8C0F</d:ContentTypeId>
    <d:Title>an item</d:Title>
    <d:Modified m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Modified>
    <d:Created m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Created>
    <d:AuthorId m:type="Edm.Int32">11</d:AuthorId>
    <d:EditorId m:type="Edm.Int32">11</d:EditorId>
    <d:OData__UIVersionString>1.0</d:OData__UIVersionString>
    <d:Attachments m:type="Edm.Boolean">false</d:Attachments>
    <d:GUID m:type="Edm.Guid">eb6850c5-9a30-4636-b282-234eda8b1057</d:GUID>
  </m:properties>
</content>

以数据流的形式检索项目

检索有关列表及其数据的信息。 你可以使用此 API 检索列表项，以防它们使用查阅或托管元数据等复杂字段。

POST https://{site_url}/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json;odata=nometadata"

{
  "parameters": {
    "AddRequiredFields": "true",
    "DatesInUtc": "true",
    "RenderOptions": 17
  }
}

RenderListDataAsStream URI 参数

以下属性可作为查询字符串参数进行添加，以控制返回的数据。

属性	说明	类型	示例
CascDelWarnMessage	指定存在级联删除警告时是否应显示一条消息	number	1
DrillDown	指示分组视图中的某些组已展开。 与 GroupString 配合使用。	string
GroupString	用于向下钻取功能的组标识符。	string
HasOverrideSelectCommand	用于确保存在某些字段，以实现 SharePoint ListView 控件的正常运行。	字符串
Field	指定应包含的特殊字段。	字符串
FieldInternalName	用于在列表中存在外部数据源时标识一个字段。 还用于在对自定义字段进行筛选时。	字符串
Filter	指定请求的视图是否应应用某个筛选器。	字符串
FilterData	通过特定筛选器指定的数据。	字符串
FilterData1	通过特定筛选器指定的数据。	字符串
FilterData2	通过特定筛选器指定的数据。	字符串
FilterData3	通过特定筛选器指定的数据。	字符串
FilterData4	通过特定筛选器指定的数据。	字符串
FilterData5	通过特定筛选器指定的数据。	字符串
FilterData6	通过特定筛选器指定的数据。	字符串
FilterData7	通过特定筛选器指定的数据。	字符串
FilterData8	通过特定筛选器指定的数据。	字符串
FilterData9	通过特定筛选器指定的数据。	字符串
FilterData10	通过特定筛选器指定的数据。	字符串
FilterField	应用于视图的特定筛选器的筛选字段名称。	字符串
FilterField1	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField2	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField3	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField4	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField5	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField6	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField7	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField8	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField9	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterField10	应用于视图的特定筛选器的筛选字段名称。	字符串	ID
FilterFields	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields1	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields2	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields3	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields4	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields5	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields6	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields7	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields8	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields9	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterFields10	为乘数筛选器指定进行筛选的多个字段。	字符串
FilterValue	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string
FilterValue1	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue2	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue3	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue4	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue5	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue6	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue7	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue8	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue9	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValue10	与特定筛选器关联的筛选值。 例如，FilterField3 与 FilterValue3 相关联，依此类推。	string	1
FilterValues	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues1	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues2	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues3	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues4	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues5	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues6	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues7	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues8	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues9	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterValues10	与 FilterFields 乘数筛选器配合使用。 例如，FilterFields3 将与 FilterValues3 配合使用，依此类推。	string
FilterLookupId	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId1	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId2	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId3	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId4	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId5	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId6	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId7	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId8	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId9	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterLookupId10	对查阅字段进行筛选时使用。 这是外部列表中具有正在被筛选的值的项目 id。	字符串
FilterOnly		string
FilterOp	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp1	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp2	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp3	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp4	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp5	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp6	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp7	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp8	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp9	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
FilterOp10	筛选运算符。 使用除 Eq 之外的其他运算符（Geq、Leq 等）进行筛选时使用	string	Geq
ID	要搜索其信息的项目的项目 id。	数字
InplaceSearchQuery	完整列表搜索的搜索词。	string
InplaceFullListSearch	一个指定是否有完整列表搜索的布尔值。	string
IsCSR	此视图是否为客户端呈现视图。	字符串
CustomAction		字符串
IsGroupRender	用于设置 SPView 的 IsGroupRender 属性。	字符串
IsRibbon		字符串
IsXslView	此视图是否为 xslt 列表视图。	字符串
List		string
ListId		string
ListViewPageUrl		字符串
OverrideScope	用于重写在呈现视图上的作用范围：SPView.Scope	string
OverrideSelectCommand	用于确保查询中存在某些字段，不管这些字段是否是显式包含在视图中。	string
PageFirstRow	有关请求的第一行的分页信息。 用于分页列表视图。	字符串
PageLastRow	有关请求的最后一行的分页信息。 用于分页列表视图。	字符串
RootFolder	视图所显示的文件夹。	字符串
SortField	视图应使用的排序依据字段。	字符串	ID
SortField1	视图应使用的排序依据字段。	字符串	ID
SortField2	视图应使用的排序依据字段。	字符串	ID
SortField3	视图应使用的排序依据字段。	字符串	ID
SortField4	视图应使用的排序依据字段。	字符串	ID
SortField5	视图应使用的排序依据字段。	字符串	ID
SortField6	视图应使用的排序依据字段。	字符串	ID
SortField7	视图应使用的排序依据字段。	字符串	ID
SortField8	视图应使用的排序依据字段。	字符串	ID
SortField9	视图应使用的排序依据字段。	字符串	ID
SortField10	视图应使用的排序依据字段。	字符串	ID
SortFields	指定用于排序的首个字段的名称	字符串
SortFieldValues	指定用于排序的首个字段的名称	字符串
SortDir	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir1	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir2	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir3	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir4	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir5	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir6	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir7	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir8	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir9	应用于视图的临时性排序的排序方向。	字符串	Desc
SortDir10	应用于视图的临时性排序的排序方向。	字符串	Desc
View	指定将用于呈现列表的基本视图。	GUID	3d13559e-3071-5000-76b8-8f1ca6b835f0
ViewPath	指定将用于呈现列表的视图的路径。 如果已指定 ViewId，则将使用 ViewId，并且该参数将被忽略。	string
ViewCount	当页面上有多个列表视图时，它将识别其中的一个。	字符串
ViewId	指定将用于呈现列表的基本视图。 临时参数将应用到此视图上方。 如果已指定 ViewXml 和 BaseViewId，则将使用 ViewXml，并且临时参数将被忽略。	string
WebPartId	显示此视图的列表视图 Web 部件的 id。	string

RenderListDataAsStream 正文参数属性

属性	说明	类型	示例
AddRequiredFields	指定是否应返回必填的字段	布尔值	true
AllowMultipleValueFilterForTaxonomyFields	指定是否允许对分类字段使用多值筛选	布尔值	true
DatesInUtc	指定返回的 DateTime 字段是使用 UTC 时间还是本地时间。	布尔值	true
ExpandGroups	指定是否应扩展分组。	布尔值	true
FirstGroupOnly	指定是否应只返回第一个组（而不考虑视图架构）。	布尔值	true
FolderServerRelativeUrl	指定要从其中返回项目的文件夹的 URL。	字符串	/sites/team-a/lists/Orders/Europe
ImageFieldsToTryRewriteToCdnUrls	逗号分隔的字段名称列表，这些字段的值应该重写到 CDN URL	字符串	ArticleImage,SecondaryImage
OverrideViewXml	指定重写 XML 以与视图 CAML 结合。 仅适用于视图 CAML 的 Query/Where 部分。	字符串	<Query><Where><Gt><FieldRef Name=\"OrderCount\" /><Value Type=\"Number\">3</Value></Gt></Where></Query>
Paging	指定分页信息。	字符串
RenderOptions	指定要返回的输出的类型。	SPRenderListDataOptions	请参阅下一部分，了解可能的值。 可通过一次性添加多个值的方式来指定多个值
ReplaceGroup	指定是否应替换分组来处理 GroupBy 限制。	布尔值	true
ViewXml	指定 CAML 视图 XML。	string

SPRenderListDataOptions 选项

标签	说明	值
None	返回默认输出	0
ContextInfo	返回列表上下文信息	1
ListData	返回列表数据（与 None 相同）	2
ListSchema	返回列表架构	4
MenuView	返回列表菜单 HTML	8
ListContentType	返回有关列表内容类型的信息。 必须与 ContextInfo 标志组合使用	16
FileSystemItemId	如果可能，返回的列表中的每个列表项都将具有 FileSystemItemId 字段。 必须与 ListData 标志组合使用	32
ClientFormSchema	返回客户端窗体架构以添加和编辑项目	64
QuickLaunch	返回 QuickLaunch 导航节点	128
Spotlight	返回聚焦呈现信息	256
Visualization	返回可视化呈现信息	512
ViewMetadata	返回有关当前视图的视图 XML 和其他信息	1024
DisableAutoHyperlink	阻止 AutoHyperlink 在此查询的文本字段上运行	2048
EnableMediaTAUrls	启用指向媒体 TA 服务的 URL，例如 .thumbnailUrl、.videoManifestUrl、.pdfConversionUrls	4096
ParentInfo	返回父文件夹信息	8192
PageContextInfo	返回正在呈现的当前列表的页面上下文信息	16384
ClientSideComponentManifest	返回与列表相关联的客户端组件清单信息（保留以备今后使用）	32768

示例

检索具有特定 ID 的项目

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&FilterField1=ID&FilterValue1=1
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
...

将项目按 ID 降序排序

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&SortField=ID&SortDir=Desc
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
...

从指定的文件夹检索项目

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FOrders%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"

{
  "parameters": {
    "FolderServerRelativeUrl": "/sites/team-a/lists/Orders/Europe"
  }
}

检索列表架构

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"

{
  "parameters": {
    "RenderOptions": 4
  }
}

检索有关列表内容类型的信息

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"

{
  "parameters": {
    "RenderOptions": 17
  }
}

创建列表项

下面的示例展示了如何创建列表项。

注意

若要执行此操作，您必须知道列表的 ListItemEntityTypeFullName 属性并将它作为 HTTP 请求正文中的 type 的值传递。 下面是获取 ListItemEntityTypeFullName 的一个 rest 调用示例

GET https://{site_url}/_api/web/lists/GetByTitle('Test')?$select=ListItemEntityTypeFullName
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json;odata=verbose"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.Data.TestListItem"
  },
  "Title": "Test"
}

在文件夹中创建列表项

下面的示例展示了如何在文件夹中创建列表项。

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/AddValidateUpdateItemUsingPath
Authorization: "Bearer " + accessToken
Accept          "application/json;odata=nometadata"
Content-Type    "application/json;odata=nometadata"
X-RequestDigest "The appropriate digest for current site"

{
  "listItemCreateInfo": {
    "FolderPath": {
      "DecodedUrl": "https://{site_url}/lists/Test/Folder/SubFolder"
    },
    "UnderlyingObjectType": 0
  },
  "formValues": [
    {
      "FieldName": "Title",
      "FieldValue": "Item"
    }
  ],
  "bNewDocumentUpdate": false
}

请求属性详细信息

属性	说明
listItemCreateInfo	有关用于创建该项的列表和文件夹的信息
listItemCreateInfo.FolderPath.DecodedUrl	用于创建该项的文件夹的绝对 URL
listItemCreateInfo.UnderlyingObjectType	要创建的项目的类型。 有关详细信息，请参阅 FileSystemObjectType
formValues	在新建项目上设置的字段名称和值组成的数组
bNewDocumentUpdate	设置为 false 以创建列表项

响应

名称	类型	说明
200 OK	布尔值	成功

{
  "value": [
    {
      "ErrorMessage": null,
      "FieldName": "Title",
      "FieldValue": "Item",
      "HasException": false,
      "ItemId": 0
    },
    {
      "ErrorMessage": null,
      "FieldName": "Id",
      "FieldValue": "1",
      "HasException": false,
      "ItemId": 0
    }
  ]
}

value 属性包含创建列表项时设置的属性的列表。

更新列表项

下面的示例展示了如何更新列表项。

注意

若要执行此操作，您必须知道列表的 ListItemEntityTypeFullName 属性并将它作为 HTTP 请求正文中的 type 的值传递。

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.Data.TestListItem"
  },
  "Title": "TestUpdated"
}

删除列表项

以下示例演示如何删除列表项。

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"

使用 ETag 值确定文档和列表项的版本控制

SharePoint REST 服务符合 OData 标准，使用 SharePoint 列表和列表项的标头 ETags。 若要在执行 PUT、MERGE 或 DELETE 请求时检查项的版本，请在 If-Match HTTP 请求头中指定 ETag。

如果你在请求中指定的 ETag 与服务器上文档或列表项的 ETag 不匹配，根据 OData 规范，REST 服务将返回 412 异常。

• 若要不考虑版本强制覆盖该项，请将 ETag 值设置为“*”。
• 如果不指定 ETag，SharePoint 将不考虑版本覆盖该项。

在 SharePoint 中，ETag 只适用于 SharePoint 列表和列表项。

另请参阅

• 了解 SharePoint REST 服务
• SharePoint-Add-in-REST-OData-BasicDataOperations
• SharePoint：使用 REST 对文件和文件夹执行基本的数据访问操作
• SharePoint 加载项的安全数据访问和客户端对象模型
• 在 SharePoint 中处理外部数据
• OData 资源
• 开发 SharePoint 加载项