OData を使用した SharePoint でのフィルター処理

  • 14 分

このユニットでは、SharePoint リストおよびドキュメント ライブラリのクエリを実行するとき OData (Open Data Protocol) フィルターを使用する方法について説明します。

OData フィルターを使用する理由

SharePoint の OData フィルターを使用するのはなぜでしょうか。 既定では、リストの項目の取得アクションまたはライブラリのファイルの取得アクションは、上位カウント値またはしきい値を指定しない場合は、最初の 100 件の項目またはファイルのみ SharePoint から取得します。 上位アカウントには既定のしきい値スロットル制限である項目 5,000 件までの数を指定できますが、リストまたはライブラリの項目またはファイルの数が 5,000 件を超える場合、上位カウントの下にあるエントリを使用してすべてのデータが返されるわけではありません。 したがって、クエリをフィルター処理すると、しきい値制限を超える結果を作成できます。

5,000 を超える数値を入力しようとすると、実行しようとしたときにフローがエラーになります。

大きいリストまたはライブラリのアクション設定について

リストまたはライブラリの項目またはファイル数が 100 ～ 5,000 件の場合、上位カウントのみ調整する必要があります。 [上位カウント] では、既定のしきい値制限である 5,000 までの値を入力できます。 しきい値制限は、このステップで 5,000 件を超える項目が返されないことを目的としています。 上位カウントは、データから最大 5000 件の項目を取得する効率的な方法です。

リストまたはライブラリに 5,000 件を超える項目がある場合や、クエリにより 5,000 件を超える項目が返される場合、ステップのページネーションを有効にする必要があります。 ページネーションとは 項目の取得アクションにより値がフェッチされるたびに、一度に 100 件の項目が取得されます。 SharePoint リストまたはライブラリ内をスクロールする場合と同様、表示可能な項目の一番下に移動すると、SharePoint によりさらに 100 件の項目がフェッチされます。 したがって、ページネーションを使用すると、それを超えてフェッチ プロセス (100 件の項目のバッチ内) を続行可能になります。 ただし、ページネーションには時間がかかるため、フローの速度は低下する点に注意してください。 ページネーションを有効にすると、アクションはこのプロセスを繰り返し、手動で入力されたしきい値合計 (後ほど説明する別のエントリ) を返します。

ページネーションを見つけるには、項目の取得アクションまたはファイルの取得アクションの右上隅にある省略記号を選択し、設定を表示します。

設定オプションを表示するために選択された省略記号ボタンを含む項目の取得のスクリーンショット。

アクション設定パネルで、ページネーション オプションをオンに切り替えた後、しきい値の値を入力します。 ページネーションは、データ ソースから 1 ～ 100,000 件の項目を返すことができますが、返されることを期待している項目の数に設定するだけでかまいません。 最後に、完了を選択して通常の設定に戻ります。

設定パネルのしきい値設定は少しわかりにくくなっていますが、次のようになっています。 クエリから受け取ることを期待している項目の数と一致している必要がありますが、100,000 件を超える項目を返すことはできません。 たとえば、しきい値を 500 に設定したが、クエリに一致する項目が 2,000 件である場合、受け取る項目は 500 件のみになります。 同様に、しきい値を 2,000 に設定した場合、期待している 2,000 件の項目すべてが取得されます。

この機能が重要なのはなぜでしょうか。 上位カウント (5,000) としきい値 (100,000) の値を上限に設定しないのはなぜでしょうか。 Power Automate にページネーションを求めると時間がかかり、フローの速度が低下するからです。 上位カウントの値を 2,500 (例) にすれば、期待しているデータすべてを取得できる場合、ページネーションを切り替え、しきい値に最大値を適用してすべてのデータでページネーションを行う必要はありません。

次に進む前に考慮すべき点がもう 1 つがあります。5,000 を超える項目が返されることを期待している場合、必ず上位カウントを 5,000 に設定してください。 上位カウントを使用すると最初の 5,000 件の項目を簡単に返すことができ、ページネーションは最初の 5,000 件の項目の最後で行われます。 これらは協調して機能します。 ページネーション自体は確かに動作しますが、同じ動作が実行されるには、一度に 100 件の項目のフェッチを続行する必要があります。

フィルター クエリで OData を使用する方法

データのフィルター処理を行うケースを作成しました。次に、OData フィルター処理の使用方法について説明します。 クエリで OData フィルター処理を使用している場合、フィルター クエリ フィールド内のパターンは列のデータの種類に基づいて決まります。 列によるフィルターを使用してみましょう。 列の値が文字列である場合、次のようなフィルターを使用できます。

StringColumn eq 'text'

OData ステートメントでは、"次の値と等しい" を表す略語 eq がどのように使用されるのでしょうか。 これは "次の値と等しい" 演算子の OData コードです。 さらに、文字列値が一重引用符でどのように囲まれているかにも注目してください。

次に示す数値を含む列に対して、同じ OData 演算子を使用できます。

NumericColumn eq 3

数値を比較するときは、単一引用符を使用する必要はない点に注目してください。

SharePoint は、委任制約のため、Power Automate が求めるすべての操作を実行するわけではありません。つまり、SharePoint は、特定の種類のクエリ フィルターのみを単独で実行します。 SharePoint のフィルター処理を求める場合に使用できる OData 演算子を以下に示します。

演算子 省略形 構文
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

テキストの Equals フィルターの使用例

使用例を一緒に見てみましょう。 使用できる複数の項目を含む SharePoint リストを見つけ、別個のブラウザー インスタンスで Power Automate Maker Portal を開きます。

  1. Power Automate Maker Portal のホーム画面で、左側のナビゲーション メニューから作成タブを選択します。

  2. 上部のオプションからインスタント クラウド フローを選択します。

  3. 手動でフローを起動する>作成を選択します。

  4. トリガーの下にステップを追加し、sharepoint を検索します。

  5. SharePoint 項目の取得アクションを見つけて選択します。

  6. SharePoint サイト アドレスを追加します。 これは、SharePoint リストが存在するサイトのホーム ページ URL です。 サイト アドレスのドロップダウンに SharePoint リストが表示されない場合、左側のナビゲーション レールでホームを選択し、ブラウザーから URL をコピーすることで SharePoint サイトのホーム ページを表示できます。 Power Automate に戻り、ドロップダウン オプションを選択してカスタム値を入力し、SharePoint ホーム ページの URLを貼り付けます。

  7. リスト名の下で、ドロップダウンから SharePoint リスト名を選択します。

  8. 詳細オプションを表示するを展開し、フィルター クエリ フィールドを見つけます。 ヒント テキスト (フィールドをポイントするとヒント全体を表示できます) に、ODATA フィルター ステートメントが必要であることが示され、構文の例も表示される点に注目してください。

  9. まず、Equals (eq) 関数を使用して SharePoint テキスト値の列をフィルター処理してみましょう。 下にテキスト値が表示されている列のいずれかを選択します。 式に列名 eq を入力した後、その下に値を一重引用符で囲んで入力します。 列データにある引用符内に正確な値を入力します。

    列の名前/値が完全には一致しない場合、フィルターは機能しません。 列名の値を表示するには、設定アイコンを選択して SharePoint リストのリスト設定に移動し、列名をポイントして、画面の下部にある列の名前を探します。 名前をポイントすると、URL が表示され、等号、列名の順に表示されます。

    以下の例を参照してください。 SharePoint 列の名前は製品の説明になっていますが、データにおける実際の名前は field_1 であるため、列名としてその名前を入力する必要があります。

    製品の説明が強調表示された列のスクリーンショット。

  10. フィルターを使用して返される項目の数を確認するため、項目の取得アクションの下にアクションをもう 1 つ追加してみましょう。 作成アクションを追加します。 入力フィールドを選択し、式タブに切り替 えます。式入力フィールドに次の式を追加します。

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

    このアクションは、項目の取得アクションによって返される行の数をカウントします。

  11. 更新を選択して、この値を保存します。

  12. 次に、フローをテストしてみましょう。 保存>テスト>手動>テストの順に選択し、接続が検証されたら、フローの実行を選択します。

  13. フローが実行されたら、フロー結果の作成アクションを展開し、返された項目数を表示します。 期待していた数でしょうか。 条件に一致する項目を複数含む大きい項目リストでテストした場合、返される項目数は 100 のみの可能性があります。

フィルターがうまく機能しない場合、列名が正確であり、一致するデータが一重引用符で正しく囲まれていることを確認してください。

上位カウントの使用

同じフローを使用して、上位カウントの使い方を見てみましょう。 上位カウントは、リストが正しくフィルター処理されているかどうかをテストする優れた方法です。返されるデータを数項目に制限し、フローの実行後にこのデータをすばやく確認できるからです。

  1. フローを編集モードに戻します。

  2. 項目の取得アクションを展開し、詳細オプションを表示するを選択します。

  3. 上位カウントの右側にあるフィールドに、「1」と入力します。

  4. フローの実行をもう一度テストします。

    ヒント

    フローをテストするとき、前回の実行で自動オプションを使用すると、数回クリックするだけでフローをすぐに再実行できます。

  5. 実行結果画面で、作成アクションを展開すると、入力/出力に値 1 が反映されています。

  6. 項目の取得アクションを展開した場合、クリックしてダウンロードを選択して、返された項目の JSON コードを表示できます。

  7. フローをもう一度編集モードに戻します。

  8. クエリに表示されることを期待している上位カウント値を入力してください (最大 5,000)。ただし、リスト内の項目数よりは大きくしないでください。

  9. フローを保存してもう一度テストします。 期待していた結果が得られたでしょうか。 得られない場合は、戻って値を確認し、もう一度やり直してください。

ページネーションの使用

ページネーションをテストするには、項目の取得機能では一度に 100 件の項目がフェッチされるため、100 件を超える項目を含むリストが必要です。 101 ～ 200 件の項目を含むリストでは、フェッチが 2 回呼び出されます。 返されることを期待している項目の数が 5,000 件以下の場合、必ずしもページネーションは必要ない点に留意してください。上位カウントの方がかなり効率的です。 しかし、ここではその機能を経験することができます。

  1. フローをもう一度編集モードにします。

  2. 上位カウントの値が何であれ消去し、上位カウントを空にします。 現実としては、フィルターには必ず上位カウントを使用してください。最初の 5,000 件の値をすぐに呼び出すことができるからです。 ただし、この場合は、ページネーションのしくみと、それ自体の遅さを示すことを目的としています。

  3. 項目の取得アクションの設定に移動します。

  4. ページネーションをオンに切り替え、取得されることを期待している項目の数をしきい値入力フィールドに入力します。

  5. 完了を選択します。

  6. フローを保存してテストします。 リストが大きい場合、フローの実行に長い時間がかかる点に注目してください。 SharePoint リスト全体にある 100 件の項目を一度にスクロールするようなものです。

概要

次の点に関する基本的な理解が得られたら幸いです。

  • OData フィルター処理を使用した SharePoint リストのフィルター処理

  • SharePoint をフィルター処理する理由

  • 目的のデータを返す SharePoint アクションを変更する方法