Uso di filtri OData con SharePoint
Questa unità illustra come usare i filtri OData (Open Data Protocol) durante l'esecuzione di query sugli elenchi e sulle raccolte documenti di SharePoint.
Perché usare un filtro OData?
Perché è opportuno usare i filtri OData per SharePoint? Per impostazione predefinita, l'azione Ottieni elementi per gli elenchi o l'azione Ottieni file per le raccolte consente di recuperare solo i primi 100 elementi o file da SharePoint se non si specifica un valore Numero massimo o Soglia. Sebbene sia possibile specificare un Numero massimo entro il limite di soglia predefinito di 5.000 elementi, se l'elenco o la raccolta contiene più di 5.000 elementi o file, la query non restituirà tutti i dati inserendo un valore in Numero massimo. L'uso di filtri nella query consente di creare risultati inferiori ai limiti di soglia.
Se si tenta di immettere un numero superiore ai 5.000 risultati, si verifica un errore di flusso al momento dell'esecuzione.
Impostazioni delle azioni per elenchi o raccolte di grandi dimensioni
Se l'elenco o la raccolta contiene tra i 100 e i 5.000 elementi o file, è necessario regolare il Numero massimo. In Numero massimo è possibile immettere un valore entro il limite di soglia predefinito di 5.000. Il limite di soglia ha lo scopo di impedire che questo passaggio restituisca più di 5.000 elementi. Numero massimo offre un modo efficace per recuperare fino a 5.000 elementi dai dati.
Se l'elenco o la raccolta contiene più di 5.000 elementi, o se la query restituisce più di 5.000 risultati, è necessario abilitare la Paginazione del passaggio. Cos'è la paginazione? Ogni volta che l'azione Ottieni elementi recupera dei valori, recupera 100 elementi alla volta. Come se si scorresse l'elenco o la raccolta di SharePoint, quando si raggiunte la fine degli elementi visualizzabili SharePoint recupera altri 100 elementi. La paginazione consente al processo di recupero (in batch di 100 elementi) di continuare molto oltre tale limite. Tuttavia, tenere presente che la paginazione richiede tempo e rallenta il flusso. Con Paginazione abilitata, l'azione ripete questo processo per restituire il valore immesso manualmente del totale Soglia (un'altra voce necessaria che illustreremo tra poco).
Per trovare l'impostazione Paginazione, selezionare i puntini di sospensione nell'angolo destro dell'azione Ottieni elementi o Ottieni file per visualizzare Impostazioni.
Nel pannello delle impostazioni dell'azione impostare l'opzione Paginazione su Attivata, quindi inserire un valore di Soglia. Paginazione può restituire da 1 a 100.000 elementi dall'origine dati, ma è necessario impostarla solo per il numero di elementi che si prevede verranno restituiti. Infine, selezionare Fatto per tornare alle impostazioni normali.
L'impostazione Soglia nel pannello delle impostazioni è un po' difficile da comprendere, ma considerare quanto segue. Dovrebbe corrispondere al numero di elementi che si prevede di ricevere dalla query ma non può restituire più di 100.000 elementi. Ad esempio, se si imposta la Soglia a 500 e 2.000 elementi corrispondono alla query, si riceveranno solo 500 elementi. Nello stesso caso se si imposta la Soglia a 2.000, si otterranno tutti e 2.000 gli elementi previsti.
Perché è importante? Perché non è sufficiente impostare i valori massimi di Numero massimo (5.000) e di Soglia (100.000)? Poiché richiedere a Power Automate di eseguire la paginazione richiede tempo e rallenta il flusso. Se è possibile ottenere tutti i dati previsti con un valore Numero massimo di 2.500 (ad esempio), non è necessario attivare Paginazione e applicare il valore massimo alla soglia per continuare a eseguire la paginazione di tutti i dati.
Un altro aspetto da considerare prima di procedere: impostare sempre il Numero massimo a 5.000 se si prevede che la query restituirà più di 5.000 elementi. Numero massimo offre un modo rapido per restituire i primi 5.000 elementi e la paginazione riprenderà alla fine dei primi 5.000 elementi. Funzionano congiuntamente. La paginazione da sola funziona, ma deve continuare a recuperare 100 elementi alla volta per eseguire la stessa operazione.
Come usare OData nella query di filtro
Dopo aver illustrato perché è utile filtrare i dati, esaminiamo come usare i filtri OData. Quando si usano i filtri OData nelle query, il criterio per il campo Query filtro si basa sul tipo di dati della colonna. Iniziamo con un filtro per colonna. Se il valore della colonna è uguale a una stringa, è possibile usare un filtro simile al seguente:
StringColumn eq 'text'
Si può notare che l'istruzione OData usa l'abbreviazione eq per l'operatore equals. Questo il codice OData per l'operatore equals. Notare inoltre che il valore della stringa è racchiuso tra virgolette singole.
Si potrebbe usare lo stesso operatore OData per una colonna con valori numerici quale:
NumericColumn eq 3
Notare che quando si confrontano valori numerici, non è necessario usare le virgolette singole.
SharePoint non esegue tutte le operazioni che Power Automate richiede a causa dei vincoli di delega, vale a dire che SharePoint esegue autonomamente solo determinati tipi di filtri di query. Di seguito sono riportati gli operatori OData che è possibile usare per richiedere a SharePoint di applicare i filtri:
| Operatore | Abbreviazione | Sintassi |
|---|---|---|
| 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 |
Analisi del filtro equals per valori di testo
Esaminiamo un esempio. Trovare un elenco SharePoint con più elementi che si possa usare e aprire Power Automate Maker Portal in un'istanza del browser separata.
Nella schermata Home di Power Automate Maker Portal selezionare la scheda Crea dal menu di spostamento a sinistra.
Selezionare Flusso cloud istantaneo dalle opzioni in alto.
Selezionare Attiva un flusso manualmente>Crea.
Aggiungere un passaggio sotto il trigger e cercare sharepoint.
Trovare e selezionare l'azione Ottieni elementi di SharePoint.
Aggiungere il proprio Indirizzo del sito di SharePoint. Questo è l'URL della home page del sito in cui risiede l'elenco di SharePoint. Se non si vede il nome dell'elenco di SharePoint nell'elenco a discesa Indirizzo del sito, è possibile ottenere la home page del sito di SharePoint selezionando Home nella barra di spostamento a sinistra e copiare l'URL dal browser. Tornare a Power Automate, selezionare l'opzione a discesa Immettere un valore personalizzato e incollare l'URL della home page di SharePoint.
In Nome elenco trovare e selezionare il nome dell'elenco di SharePoint dall'elenco a discesa.
Espandere Mostra opzioni avanzate e trovare il campo Query filtro. Notare che il suggerimento (è possibile visualizzare l'intero suggerimento posizionando il puntatore del mouse sul campo) indica che prevede un'istruzione di filtro ODATA e fornisce esempi di sintassi.
Filtriamo innanzitutto una colonna di valori di testo di SharePoint usando la funzione equals (eq). Scegliere una colonna che contenga valori di testo. Per la formula, immettere il nome della colonna, eq e un valore contenuto in tale colonna tra virgolette singole. Immettere tra virgolette un valore esatto presente nei dati della colonna.
Se il nome della colonna o il valore non corrispondono esattamente, il filtro non funziona. Per visualizzare i valori dei nomi delle colonne, è possibile andare alle Impostazioni elenco dell'elenco di SharePoint selezionando l'icona delle impostazioni, posizionare il puntatore del mouse sul nome della colonna e verificare il nome della colonna nella parte inferiore dello schermo. Quando si posiziona il puntatore del mouse sul nome, compare un URL con un segno di uguale seguito dal nome della colonna.
Vedere l'esempio di seguito. La colonna in SharePoint è denominata Descrizione prodotto ma il nome effettivo nei dati è field_1 e questo è il nome della colonna che si deve immettere.
Per poter vedere quanti elementi vengono restituiti con il filtro, aggiungiamo un'altra azione sotto l'azione Ottieni elementi. Aggiungere un'azione Componi. Selezionare il campo Input e passare alla scheda Espressione. Aggiungere la formula seguente nel campo di immissione Espressione:
length(outputs('Get_items')?['body/value'])Questa azione conteggia il numero di righe restituite dall'azione Ottieni elementi.
Selezionare Aggiorna per salvare questo valore.
Ora testiamo il flusso. Selezionare Salva>Test>Manualmente>Test quindi, dopo che la connessione viene verificata, selezionare Esegui flusso.
Dopo l'esecuzione del flusso, espandere l'azione Componi nei risultati del flusso e visualizzare il numero di elementi restituiti. Corrisponde al numero previsto? Se si è eseguito il test con un elenco esteso di elementi in cui più elementi corrispondono ai criteri, potrebbero venire restituiti solo 100 elementi.
Se il filtro non ha funzionato, assicurarsi di aver inserito il nome della colonna esatto e i dati corrispondenti esatti tra virgolette singole.
Uso di Numero massimo
Con lo stesso flusso, vediamo cosa possiamo ottenere usando Numero massimo. Numero massimo è un ottimo modo per verificare se l'elenco viene filtrato correttamente, poiché consente di limitare i dati restituiti a pochi elementi e di visualizzare rapidamente questi dati una volta eseguito il flusso.
Riportare il flusso in modalità Modifica.
Espandere l'azione Ottieni elementi e selezionare Mostra opzioni avanzate.
Nel campo a destra di Numero massimo immettere 1.
Provare a eseguire di nuovo il flusso.
Suggerimento
Quando si testa il flusso, è possibile usare l'opzione Automaticamente con un'esecuzione precedente per ripetere rapidamente l'esecuzione del flusso in pochi clic.
Se si espande l'azione Componi nella schermata dei risultati dell'esecuzione, dovrebbe riflettere il valore di 1 input/output.
Se si espande l'azione Ottieni elementi, è possibile selezionare Fare clic per scaricare per rappresentare il codice JSON dell'elemento restituito.
Riportare nuovamente il flusso in modalità Modifica.
Immettere un valore di Numero massimo pari al numero di risultati della query previsti (un massimo di 5.000), ma non superiore al numero di elementi presenti nell'elenco.
Selezionare Salva e Test per salvare e testare nuovamente il flusso. Si sono ottenuti i risultati previsti? In caso contrario, tornare indietro, controllare i valori e riprovare.
Uso della paginazione
Per testare la paginazione, è necessario un elenco che contenga più di 100 elementi, poiché la funzione Ottieni elementi recupera 100 elementi alla volta. Un elenco da 101 a 200 causerebbe due recuperi. Tenere presente che in realtà non sarebbe necessaria la paginazione se si prevede che venga restituito un massimo di 5.000 elementi, poiché Numero massimo offre prestazioni molto superiori. Tuttavia ciò consente di comprendere come funziona.
Riportare nuovamente il flusso in modalità Modifica.
Cancella qualsiasi valore inserito in Numero massimo in modo che sia vuoto. Realisticamente, si userebbe sempre Numero massimo per il filtro poiché può rapidamente richiamare i primi 5.000 valori. In questo caso, però, vogliamo illustrare il funzionamento della paginazione e quanto può essere lenta.
Andare alle impostazioni dell'azione Ottieni elementi.
Impostare Paginazione su Attivata e immettere il numero di elementi che si prevede di recuperare nel campo di input Soglia.
Selezionare Fatto.
Selezionare Salva e Test per salvare e testare il flusso. Se l'elenco è esteso, tenere presente che l'esecuzione richiederà molto tempo. Supporre di dover scorrere l'intero elenco di SharePoint a 100 elementi alla volta.
Riepilogo
Si è acquista una conoscenza di base su:
Come filtrare gli elenchi di SharePoint usando filtri OData
Perché è opportuno filtrare SharePoint
Come è possibile modificare le azioni di SharePoint affinché vengano restituiti i dati desiderati.