使用 OData 筛选 SharePoint

  • 14 分钟

在本单元中，我们要学习如何在查询 SharePoint 列表和文档库时使用 OData (Open Data Protocol) 筛选器。

为什么使用 OData 筛选器？

为什么要对 SharePoint 使用 OData 筛选器？ 默认情况下，如果没有指定靠前计数或阈值值，列表的获取项目或库的获取文件操作只能检索 SharePoint 的前 100 个项目或文件。 您可以将靠前计数指定为不超过 5000 个项目的默认阈值限制，但是，如果列表或库的项目或文件超过 5000 个，则不会使用“靠前计数”下的条目返回所有数据。 因此，筛选查询可以帮助您创建低于阈值限制的结果。

尝试运行流时，输入大于 5000 的数字会导致流失败。

了解大型列表或库的操作设置

如果列表或库包含超过 100 个项目或文件且不超过 5000 个项目，则只需要调整靠前计数。 在“靠前计数”中，您可以输入最大不超过默认阈值限制 5000 的值。 阈值限制旨在防止此步骤返回超过 5000 个项目。 “靠前计数”可以让您快速从数据中检索最多 5000 个项目。

如果列表或库包含超过 5000 个项目，或者查询返回超过 5000 个项目，则需要启用该步骤的分页。 分页是什么？ 获取项目操作每次获取值时都能一次性获取 100 个项目。 与滚动浏览 SharePoint 列表或库时一样，您也可以滚动到可查看项目底部，而 SharePoint 可以额外获取 100 个项目。 因此，分页可以让获取过程（100 个项目为一批）继续下去。 但是，请记住，分页需要时间，这会减慢您的流程。 启用分页后，操作会重复此过程，返回手动输入的阈值总计值（我们稍后要讨论的另一个必要条目）。

要查找分页设置，请选择“获取项目”或“获取文件”操作右上角的省略号，查看设置。

“获取项目”的屏幕截图，已选择省略号以显示“设置”选项。

在操作设置面板上，将分页选项切换为开启，然后必须在此处为阈值输入一个值。 分页可以从数据源返回 1 到 100,000 个项目，但您只需将其设置为想要返回的项目数量。 最后，选择完成，返回正常设置。

设置面板中的阈值设置有点难以理解，不过可以这样看。 它应与期望 从查询中接收的项目数量相匹配，但不得返回超过 100,000 个项目。 例如，如果将阈值设置为 500，但与查询匹配的项目有 2000 个，则只会收到 500 个项目。 同样，如果将阈值设置为 2000，则将获得期望获取的所有 2000 个项目。

这一点为什么如此重要？ 为什么不能直接使用靠前计数 (5000) 和阈值 (100000) 的最大值？ 因为要求 Power Automate 分页需要时间，还会减慢整个流程。 假设您可以通过 2500 的“靠前计数”值获取期望的所有数据，则无需打开分页，并将最大值应用到阈值，继续对数据进行分页。

继续之前还需要考虑一个因素，如果您希望返回超过 5000 个项目，请始终将“靠前计数”设置为 5000。 “靠前计数”可以快速返回前 5000 个项目，而分页会在前 5000 个项目之后继续获取结果。 二者相互配合。 分页本身确实有效，但它必须继续一次性获取 100 个项目，才能完成相同的工作。

如何在筛选器查询中使用 OData

现在，我们已经介绍了筛选数据的示例，接下来，我们要学习如何使用 OData 筛选。 在查询中使用 OData 筛选时，筛选器查询字段中的模式基于列中的数据类型。 我们从按列筛选开始。 如果列值等于字符串，我们可以使用如下所示的筛选器：

StringColumn eq 'text'

查看 OData 语句使用的是“equals”的缩写 eq？ 这是 equals 运算符的 OData 代码。 另外，请注意我们的字符串值外面添加了单引号。

我们可以对包含数值的列使用相同的 OData 运算符，例如：

NumericColumn eq 3

请注意，比较数值时，不需要使用单引号。

由于授权限制，SharePoint 不会执行 Power Automate 要求的所有操作，也就是说，SharePoint 仅执行某些类型的查询筛选器。 您可以使用以下 OData 运算符提示 SharePoint 筛选：

Operator 缩写 语法
Equals eq StringValueColumn eq 'text'（或 NumericColumn eq number）
Not equals ne StringValueColumn ne 'text'（或 NumericColumn ne number）
Less than lt NumericColumn lt number（或 DateValueColumn lt date）
Greater than gt NumericColumn gt number（或 DateValueColumn gt date）
Less than or equal to le NumericColumn le number（或 DateValueColumn le date）
Greater than or equal to ge NumericColumn le number（或 DateValueColumn le date）
Starts with startswith startswith(StringValueColumn, 'text')
Substring of substringof substringof('text', StringValueColumn)
And and FilterFormula and FilterFormula
Or or FilterFormula or FilterFormula

浏览文本等于筛选器

一起看个示例。 找到一个 SharePoint 列表，其中包含可以使用的多个项目，然后打开 Power Automate Maker Portal 的一个独立浏览器实例。

  1. 从 Power Automate Maker Portal 的主页屏幕中，选择左侧导航菜单中的创建选项卡。

  2. 从顶部的选项选择即时云端流。

  3. 选择手动触发流>创建。

  4. 在触发器下添加一个步骤并搜索 SharePoint。

  5. 查找并选择 SharePoint 获取项目操作。

  6. 添加 SharePoint 站点地址。 就是 SharePoint 列表所在站点的主页 URL。 如果没有在站点地址下拉列表中看到您的 SharePoint 列表名称，则可以从左侧导航栏选择主页，获取 SharePoint 站点的主页，然后从浏览器复制 URL。 返回到 Power Automate，选择输入自定义值下拉选项，然后粘贴 SharePoint 主页 URL。

  7. 在列表名称下，从下拉列表中找到并选择 SharePoint 列表名称。

  8. 展开显示高级选项并找到筛选器查询字段。 请注意，提示文本（您可以通过将鼠标悬停在字段上来查看整个提示）会告知您，它需要 ODATA 筛选器语句，甚至还会提供语法示例。

  9. 首先，我们使用 equals (eq) 函数筛选 SharePoint 文本值列。 选择一个包含文本值的列。 对于公式，请在列名称中输入 eq，然后输入该列下的一个值，在职周围加上单引号。 输入列数据中存在的准确值，并加上引号。

    如果列名称/值不完全匹配，则筛选器无效。 要查看列名称的值，您可以选择设置图标导航到 SharePoint 列表的列表设置，然后将鼠标悬停在列名称上方，并在屏幕底部查找该列的名称。 将鼠标悬停在名称上时，您会看到一个包含等号的 URL，后面是列名称。

    请参阅以下示例。 SharePoint 列名为产品描述，但数据中的实际名称是 field_1，这就是我们需要输入的列名称。

    “列”的屏幕截图，其中突出显示“产品描述”。

  10. 为了解筛选器返回的项目数量，我们要在获取项目操作下再添加一个操作。 添加撰写操作。 选择输入字段并切换到表达式选项卡。在表达式输入字段中添加以下公式：

    length(outputs('Get_items')?['body/value'])

    此操作会计算获取项目操作返回的行数。

  11. 选择更新以保存此值。

  12. 现在，我们来测试流。 选择保存>测试>手动>测试，然后验证连接，选择运行流。

  13. 运行流后，展开流结果中的撰写操作并查看返回的项目数量。 是否正常？ 如果使用大量项目进行测试，且其中包含多个符合条件的项目，则可能只返回 100 个项目。

如果筛选器不太有效，请检查并确保单引号内的列名称是否准确无误，匹配的数据是否准确无误。

使用靠前计数

使用相同的流，我们来看使用“靠前计数”能为我们带来什么。 “靠前计数”可以有效测试列表是否能够正确筛选，因为您可以将返回的数据限制为部分项目，并在流运行后快速查看这些数据。

  1. 将流恢复到编辑模式。

  2. 展开获取项目操作并选择显示高级选项。

  3. 在靠前计数右侧的字段中，输入 1。

  4. 再次测试流。

    提示

    测试流时，您可以在之前的运行中使用自动选项，通过更少按钮单击次数快速重新运行流。

  5. 在运行结果屏幕中，如果展开撰写操作，它应该在输入/输出中反映值 1。

  6. 如果展开“获取项目”操作，则可以选择单击下载，描述返回项目的 JSON 代码。

  7. 再次将流恢复到编辑模式。

  8. 输入您希望在查询中看到的“靠前计数”值（最多 5000），但不能大于列表中的项目数量。

  9. 再次保存并测试流。 结果是否符合预期？ 如果不符合，请返回并检查值，然后重试。

使用分页

要测试分页，您需要拥有一个包含 100 多个项目的列表，因为 Get Items 函数一次获取 100 个项目。 包含 101-200 个项目的列表将调用两次获取。 请记住，如果希望返回 5000 个项目或更少，则不需要使用分页，“靠前计数”的性能比它好得多。 不过，还是要为您解释它的工作原理。

  1. 再次将流恢复到编辑模式。

  2. 擦除靠前计数的任何值，将“靠前计数”留空。 实际操作中，您要始终使用“靠前计数”作为筛选器，因为它可以快速调用前 5000 个值。 但是，在本例中，我们想要演示分页的工作原理以及它能慢到什么程度。

  3. 转到获取项目操作的设置。

  4. 将分页切换为开启，然后在阈值输入字段中输入希望检索的项目数量。

  5. 选择完成。

  6. 保存并测试流。 请注意，如果列表很长，流程的运行时间会非常久。 想象一下，一次滚动 100 项，要浏览整个 SharePoint 列表需要多久！

总结

希望您已对以下内容有了基本了解：

  • 使用 OData 筛选功能筛选 SharePoint 列表；

  • 为什么想要筛选 SharePoint；

  • 以及如何修改 SharePoint 操作，返回您想要的数据。