Рекомендации по обнаружению файлов и определению изменений в масштабе

  • Статья

SharePoint и OneDrive хранят миллионы файлов. Очень важно использовать правильные шаблоны вызовов при попытке понять все файлы и изменения в масштабе. Исторически существует множество API для доступа к файлам на атомарном уровне. Многие из этих API не являются эффективными в больших масштабах, но хорошо работают при взаимодействии с одним пользователем. В этом руководстве рассказывается, как отслеживать клиента Office 365 или OneDrive, чтобы приложение интегрировалось с Office 365 с максимальной производительностью и эффективностью. Приложения, которые обычно имеют этот тип потребности, — это механизмы синхронизации, поставщики резервного копирования, индексаторы поиска, механизмы классификации и поставщики средств защиты от потери данных.

Получение нужных разрешений

Чтобы завоевать доверие пользователей, важно использовать правильный минимальный набор областей разрешений, необходимых для работы приложения. Большинство приложений сканирования хотят работать с разрешениями приложения. Это означает, что приложение работает независимо от какого-либо конкретного пользователя. Чтобы получить доступ к файлам, необходимо запросить область Files.Read.All или Files.ReadWrite.All. Для доступа к SharePoint, включая список всех коллекций сайтов, подходит Sites.Read.All или Sites.ReadWrite.All. Для правильной обработки разрешений также потребуется запросить Sites.FullControl.All.

Типы авторизации, области разрешений и пользователи

При настройке разрешений приложения в Microsoft Azure можно выбрать между разрешениями приложения и делегированными разрешениями. Как отмечалось выше, большинству приложений для сканирования потребуются разрешения приложений. Делегированные разрешения требуют, чтобы приложение работало в контексте пользователя, выполнившего вход, а не глобально. В делегированной модели вы ограничены контентом, к которому текущий пользователь имеет доступ.

Следует отметить, что, когда администратор предоставляет разрешения приложению, запрашивающим разрешения приложения (а не делегированных разрешений), предоставление разрешений связывается с клиентом и приложением, а не с пользователем администратора. Хотя для предоставления доступа требуется администратор, предоставление доступа не предоставляет приложению никаких специальных административных разрешений, помимо доступа к областям ресурсов, запрошенным приложением.

Для приложений, которые обрабатывают большие объемы данных из SharePoint и OneDrive, необходимо следовать последовательному шаблону вызовов, подобному следующему.

  1. Обнаружить — настройка расположения, которые нужно проверить.
  2. Обход контента — обнаружение и обработка всего набора интересующих файлов.
  3. Уведомление — отслеживание изменений в этих файлах с помощью уведомлений.
  4. Изменения процесса — повторная обработка только файлов, которые были изменены с помощью разностного запроса.

Шаблон будет выглядеть как на следующей схеме. В этой статье подробно описывается каждый этап реализации.

Сканирование потока вызовов между Microsoft Graph и клиентским приложением

Каждый из этих элементов может иметь несколько механизмов для их реализации в Microsoft Graph API и существующих API SharePoint. Цель этой статьи — предоставить вам наилучший на сегодняшний день способ для выполнения каждой задачи.

Обнаружение расположений для сканирования

Настройка нужных расположений для проверки приложением, сегодня выполняется вручную. Во многих случаях на этом этапе может быть необходимо предоставить пользователю интерфейс для работы с приложением; как вы предоставляете эту возможность и будет ли она доступна всем пользователям или только администраторам, зависит от вас. Необходимо определить, какие OneDrive и какие семейства веб-сайтов и дочерние сайты SharePoint пользователя необходимо проверить.

OneDrive каждого пользователя содержит один диск, который можно отслеживать. Семейства и дочерние сайты SharePoint могут иметь несколько дисков, по одному для каждой библиотеки документов на сайте. Каждый диск можно обнаружить на сайте с помощью конечной точки /drives. Например, чтобы получить все диски с корневого сайта клиента, можно использовать:

https://graph.microsoft.com/v1.0/sites/root/drives

Диск является отправной точкой для масштабных действий с файлами. Эти диски будут использоваться для получения полных списков файлов, подключения веб-перехватчиков для уведомлений и использования разностных запросов для получения наборов изменений элементов в дисках.

Поиск семейств веб-сайтов SharePoint и дисков OneDrive для бизнеса

Используя Microsoft Graph с разрешениями приложений, можно получить полный список семейств веб-сайтов, включая сайты, содержащие диски OneDrive для бизнеса. Чтобы получить этот список, используйте следующий вызов API:

GET /sites

API перечисления сайтов также поддерживает разностный запрос для получения сведений о новых сайтах, созданных или измененных в структуре сайтов. Поддержка разностных запросов для перечисления сайтов в настоящее время развертывается в бета-версии Microsoft Graph. Продолжайте читать, чтобы получить дополнительные сведения о разностном запросе.

Для получения уведомлений о новых семействах веб-сайтов можно подписаться на веб-перехватчики с помощью конечной точки подписок Microsoft Graph. Целевым ресурсом для этих уведомлений является /sites. Вы будете получать уведомления при создании или удалении новых семейств веб-сайтов, а также при создании дочерних сайтов или списков.

Выполнение обхода контента и обработка с помощью разностного запроса

Чтобы получить исходный список файлов на диске, выполните один вызов разностного запроса без параметров. Разностный запрос предоставляет приложениям начальный обход всего содержимого, а затем последующие изменения с определенного момента времени. Разностный запрос возвращает ссылку, необходимую для получения будущих изменений каждый раз при каждом вызове.

Например, если вы хотите получить все файлы в библиотеке документов по умолчанию на сайте SharePoint, можно использовать этот запрос:

/sites/{siteId}/drive/root/delta

Этот API возвращает страницы результатов, которые представляют все файлы на диске. После получения всех страниц файлов с помощью возвращенного @odata.nextLinkможно снова выполнить разностный запрос с возвращенным @odata.deltaLink , чтобы получить изменения с момента последнего вызова разностного запроса. Всегда не забывайте, что URL-адрес возвращается, @odata.deltaLink чтобы вы могли эффективно проверять наличие изменений в дальнейшем.

Ссылки, возвращаемые разностным запросом, будут выглядеть следующим образом:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?$select=*%2csharepointIds&token=MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM2NzExNzY2MzIxMDcwMDAwOzE5ODAzMzU5ODslMjM7JTIzOyUyMzQ",
    "value": [
        {
            "@odata.type": "#microsoft.graph.driveItem",
            "createdDateTime": "2017-07-27T02:41:36Z",
…
}

Более подробный пример см. в документации по разностным запросам.

Разностный запрос возвращает массив элементов driveItems. Если вы заранее знаете, что вам нужна конкретная информация, вы можете включить ее в оператор SELECT с разностным запросом. Вы можете дополнительно дополнить разностный вызов запросом определенного driveItem, если он вам понадобится. Разностный запрос по-прежнему поможет сократить количество элементов, которые необходимо запрашивать на предмет изменений, что сделает приложение более эффективным.

Получение уведомлений об изменениях с помощью веб-перехватчиков

Чтобы наилучшим образом использовать разностный запрос для изменений, происходящих на диске, вам нужна эффективная стратегия, чтобы знать, когда следует возвращаться и запрашивать изменения. В прошлом вы, возможно, написали свое приложение для опроса OneDrive и SharePoint через определенный фиксированный интервал и самостоятельно перечисляли изменения. С разностным запросом перечисление выполняется за вас, поэтому вам просто нужно знать, когда вернуться. Веб-перехватчики позволяют избежать опроса службы и вместо этого получать уведомление, когда изменилось то, что вас интересует. Многократный или частый опрос службы приводит к тому, что приложение блокируется из-за чрезмерного количества шаблонов вызовов.

Веб-перехватчики присоединяются с помощью API подписок для Microsoft Graph. Полную документацию по веб-перехватчикам Microsoft Graph и API подписок на сайте Microsoft Graph.

Необходимо создать подписку, связанную с определенным ресурсом (в данном случае с диском). Диски поддерживают тип изменения "обновление" для веб-перехватчиков. В "обновлении" указывается, что содержимое на диске было изменено или что новое содержимое было добавлено или удалено. Подписки на веб-перехватчика имеют связанное время ожидания, которое необходимо периодически обновлять. См. ранее упомянутую документацию о том, как обновить подписки. Рекомендуется использовать разностный запрос с последним маркером изменений сразу после подписки на веб-перехватчиков, чтобы не пропустить никаких изменений, произошедших между начальным обходом контента и настройкой веб-перехватчиков.

Даже с веб-перехватчиками, отправляющими уведомления приложения, может потребоваться предоставить периодический разностный запрос, чтобы гарантировать, что никакие изменения не будут пропущены, если с момента получения уведомления прошло много времени. Рекомендуется проводить эту периодическую проверку не чаще одного раза в день. Разностный запрос по-прежнему позволяет легко наверстать упущенное и не пропустить никаких изменений в системе.

Получение уведомлений веб-перехватчика о событиях безопасности

OneDrive и SharePoint поддерживают отправку уведомлений приложений о событиях безопасности. Чтобы подписаться на эти события, необходимо добавить заголовок "prefer:includesecuritywebhooks" в запрос на регистрацию веб-перехватчика. После регистрации веб-перехватчика вы будете получать уведомления об изменениях разрешений для элемента. Этот заголовок можно использовать в SharePoint и OneDrive для бизнеса, но не в учетных записях потребителей в OneDrive.

Изменения в процессе

После того, как приложение получит уведомление через веб-перехватчик, вам необходимо подтвердить уведомление, немедленно отправив код 202 — принято обратно в Microsoft Graph. Этот код необходимо отправить перед началом любой длительной обработки. В противном случае будут отправлены дополнительные попытки, которые ваше приложение может рассматривать как ложные уведомления.

После подтверждения отправьте разностного запрос о последних изменениях, и ваше приложение должно быть обновлено. Если вы ожидаете интенсивного трафика на определенном диске, вам следует рассмотреть возможность вызова разностного запроса с сокращенным интервалом, а не после каждого уведомления об изменении. Кроме того, необходимо сохранить новое значение, возвращенное в параметре deltaLink, чтобы получить новый маркер для повторного вызова API.

Если обработка требует загрузки содержимого отдельного файла, можно использовать свойство cTag, чтобы определить, изменилось ли содержимое файла с момента последней загрузки. Как только вам будет необходимо загрузить файл, вы можете получить доступ к свойству /content объекта DriveItem, возвращенного в ответе на разностный запрос.

Сканирование иерархии разрешений

По умолчанию ответ на запрос изменений включает информацию об общем доступе для элементов, даже если они наследуют разрешения от родительского элемента и сами непосредственно не имеют изменений общего доступа. Обратите внимание, что ответ на разностный запрос включает только элементы с прямыми изменениями их содержимого или метаданных и родительской иерархии измененных элементов. Обычно за этим следует дополнительный запрос на получение сведений о разрешениях для каждого элемента, а не только для тех, которые имеют изменения общего доступа. Чтобы получить более детальные сведения о произошедших изменениях разрешений, добавьте в запрос заголовок "Prefer: hierarchicalsharing".

При наличии заголовка "Prefer: hierarchicalsharing" возвращается информация об общем доступе для корневого элемента иерархии разрешений, а также для элементов с изменениями общего доступа. В случае когда изменения состоят в отмене общего доступа для элемента, отображается пустой аспект общего доступа, что позволяет отличать элементы, наследующие разрешения от родителя, и уникальные элементы, не имеющие ссылок для общего доступа. Пустой аспект общего доступа также отображается для корневого элемента иерархии разрешений, который не имеет общего доступа.

Во многих сценариях сканирования интерес представляют именно изменения разрешений. Чтобы получить сведения о том, какие изменения являются следствием изменений разрешений, можно использовать в запросе заголовок "Prefer: hierarchicalsharing". Когда в этом заголовке будут представлены все элементы, которые отображаются в ответе запроса из-за изменений разрешений, будет отображаться заметка OData "@microsoft.graph.sharedChanged":"True" при вызове Microsoft Graph, при непосредственном использовании API SharePoint или OneDrive API заметка будет "@oneDrive.sharedChanged":"True". Как и веб-перехватчики безопасности, эта функция применима к SharePoint и OneDrive для бизнеса, но не к личным учетным записям OneDrive.

Что происходит при регулировании?

В некоторых сценариях приложение может получить ответ 429 или 503 от Microsoft Graph. Это означает, что ваш запрос в настоящее время регулируется. Следует иметь в виду, что SharePoint регулирует приложения в зависимости от их использования каждым клиентом. Обслуживание запроса для одного ресурса в клиенте соответственно даст вам меньше ресурсов для вызова другого ресурса для того же клиента. В конечном итоге может быть несколько причин, по которым ваше приложение получает ответ о регулировании, и очень важно, чтобы ваше приложение правильно реагировало в этих ситуациях.

Чтобы восстановиться после получения кода ответа 429 или 503, попробуйте еще раз после ожидания в течение времени, указанного в поле Retry-After в заголовке ответа. Если регулирование сохраняется, значение Retry-After может со временем увеличиться, что позволит системе восстановиться. Приложения, которые не соблюдают повторную попытку по истечении времени до обратного вызова, будут заблокированы из-за оскорбительных шаблонов вызовов.

При ожидании восстановления 429 или 503 убедитесь, что вы приостановили все дальнейшие запросы, которые вы делаете в службе. Это особенно важно в многопоточных сценариях. Выполнение дополнительных вызовов при получении ответов регулирования увеличит время, необходимое вашему приложению, чтобы стать нерегулируемым.

Дополнительные сведения о том, как ресурсы Microsoft Graph работают с регулированием, см. в руководстве по регулированию Microsoft Graph.