Usar los filtros OData con SharePoint
En esta unidad, aprenderemos a utilizar filtros OData (Open Data Protocol) al consultar listas y bibliotecas de documentos de SharePoint.
¿Por qué debemos utilizar un filtro OData?
¿Por qué es una buena idea utilizar filtros OData para SharePoint? De forma predeterminada, la acción Obtener elementos para listas o la acción Obtener archivos para bibliotecas solo recupera los primeros 100 elementos o archivos de SharePoint si no especifica un valor Recuento principal o Umbral. Aunque puede especificar un Recuento principal con un valor máximo igual a la limitación de umbral predeterminada de 5000 elementos, si la lista o biblioteca tiene más de 5000 elementos o archivos, no devuelve todos los datos utilizando una entrada en Recuento principal. Por lo tanto, filtrar su consulta le ayuda a crear resultados que están por debajo de los límites del umbral.
Si introduce un número mayor a 5000, habrá un error en el flujo al intentar ejecutarlo.
Configuración de acciones para listas o bibliotecas grandes
Si su lista o biblioteca tiene más de 100 elementos o archivos, y hasta 5000 elementos, lo que debe ajustar es el Recuento principal. En Recuento principal, puede introducir un valor máximo igual al límite predeterminado de umbral de 5000. El límite de umbral tiene el objetivo de evitar que este paso devuelva más de 5000 elementos. Recuento principal es una forma eficaz de recuperar hasta 5000 elementos de sus datos.
Si su lista o biblioteca tiene más de 5000 elementos, o si su consulta devuelve más de 5000 elementos, debe habilitar la Paginación del paso. ¿Qué es la paginación? Cada vez que la acción Obtener elementos consigue valores, obtiene 100 elementos. Como ocurre al navegar por una lista o biblioteca de SharePoint, llega al final de los elementos visibles y SharePoint busca otros 100 elementos. Por lo tanto, la paginación permite que el proceso de búsqueda (en lotes de 100 elementos) continúe tras este límite. Sin embargo, tenga en cuenta que la paginación lleva tiempo y ralentiza el flujo. Con la paginación habilitada, su acción repite este proceso para devolver el valor introducido manualmente del total de umbral (otra entrada necesaria de la que hablaremos brevemente).
Para encontrar la configuración de paginación, seleccione los puntos suspensivos en la esquina derecha de la acción Obtener elementos u Obtener archivos, a fin de ver la Configuración.
En el panel de configuración de acciones, cambie la opción Paginación a Activado; luego, introduzca un valor para Umbral. La paginación puede devolver desde 1 hasta 100 000 elementos de su origen de datos, pero solo necesita configurarla para el número de elementos que espera devolver. Por último, seleccione Listo para volver a la configuración normal.
La configuración de Umbral en el panel de configuración es un poco difícil de comprender, pero podemos planteárnoslo de la siguiente manera. Debería coincidir con el número de elementos que espera recibir de la consulta, pero no puede devolver más de 100 000 elementos. Por ejemplo, si el Umbral es 500 y tiene 2000 elementos que coinciden con la consulta, solo recibirá 500 elementos. En el mismo ejemplo, si establece el Umbral en 2000, obtendrá los 2000 elementos que espera.
¿Qué importancia tiene esto? ¿Por qué no nos limitamos a poner el valor máximo para Recuento principal (5000) y Umbral (100 000)? Porque pedirle a Power Automate que lleve a cabo la paginación conlleva tiempo y ralentiza el flujo. Si puede obtener todos los datos que espera con un valor de Recuento principal de 2500 (por ejemplo), no es necesario alternar "Paginación" y aplicar el valor máximo al umbral para seguir paginando todos los datos.
Otro factor que debemos tener en cuenta antes de seguir: ponga siempre el Recuento principal en 5000 si espera devolver más de 5000 elementos. Recuento principal es una forma rápida de devolver los primeros 5000 elementos, y la Paginación continúa al final de esos primeros 5000 elementos. Trabajan en conjunto. La paginación por sí sola funciona bien, pero tiene que ir obteniendo elementos en conjuntos de 100 para realizar el mismo trabajo.
Cómo utilizar OData en la consulta de filtro
Ahora que ya hemos visto la importancia del filtrado de datos, veamos cómo utilizar el filtrado OData. Al usar el filtrado OData en las consultas, el patrón en el campo Consulta de filtro se basa en el tipo de datos de la columna. Comencemos con un filtro por columna. Si el valor de la columna es igual a una cadena, podemos usar un filtro similar a este:
StringColumn eq 'text'
Como puede ver, la instrucción OData usa la abreviatura eq para "equals"; es el código OData para el operador "equals". Además, el valor de cadena tiene comillas simples alrededor.
Podríamos usar el mismo operador OData para una columna con valor numérico, como lo siguiente:
NumericColumn eq 3
Observe que, cuando comparamos valores numéricos, no necesitamos usar comillas simples.
SharePoint no realiza todas las operaciones que Power Automate le pide, debido a limitaciones de delegación, lo que significa que SharePoint solo realiza ciertos tipos de filtros de consulta de forma independiente. Estos son los operadores de OData que puede utilizar para pedir confirmación del filtrado de SharePoint:
| Operator | Abreviatura | Sintaxis |
|---|---|---|
| Equals | eq |
StringValueColumn eq 'text' (o NumericColumn eq number) |
| Not equals | ne |
StringValueColumn ne 'text' (o NumericColumn ne number) |
| Less than | lt |
NumericColumn lt number (o DateValueColumn lt date) |
| Greater than | gt |
NumericColumn gt number (o DateValueColumn gt date) |
| Less than or equal to | le |
NumericColumn le number (o DateValueColumn le date) |
| Greater than or equal to | ge |
NumericColumn le number (o 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 |
Recorrido por el texto del filtro "equals"
Veamos juntos un ejemplo. Busque una lista de SharePoint con varios elementos que pueda usar y abra una instancia de navegador independiente en Power Automate Maker Portal.
Desde la pantalla de inicio de Power Automate Maker Portal, seleccione la pestaña Crear en el menú de navegación del lado izquierdo.
Seleccione Flujo de nube instantánea desde las opciones de la parte superior.
Seleccione Desencadenar un flujo manualmente>Crear.
Agregue un paso debajo de su desencadenador y busque sharepoint.
Busque y seleccione la acción Obtener elementos de SharePoint.
Agregue su Dirección del sitio de SharePoint. Esta es la URL de la página principal del sitio donde reside la lista de SharePoint. Si no ve el nombre de la lista de SharePoint en el menú desplegable de Dirección del sitio, puede tomar la página principal del sitio de SharePoint seleccionando Inicio desde el raíl de navegación del lado izquierdo; luego, copie la URL desde su navegador. En Power Automate, seleccione la opción desplegable para Escribir un valor personalizado y pegue la URL de la página principal de SharePoint.
En Nombre de lista, busque y seleccione el nombre de lista de SharePoint en el menú desplegable.
Expanda Mostrar opciones avanzadas y busque el campo Consulta de filtro. Como puede ver, el texto de sugerencia (puede ver toda la sugerencia pasando el cursor sobre el campo) le indica que espera una instrucción de filtro ODATA, y hasta proporciona ejemplos de sintaxis.
Comencemos filtrando una columna de valor de texto SharePoint usando la función "equals" (eq). Elija una de las columnas que tenga valores de texto debajo. Para la fórmula, introduzca el nombre de columna eq y un valor de los que haya bajo esa columna, entre comillas simples. Introduzca un valor exacto (que esté en los datos de la columna) entre las comillas.
Si no empareja exactamente el nombre y el valor de la columna, el filtro no funcionará. Para ver los valores de los nombres de las columnas, vaya a la Configuración de lista de la lista de SharePoint seleccionando el icono de configuración y colocando el cursor sobre el nombre de la columna; busque el nombre de esa columna en la parte inferior de la pantalla. Al pasar el cursor sobre el nombre, aparecerá una URL con un signo igual y el nombre de la columna.
Vea el ejemplo a continuación. Nuestra columna de SharePoint se llama Descripción del producto, pero el nombre real en los datos es field_1, así que ese es el nombre que necesitaríamos introducir para el nombre de la columna.
Para que podamos ver cuántos elementos se devuelven con nuestro filtro, vamos a agregar una acción más bajo la acción Obtener elementos. Agregue una acción Redactar. Seleccione el campo Entradas y cambie a la pestaña Expresión. Agregue la siguiente fórmula en el campo de entrada "Expresión":
length(outputs('Get_items')?['body/value'])Esta acción cuenta el número de filas que devuelve la acción Obtener elementos.
Seleccione Actualizar para guardar este valor.
Probemos ahora nuestro flujo. Seleccione Guardar>Probar>Manualmente>Probar; cuando la conexión se haya verificado, seleccione Ejecutar flujo.
Cuando se haya ejecutado el flujo, expanda la acción Redactar en los resultados del flujo y vea cuántos elementos se han devuelto. ¿Era eso lo que cabía esperar? Si ha hecho la prueba con una lista grande de elementos y más de uno coincidía con los criterios, es posible que haya devuelto solo 100 elementos.
Si el filtro no ha funcionado del todo bien, compruebe que el nombre de la columna y los datos de combinación sean exactamente los adecuados y que estén entre comillas simples.
Uso de Recuento principal
Con el mismo flujo, vamos a ver de qué nos sirve utilizar Recuento principal. Recuento principal es una excelente manera de probar si su lista se está filtrando correctamente, ya que puede limitar los datos devueltos a unos pocos elementos y ver rápidamente estos datos una vez que se haya ejecutado el flujo.
Ponga el flujo de nuevo en modo Editar.
Expanda la acción Obtener elementos y seleccione Mostrar opciones avanzadas.
En el campo que encontrará a la derecha de Recuento principal, introduzca 1.
Pruebe de nuevo el funcionamiento del flujo.
Sugerencia
Al probar el flujo, puede usar la opción Automáticamente con una ejecución anterior, para volver a ejecutar rápidamente el flujo con menos clics.
En la pantalla de resultados de ejecución, si expande la acción "Redactar", debería verse el valor "1" en entradas/salidas.
Si expande la acción Obtener elementos, puede seleccionar Haga clic para descargar a fin de representar el código JSON del elemento devuelto.
Ponga el flujo de nuevo en modo Editar.
Introduzca un valor de recuento principal correspondiente a lo que espera ver en su consulta (hasta 5000), pero no superior a la cantidad de elementos en su lista.
Seleccione de nuevo Guardar y Probar para el flujo. ¿Ha obtenido los resultados que esperaba? Si no es así, vuelva hacia atrás, compruebe los valores e inténtelo de nuevo.
Uso de la paginación
Para probar la paginación, necesita tener una lista de más de 100 elementos, ya que la función Get Items obtiene 100 elementos cada vez. Una lista con entre 101 y 200 elementos, requeriría dos obtenciones. Recuerde que no necesita la paginación si espera devolver 5000 elementos o menos, ya que Recuento principal es mucho más eficaz. Sin embargo, esto le permite ver cómo funciona.
Ponga el flujo de nuevo en modo Editar.
Elimine cualquier valor que tenga para Recuento principal a fin de dejarlo en blanco. La realidad es que lo normal es usar siempre Recuento principal en el filtro, ya que puede llamar rápidamente a los primeros 5000 valores. En este caso, sin embargo, queremos mostrar cómo funciona la paginación y lo lenta que puede llegar a ser cuando funciona de forma independiente.
Vaya a la configuración de la acción Obtener elementos.
Cambie la Paginación a Activado e introduzca la cantidad de elementos que espera recuperar en el campo de entrada Umbral.
Seleccione Listo.
SeleccioneGuardar y Probar para el flujo. Como puede ver, si la lista es grande, tarda mucho tiempo en ejecutarse. Imagínese lo que supone desplazarse por toda la lista de SharePoint en pasos de 100 elementos.
En resumen
Esperamos que haya entendido los conceptos básicos de lo siguiente:
Filtrado de listas de SharePoint mediante el filtrado OData.
Por qué utilizar filtros SharePoint.
Cómo modificar las acciones de SharePoint para devolver los datos que desee.