使用 REST 处理列表和列表项Working with lists and list items with REST

提示

SharePoint Online(和本地 SharePoint 2016 及更高版本)REST 服务支持使用 OData $batch 查询选项,将多个请求合并到一个服务调用中。The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. 有关详细信息和代码示例链接,请参阅使用 REST API 发出批处理请求For details and links to code samples, see Make batch requests with the REST APIs.

先决条件Prerequisites

若要更好地理解本主题,需要已熟悉主题了解 SharePoint REST 服务使用 SharePoint REST 端点完成基本操作This topic assumes that you're already familiar with the topics Get to know the SharePoint REST service and Complete basic operations using SharePoint REST endpoints. 本主题不随附代码片段。It doesn't provide code snippets.

使用 REST 检索列表和列表属性Retrieving lists and list properties with REST

以下示例演示在知道特定列表的 GUID 时如何检索该列表。The following example shows how to retrieve a specific list if you know its GUID.

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

备注

如果想要以 JSON 格式响应,请在 Accept 标头中使用 application/json;odata=verboseIf you want the response in JSON, use application/json;odata=verbose in the Accept header.

如果想要以 Atom 格式响应,请在 Accept 标头中使用 application/atom+xmlIf you want the response in Atom format, use application/atom+xml in the Accept header.

以下示例演示在知道特定列表的标题时如何检索该列表。The following example shows how to retrieve a specific list if you know its title.

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

以下 XML 显示了 ** 请求 XML 内容类型时返回的列表属性** 的示例。The following XML shows an example of the list properties that are returned when you request the XML content type.

<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 属性传递。The ListItemEntityTypeFullName property (SP.Data.ProjectPolicyItemListItem in the previous example) is especially important if you want to create and update list items. This value must be passed as the type property in the metadata that you pass in the body of the HTTP request whenever you create and update list items.

通过 REST 使用列表Working with lists by using REST

以下示例演示如何创建列表。The following example shows how to create a list.

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 方法更新列表**。The following example shows how to update a list by using the MERGE method.

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"
}

以下示例演示如何 ** 为列表创建自定义字段**。The following example shows how to create a custom field for a list.

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"
}

以下示例演示如何删除列表。The following example shows how to delete a list.

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}"

查找列更改Lookup column changes

使用 REST API 列表在列表中引用查找列时,使用查找列的显示名称,而不是内部名称。When referring to a lookup column inside a list using REST API, use the display name of the lookup column instead of the internal name.

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

使用 REST 处理列表项Working with list items by using REST

检索所有列表项Retrieve all list items

以下示例显示如何检索列表的所有项。The following example shows how to retrieve all of a list's items.

备注

  • 查询列表项时 OData $skip 查询参数无效。The OData $skip query parameter doesn't work when querying list items. 在很多情况下,可改用 $skiptoken 选项。In many situations, you can use the $skiptoken option instead.
  • 默认情况下,这将返回前 100 个项。By default, this will return the first 100 items. 要详细了解如何控制项目和分页等的数量,请参阅 OData 查询选项相关文档More information on controlling the number of items, paging, etc. see the documentation on OData Query operations
GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

检索特定列表项Retrieve specific list item

以下示例演示如何检索特定列表项。The following example shows how to retrieve a specific list item.

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

以下 XML 显示请求 XML 内容类型时返回的列表项属性的示例。The following XML shows an example of the list item properties that are returned when you request the XML content type.

<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>

以数据流的形式检索项目Retrieve items as a stream

检索有关列表及其数据的信息。Retrieves information about the list and its data. 你可以使用此 API 检索列表项,以防它们使用查阅或托管元数据等复杂字段。Using this API you can retrieve list items in case they use complex fields such as lookups or managed metadata.

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 参数RenderListDataAsStream URI parameters

以下属性可作为查询字符串参数进行添加,以控制返回的数据。Following properties can be added as query string parameters to manipulate the returned data.

属性Property 说明Description 类型Type 示例Example
CascDelWarnMessage 指定存在级联删除警告时是否应显示一条消息Specifies if a message should be displayed if there's a cascade deletion warning numbernumber 1
DrillDown 指示分组视图中的某些组已展开。Specifies that some groups in a grouped view are expanded. GroupString 配合使用。Used with GroupString. stringstring
GroupString 用于向下钻取功能的组标识符。Group identifier used for drill-down feature. stringstring
HasOverrideSelectCommand 用于确保存在某些字段,以实现 SharePoint ListView 控件的正常运行。Used to ensure that certain fields are present for proper functioning of the SharePoint ListView control. 字符串string
Field 指定应包含的特殊字段。Specifies a special field that should be included. 字符串string
FieldInternalName 用于在列表中存在外部数据源时标识一个字段。Used to identify a field when a list has an external data source. 还用于在对自定义字段进行筛选时。Also used when filtering on a custom field. 字符串string
Filter 指定请求的视图是否应应用某个筛选器。Specifies whether the requested view should have a filter applied. 字符串string
FilterData 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData1 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData2 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData3 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData4 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData5 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData6 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData7 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData8 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData9 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterData10 通过特定筛选器指定的数据。Data specified by a particular filter. 字符串string
FilterField 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string
FilterField1 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField2 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField3 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField4 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField5 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField6 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField7 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField8 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField9 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterField10 应用于视图的特定筛选器的筛选字段名称。A filter field name for a specific filter that is applied to the view. 字符串string ID
FilterFields 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields1 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields2 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields3 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields4 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields5 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields6 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields7 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields8 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields9 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterFields10 为乘数筛选器指定进行筛选的多个字段。Specifies multiple fields that are being filtered on for a multiplier filter. 字符串string
FilterValue 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring
FilterValue1 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue2 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue3 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue4 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue5 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue6 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue7 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue8 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue9 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValue10 与特定筛选器关联的筛选值。The filter value associated with a particular filter. 例如,FilterField3 与 FilterValue3 相关联,依此类推。For example, FilterField3 goes with FilterValue3, and so forth. stringstring 1
FilterValues 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues1 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues2 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues3 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues4 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues5 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues6 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues7 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues8 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues9 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterValues10 与 FilterFields 乘数筛选器配合使用。Used with FilterFields for multiplier filter. 例如,FilterFields3 将与 FilterValues3 配合使用,依此类推。For example, FilterFields3 would go with FilterValues3, and so forth. stringstring
FilterLookupId 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId1 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId2 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId3 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId4 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId5 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId6 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId7 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId8 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId9 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterLookupId10 对查阅字段进行筛选时使用。Used when filtering on a lookup field. 这是外部列表中具有正在被筛选的值的项目 id。This is the item id in the foreign list that has a value that is being filtered on. 字符串string
FilterOnly 字符串string
FilterOp 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp1 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp2 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp3 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp4 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp5 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp6 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp7 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp8 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp9 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
FilterOp10 筛选运算符。Filter operator. 使用除 Eq 之外的其他运算符(GeqLeq 等)进行筛选时使用Used when filtering with other operators than Eq (Geq, Leq etc.) stringstring Geq
ID 要搜索其信息的项目的项目 id。The item id of the item whose information is being sought. 数字number
InplaceSearchQuery 完整列表搜索的搜索词。Search term for a full list search. stringstring
InplaceFullListSearch 一个指定是否有完整列表搜索的布尔值。A boolean that specifies whether there's a full list search. stringstring
IsCSR 此视图是否为客户端呈现视图。Whether this view is a client side rendered view. 字符串string
CustomAction 字符串string
IsGroupRender 用于设置 SPView 的 IsGroupRender 属性。Used to set the IsGroupRender property of the SPView. 字符串string
IsRibbon 字符串string
IsXslView 此视图是否为 xslt 列表视图。Whether this view is an xslt list view. 字符串string
List stringstring
ListId stringstring
ListViewPageUrl 字符串string
OverrideScope 用于重写在呈现视图上的作用范围:SPView.ScopeUsed to override a scope on the rendered view: SPView.Scope stringstring
OverrideSelectCommand 用于确保查询中存在某些字段,不管这些字段是否是显式包含在视图中。Used to make sure that certain fields are present in the query regardless of whether they're explicitly included in the view. stringstring
PageFirstRow 有关请求的第一行的分页信息。Paging information about the first row that is requested. 用于分页列表视图。Used for paging list views. 字符串string
PageLastRow 有关请求的最后一行的分页信息。Paging information about the last row that is requested. 用于分页列表视图。Used for paging list views. 字符串string
RootFolder 视图所显示的文件夹。The folder that the view is displaying. 字符串string
SortField 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField1 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField2 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField3 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField4 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField5 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField6 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField7 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField8 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField9 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortField10 视图应使用的排序依据字段。A field that the view should be sorted on. 字符串string ID
SortFields 指定用于排序的首个字段的名称Specifies the name of the first field to sort by 字符串string
SortFieldValues 指定用于排序的首个字段的名称Specifies the name of the first field to sort by 字符串string
SortDir 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir1 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir2 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir3 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir4 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir5 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir6 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir7 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir8 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir9 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
SortDir10 应用于视图的临时性排序的排序方向。The sort direction of an ad hoc sort that is being applied to the view. 字符串string Desc
View 指定将用于呈现列表的基本视图。Specifies the base view that will be used to render the list. GUIDGUID 3d13559e-3071-5000-76b8-8f1ca6b835f0
ViewPath 指定将用于呈现列表的视图的路径。Specifies the path of the view that will be used to render the list. 如果已指定 ViewId,则将使用 ViewId,并且该参数将被忽略。If ViewId is given, then the ViewId will be used and this parameter will be ignored. stringstring
ViewCount 当页面上有多个列表视图时,它将识别其中的一个。When multiple list views are on a page, this identifies one of them. 字符串string
ViewId 指定将用于呈现列表的基本视图。Specifies the base view that will be used to render the list. 临时参数将应用到此视图上方。ad-hoc parameters will be applied on top of this view. 如果已指定 ViewXmlBaseViewId,则将使用 ViewXml,并且临时参数将被忽略。If both ViewXml and BaseViewId are given, then the ViewXml will be used and the ad-hoc parameters will be ignored. stringstring
WebPartId 显示此视图的列表视图 Web 部件的 id。The id of the list view web part that is showing this view. stringstring

RenderListDataAsStream 正文参数属性RenderListDataAsStream body parameter properties

属性Property 说明Description 类型Type 示例Example
AddRequiredFields 指定是否应返回必填的字段Specifies if required fields should be returned or not 布尔值bool true
AllowMultipleValueFilterForTaxonomyFields 指定是否允许对分类字段使用多值筛选Specifies if multi value filtering is allowed for taxonomy fields or not 布尔值bool true
DatesInUtc 指定返回的 DateTime 字段是使用 UTC 时间还是本地时间。Specifies if we return DateTime field in UTC or local time. 布尔值bool true
ExpandGroups 指定是否应扩展分组。Specifies if the grouping should be expanded or not. 布尔值bool true
FirstGroupOnly 指定是否应只返回第一个组(而不考虑视图架构)。Specifies if only the first group should be returned or not (regardless of view schema). 布尔值bool true
FolderServerRelativeUrl 指定要从其中返回项目的文件夹的 URL。Specifies the url to the folder from which to return items. 字符串string /sites/team-a/lists/Orders/Europe
ImageFieldsToTryRewriteToCdnUrls 逗号分隔的字段名称列表,这些字段的值应该重写到 CDN URLComma-separated list of field names whose values should be rewritten to CDN URLs 字符串string ArticleImage,SecondaryImage
OverrideViewXml 指定重写 XML 以与视图 CAML 结合。Specifies the override XML to be combined with the View CAML. 仅适用于视图 CAML 的 Query/Where 部分。Applies only to the Query/Where part of the View CAML. 字符串string <Query><Where><Gt><FieldRef Name=\"OrderCount\" /><Value Type=\"Number\">3</Value></Gt></Where></Query>
Paging 指定分页信息。Specifies the paging information. 字符串string
RenderOptions 指定要返回的输出的类型。Specifies the type of output to return. SPRenderListDataOptionsSPRenderListDataOptions 请参阅下一部分,了解可能的值。See the next section for possible values. 可通过一次性添加多个值的方式来指定多个值You can specify multiple values by adding their values together
ReplaceGroup 指定是否应替换分组来处理 GroupBy 限制。Specifies if the grouping should be replaced or not to deal with GroupBy throttling. 布尔值bool true
ViewXml 指定 CAML 视图 XML。Specifies the CAML view XML. stringstring
SPRenderListDataOptions 选项SPRenderListDataOptions options
标签Label 说明Description Value
None 返回默认输出Return default output 0
ContextInfo 返回列表上下文信息Return list context information 1
ListData 返回列表数据(与 None 相同)Return list data (same as None) 2
ListSchema 返回列表架构Return list schema 4
MenuView 返回列表菜单 HTMLReturn HTML for the list menu 8
ListContentType 返回有关列表内容类型的信息。Returns information about list content types. 必须与 ContextInfo 标志组合使用Must be combined with the ContextInfo flag 16
FileSystemItemId 如果可能,返回的列表中的每个列表项都将具有 FileSystemItemId 字段。The returned list will have a FileSystemItemId field on each item if possible. 必须与 ListData 标志组合使用Must be combined with the ListData flag 32
ClientFormSchema 返回客户端窗体架构以添加和编辑项目Returns the client form schema to add and edit items 64
QuickLaunch 返回 QuickLaunch 导航节点Returns QuickLaunch navigation nodes 128
Spotlight 返回聚焦呈现信息Returns Spotlight rendering information 256
Visualization 返回可视化呈现信息Returns Visualization rendering information 512
ViewMetadata 返回有关当前视图的视图 XML 和其他信息Returns view XML and other information about the current view 1024
DisableAutoHyperlink 阻止 AutoHyperlink 在此查询的文本字段上运行Prevents AutoHyperlink from being run on text fields in this query 2048
EnableMediaTAUrls 启用指向媒体 TA 服务的 URL,例如 .thumbnailUrl.videoManifestUrl.pdfConversionUrlsEnables URLs pointing to Media TA service, such as .thumbnailUrl, .videoManifestUrl, .pdfConversionUrls 4096
ParentInfo 返回父文件夹信息Returns parent folder information 8192
PageContextInfo 返回正在呈现的当前列表的页面上下文信息Returns page context info for the current list being rendered 16384
ClientSideComponentManifest 返回与列表相关联的客户端组件清单信息(保留以备今后使用)Return client-side component manifest information associated with the list (reserved for future use) 32768

示例Examples

检索具有特定 ID 的项目Retrieve item with specific 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 降序排序Sort items descending by 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"
...
从指定的文件夹检索项目Retrieve items from the specified folder
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"
  }
}
检索列表架构Retrieve list schema
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
  }
}
检索有关列表内容类型的信息Retrieve information about list content types
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
  }
}

创建列表项Create list item

下面的示例展示了如何创建列表项。The following example shows how to create a list item.

备注

若要执行此操作,您必须知道列表的 ListItemEntityTypeFullName 属性并将它作为 HTTP 请求正文中的 type 的值传递。To do this operation, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body. 下面是获取 ListItemEntityTypeFullName 的一个 rest 调用示例Following is a sample rest call to get the ListItemEntityTypeFullName

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"
}

在文件夹中创建列表项Create list item in a folder

下面的示例展示了如何在文件夹中创建列表项。The following example shows how to create a list item in a folder.

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
}

请求属性详细信息Request property details

属性Property 说明Description
listItemCreateInfo 有关用于创建该项的列表和文件夹的信息Information about the list and folder where the item should be created
listItemCreateInfo.FolderPath.DecodedUrl 用于创建该项的文件夹的绝对 URLAbsolute URL of the folder where the item should be created
listItemCreateInfo.UnderlyingObjectType 要创建的项目的类型。Type of item to create. 有关详细信息,请参阅 FileSystemObjectTypeFor more information, see FileSystemObjectType
formValues 在新建项目上设置的字段名称和值组成的数组Array of field names and values to set on the newly created item
bNewDocumentUpdate 设置为 false 以创建列表项Set to false to create a list item

响应Responses

名称Name 类型Type 说明Description
200 OK200 OK 布尔值Boolean 成功Success
{
  "value": [
    {
      "ErrorMessage": null,
      "FieldName": "Title",
      "FieldValue": "Item",
      "HasException": false,
      "ItemId": 0
    },
    {
      "ErrorMessage": null,
      "FieldName": "Id",
      "FieldValue": "1",
      "HasException": false,
      "ItemId": 0
    }
  ]
}

value 属性包含创建列表项时设置的属性的列表。The value property contains the list of properties that have been set when creating the list item.

更新列表项Update list item

下面的示例展示了如何更新列表项。The following example shows how to update a list item.

备注

若要执行此操作,您必须知道列表的 ListItemEntityTypeFullName 属性并将它作为 HTTP 请求正文中的 type 的值传递。To do this operation, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.

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"
}

删除列表项Delete list item

以下示例演示如何删除列表项。The following example shows how to delete a list item.

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 值确定文档和列表项的版本控制Using ETag values to determine document and list item versioning

SharePoint REST 服务符合 OData 标准,使用 SharePoint 列表和列表项的标头 ETagsThe SharePoint REST service, which follows the OData standard, uses Header ETags of SharePoint lists and list items. 若要在执行 PUTMERGEDELETE 请求时检查项的版本,请在 If-Match HTTP 请求头中指定 ETagTo check on an item's version when you perform a PUT, MERGE, or DELETE request, specify an ETag in the If-Match HTTP request header.

如果你在请求中指定的 ETag 与服务器上文档或列表项的 ETag 不匹配,根据 OData 规范,REST 服务将返回 412 异常。If the ETag you specify in your request doesn't match the ETag of the document or list item on the server, the REST service returns a 412 exception, per the OData specification.

  • 若要不考虑版本强制覆盖该项,请将 ETag 值设置为 “*”To force an overwrite of the item regardless of version, set the ETag value to "*".
  • 如果不指定 ETag,SharePoint 将不考虑版本覆盖该项。If you do not specify an ETag, SharePoint overwrites the item regardless of version.

在 SharePoint 中,ETag 只适用于 SharePoint 列表和列表项。Within SharePoint, ETags apply only to SharePoint lists and list items.

另请参阅See also