使用 OData 从 SharePoint Server 请求 Excel 工作簿数据
注意
Excel Services REST API 适用于本地 SharePoint 和 SharePoint 2016。 对于 Office 365 教育版、商业版和企业版帐户,请使用属于 Microsoft Graph 终结点的 Excel REST API。
OData 使用 URL 请求资源中的信息。 你使用查询选项以特定方式生成 URL 以返回正在请求的信息。 以下 URL 显示了典型 OData 请求的外观:
http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$top=20
此示例 OData 请求已进行结构化,它将获取名为 Table1 的表中的前 20 行,该表位于存储在 contoso1 服务器上的 Documents 文件夹中的工作簿 ProductSales.xlsx 中。 URL 使用系统查询选项 $top 指定要返回的行数。仔细查看 URL,可以看到其三部分结构:服务根 URI;资源路径;和查询选项。
服务根 URI
此 URL 的起始部分称作服务根,它对于您向 SharePoint 服务器发起的每个 OData 请求保持一致(服务器的名称除外)。 它包括存储工作簿的 SharePoint 服务器的名称以及路径 _vti_bin/ExcelRest.aspx,如下面的示例所示:
http://contoso1/_vti_bin/ExcelRest.aspx
资源路径
此 URL 的第二个部分包含 Excel 工作簿的路径,并指定这是一个 OData 请求:/Documents/ProductSales.xlsx/OData
系统查询选项
此 URL 的第三部分提供了针对请求的系统查询选项。 查询选项始终以美元符号 ($) 开头并将作为查询参数追加到 URI 的末尾。 在此示例中,请求针对的是名为 Table1 的表中的前 20 行:/Table1?$top=20
系统查询选项提供了获取资源中的特定数据的方式。 Excel Services OData 实现支持下面一节中列出的大量查询选项。
Excel Services OData 实现支持大量标准 OData 系统查询选项。 这些查询选项是 OData 请求的核心,因为您将使用这些选项指定要从资源中获取的数据。 下表列出了 Excel Services OData 实现当前支持的系统查询选项。
表 1. Excel Services OData 系统查询选项
系统查询选项 | 说明 |
---|---|
<tableName> |
返回由 <tableName> 指定的表的所有行,其中 <tableName> 是包含要检索的行的 Excel 工作簿中表的名称。 重要说明:这种形式的 OData 请求一次返回不超过 500 行。 每组 500 行构成一页。 若要在超过 500 行的表中其他页面中获取行,请使用 $skiptoken 查询选项(如下所示)。以下示例返回 ProductSales.xlsx 工作簿中 Table1 中第 500 行及其之前的所有行。 |
$metadata | 返回指定工作簿中的所有可用表以及每个表中所有行的类型信息。 以下示例返回 ProductSales.xlsx 工作簿中的表以及这些表的类型信息。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/$metadata |
$orderby | 返回指定表中的行,这些行按 $orderby 指定的值进行排序。 下面的示例返回 ProductSales.xlsx 工作簿中 Table1 的所有行,这些行按“名称”列进行排序。 注意:$orderby 的默认值为 ascending。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$orderby=Name |
$top | 返回表中的 N 个行,其中 N 是由 $top 的值指定的数字。 以下示例返回 ProductSales.xlsx 工作簿中的 Table1 中的前 5 个行,这些行按 Name 列进行排序。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$orderby=Name&$top=5 |
$skip | 跳过 N 个行(其中 N 是由 $skip 的值指定的数字),然后返回表的剩余行。 以下示例返回 ProductSales.xlsx 工作簿中的 Table1 中的第 5 行后面的所有剩余行。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$skip=5 |
$skiptoken | 寻找第 N 行(其中 N 是由 $skiptoken 的值指示的行顺序位置),然后返回从第 N + 1 行开始的所有剩余行。 由于集合是从 0 开始的,因此第 2 行由 $skiptoken=1 指示。 以下示例返回 ProductSales.xlsx 工作簿中的 Table1 中的第 2 行后面的所有剩余行。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$skiptoken=1 还可以使用 $skiptoken 查询选项从包含 500 多行的表中获取第一页之后的页面中的行。 以下示例说明如何从包含 500 个行以上的表中获取第 500 行及其后面的行。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$skiptoken=499 |
$filter | 返回满足由 $filter 的值指定的条件的行的子集。 有关可与 $filter 一起使用的运算符和函数集的详细信息,请参阅 OData 文档。 以下示例仅返回其 Price 列的值大于 100 的行。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$filter = 价格 g t 100 |
$format | Atom XML 格式是唯一受支持的值,且是 $format 查询选项的默认值。 |
$select | 返回 $select 指定的实体。 以下示例选择 ProductSales.xlsx 工作簿中的 Table1 中的 Name 列。 http://contoso1/_vti_bin/ExcelRest.aspx/Documents/ProductSales.xlsx/OData/Table1?$select=Name |
$inlinecount | 返回指定表中的行数。 $ inlinecount 只能使用以下 2 个值之一。
|