Фильтрация по дате в CAML запросах SharePoint

SharePoint — это мощная платформа для совместной работы‚ и одной из её ключевых возможностей является работа со списками и библиотеками документов․ Когда вам нужно программно извлечь данные из списка‚ отфильтровав их по дате создания‚ изменения или по любому другому полю типа «Дата и время»‚ на помощь приходит CAML (Collaborative Application Markup Language)․

В этой статье мы подробно разберем‚ как правильно конструировать CAML-запросы для фильтрации записей по датам‚ рассмотрим частые подводные камни и приведем практические примеры․

Что такое CAML?

CAML — это XML-язык разметки‚ используемый в SharePoint для определения запросов (Querying) и представления данных (View definitions)․ С его помощью вы можете указать платформе‚ какие именно элементы списка вам нужно вернуть‚ отсортировать их или сгруппировать․

Базовая структура CAML-запроса

Любой запрос в SharePoint обычно оборачивается в тег <Query>․ Внутри него находится секция <Where>‚ которая определяет условия фильтрации․ Условия строятся с помощью операторов сравнения‚ таких как <Eq> (равно)‚ <Gt> (больше)‚ <Lt> (меньше)‚ <Geq> (больше или равно) и <Leq> (меньше или равно)․

Базовый шаблон выглядит так:

<Query>
<Where>
  <Оператор>
    <FieldRef Name=»ИмяПоля» />
    <Value Type=»DateTime»>Значение даты</Value>
  </Оператор>
</Where>
</Query>

Формат даты в CAML

Это самое главное‚ что нужно помнить при работе с датами в CAML․ SharePoint ожидает дату в строго определенном формате: ISO 8601․ Формат выглядит следующим образом: YYYY-MM-DDTHH:MM:SSZ․

• YYYY — год (например‚ 2023)
• MM — месяц (например‚ 05)
• DD — день (например‚ 15)
• T — разделитель‚ обозначающий начало времени
• HH:MM:SS, часы‚ минуты‚ секунды
• Z — указывает на время в формате UTC (по Гринвичу)

Пример корректной даты: 2023-10-25T00:00:00Z

Практические примеры фильтрации

Фильтрация по точной дате (без учета времени)

Если вам нужно найти элементы‚ созданные 25 октября 2023 года‚ запрос будет выглядеть так:

<Where>
  <Eq>
    <FieldRef Name=»Created» />
    <Value Type=»DateTime»>2023-10-25T00:00:00Z</Value>
  </Eq>
</Where>

Записи после определенной даты

Чтобы получить все записи‚ созданные после 1 января 2023 года‚ используем оператор <Gt>:

<Where>
  <Gt>
    <FieldRef Name=»Created» />
    <Value Type=»DateTime»>2023-01-01T00:00:00Z</Value>
  </Gt>
</Where>

Диапазон дат (Between)

Для выборки данных между двумя датами (например‚ за определенный месяц) необходимо использовать вложенные операторы <And>:

<Where>
  <And>
    <Geq>
      <FieldRef Name=»Created» />
      <Value Type=»DateTime»>2023-10-01T00:00:00Z</Value>
    </Geq>
    <Leq>
      <FieldRef Name=»Created» />
      <Value Type=»DateTime»>2023-10-31T23:59:59Z</Value>
    </Leq>
  </And>

</Where>

Важные атрибуты: IncludeTimeValue

По умолчанию SharePoint сравнивает не только дату‚ но и время․ Если вы хотите‚ чтобы сравнение происходило только по дате‚ игнорируя время‚ добавьте атрибут IncludeTimeValue=»FALSE» в тег <Value>․

Пример:

<Where>
  <Eq>
    <FieldRef Name=»Created» />
    <Value Type=»DateTime» IncludeTimeValue=»FALSE»>2023-10-25T00:00:00Z</Value>
  </Eq>
</Where>

В этом случае записи‚ созданные в 10:00 и в 18:00 25 октября‚ будут считаться равными указанной дате․

Работа с сегодняшним днем (Today)

Часто возникает задача отфильтровать записи‚ созданные сегодня‚ или за последние 7 дней․ В SharePoint есть специальный тег <Today />‚ который подставляет текущую дату․

Пример: Записи за сегодня

<Where>
  <Eq>
    <FieldRef Name=»Created» />
    <Value Type=»DateTime»>
      <Today />
    </Value>
  </Eq>
</Where>

Пример: Записи за последние 7 дней

Тег <Today /> принимает атрибут OffsetDays‚ который позволяет сдвигать дату назад или вперед․

<Where>
  <Geq>
    <FieldRef Name=»Created» />
    <Value Type=»DateTime»>
      <Today OffsetDays=»-7″ />
    </Value>
  </Geq>
</Where>

Частые ошибки и советы

1. Проблемы с часовыми поясами: SharePoint хранит даты в формате UTC․ Если вы передаете локальное время без конвертации‚ результаты могут отличаться на один день․ Всегда конвертируйте локальное время в UTC перед вставкой в CAML-запрос․
2. Регистр тегов: CAML чувствителен к регистру․ Теги <Where>‚ <Eq>‚ <FieldRef> должны начинаться с заглавной буквы‚ а атрибуты (например‚ Name‚ Type) — со строчной‚ как показано в примерах․
3. Системные поля: Вы можете фильтровать не только по пользовательским полям‚ но и по системным‚ таким как Created (дата создания) и Modified (дата изменения)․

Фильтрация по дате с помощью CAML в SharePoint — это базовый‚ но очень важный навык для разработчиков и администраторов․ Главное правило — всегда использовать формат ISO 8601 (UTC) и не забывать про атрибут IncludeTimeValue‚ если время для вас не критично․ Используя операторы сравнения и тег <Today />‚ вы можете создавать гибкие и быстрые запросы для извлечения нужных данных из списков SharePoint․