はじめに
SharePoint REST APIエンドポイントにクエリ文字列を付与して、返却されるデータをフィルターすることがままあります。
フィルター式には様々な演算子がサポートされており、今回は 「日付と時刻」列に対して演算子を用いてフィルターする ときに知っておくと良さそうなことのメモです。
参考
早速フィルターをかけてみる
使用するリストは以下です。
「日付と時刻」で作成した公開日（内部名：StartDate）列に対して、いろいろなフィルターをかけてみます。
1. 等しい (eq)
クエリ
$filter=StartDate eq 'UTC日付文字列'
日付文字列をシングルクォーテーション（' '）で囲うのを忘れないように！
また、クエリにはUTC形式（日本時間 - 9時間）の文字列を付与しています。
JST形式でも可能そうなのですが、十分に調査できていないので、ここではUTC形式にしています。
クエリの意味
「公開日が 2023年1月11日 のアイテムに絞り込みたい！」
結果
レスポンスデータをコンソールに出してみます。
※アイテムの「開始日」という表記になっていますが、ミスです・・。正しくは「公開日」となります！
公開日が 2023年1月11日 のアイテムが1件のみ取得できている。
2. 以下 / 以前 (le)
クエリ
$filter=StartDate le 'UTC日付文字列'
クエリの意味
「公開日が 2023年1月11日 以前（2023年1月11日を含む）のアイテムに絞り込みたい！」
結果
公開日が 2023年1月11日 以前のアイテムが3件取得できている。
3. ～未満 / ～より古い (lt)
クエリ
$filter=StartDate lt 'UTC日付文字列'
クエリの意味
「公開日が 2023年1月11日 より古い（2023年1月11日を含まない）アイテムに絞り込みたい！」
結果
公開日が 2023年1月11日 より古い2件が取得できている。
4. 以上 / 以降 (ge)
クエリ
$filter=StartDate ge 'UTC日付文字列'
クエリの意味
「公開日が 2023年1月11日 以降（2023年1月11日を含む）のアイテムに絞り込みたい！」
結果
公開日が 2023年1月11日 以降の3件が取得できている。
5. ～より大きい / ～より新しい (gt)
クエリ
$filter=StartDate gt 'UTC日付文字列'
クエリの意味
「公開日が 2023年1月11日 より新しい（2023年1月11日を含まない）アイテムに絞り込みたい！」
結果
公開日が 2023年1月11日 より新しい2件が取得できている。
そのほかにも・・・
AND条件を使って複数の条件を設定することもできます。
さきほどのリストに終了日列（内部名: EndDate）を追加する。
クエリ
$filter=StartDate le 'UTC日付文字列' and EndDate ge 'UTC日付文字列'
クエリの意味
※ 今日が、2023年1月12日という前提で。
「公開日が今日より前の日付で、終了日は今日より後の日付のアイテムに絞り込みたい！」
結果
5件のアイテムの内、
公開日が2023年1月12日以前であり、終了日が2023年1月12日以降で設定された、
テスト2とテスト3のアイテムが取得できています。
このようなフィルターをかけることで、有効期限内のアイテムだけ取得する！なんてこともできそうです。
おわりに
やや煩雑な説明になってしまった気がするのですが、、、演算子を用いた日付データの比較は、混乱してしまうことが多いので、これを機に良い復習ができました。
フィルタークエリを使って、取得するアイテムを制御できるのは便利ですね！
ほかにも様々な演算子やクエリオプションが存在するので色々と試してみたいです。