В этом руководстве объясняется, как отправлять запросы в API активности Google Диска с помощью метода activity.query
.
Ключ запроса
Есть два способа запросить активность: по элементу Google Диска или по всему, что находится в иерархии папок.
itemName
: формат этого ключа — «items/ITEM_ID». Обычно это файл на Диске. Если вы укажете папку для этого ключа, он покажет активность этой папки, например, когда она была создана или переименована.ancestorName
: формат этого ключа — «items/ITEM_ID», и ответ включает активность всех элементов в поддереве ниже этой папки.
Если ключ не установлен, по умолчанию используется ancestorName
«items/root» и отображается активность для всех элементов на вашем Диске.
Пагинация
Поле pageSize
позволяет вам запросить приблизительное количество действий, возвращаемых в каждом ответе. Фактическое количество возвращаемых действий будет варьироваться, поэтому ваше приложение должно обрабатывать произвольные количества в ответе.
Размеры страниц ограничены. Если вашему приложению требуется много действий, сделайте несколько запросов, используя разбиение на страницы, вместо того, чтобы задавать большое значение для pageSize
. В частности, если необходимо получить больше активности, чем включено в ответ, тогда ответ также будет содержать nextPageToken
. Чтобы получить больше результатов, повторите тот же запрос, но добавьте поле pageToken
со значением nextPageToken
из предыдущего ответа.
Консолидация
Объекты Action
часто группируются и возвращаются в одном ресурсе DriveActivity
. Некоторые группы Action
возникают спонтанно, например перемещение элемента в общую папку, вызывающее изменение разрешений.
Вы также можете указать в запросе ConsolidationStrategy
(иногда называемую агрегацией или пакетной обработкой). Это позволяет использовать другие группы связанных объектов Action
, например несколько актеров, редактирующих один элемент, или один Actor
, перемещающий несколько файлов в новую папку на Диске.
Хотя отдельное Action
имеет одного Actor
и одну Target
, после группировки результирующий DriveActivity
может иметь несколько актеров и несколько целей. Однако даже после группировки всегда существует «основное» действие, которое является репрезентативным или наиболее важным из всех действий в ресурсе DriveActivity
, в зависимости от запрошенной стратегии консолидации.
В результате, независимо от того, включена консолидация или нет, многим клиентам может быть достаточно просматривать только содержимое верхнего уровня ресурса DriveActivity
(например, коллективные действующие лица и цели в primaryActionDetail
) и игнорировать подробные действия в ответ.
Фильтры
Вы можете ограничить действия, которые могут быть возвращены в ресурсе DriveActivity
, создав строку filter
в запросе activity.query
. Поддерживаются 2 поля: time
и detail.action_detail_case
.
Фильтровать по времени
Чтобы ограничить действия по диапазону времени, укажите time
имени поля с помощью числовых операторов над значениями даты, соединенных необязательным знаком «И». Используйте миллисекунды с 1 января 1970 года или формат RFC 3339 , например:
-
time > 1452409200000 AND time <= 1492812924310
-
time >= "2016-01-10T01:02:03-05:00"
Фильтровать по типу
Чтобы ограничить тип действия, примените имя поля detail.action_detail_case
с оператором has ( :
). Используйте либо единственное значение, либо список разрешенных типов действий, заключенный в круглые скобки и разделенные пробелом. Чтобы найти список типов действий, просмотрите объекты ActionDetail
.
Чтобы исключить тип действия из ответа, добавьте дефис ( -
) в начало строки фильтра.
Вот несколько примеров типов действий:
-
detail.action_detail_case:RENAME
-
detail.action_detail_case:(CREATE RESTORE)
-
-detail.action_detail_case:MOVE
Комбинации
Эти условия фильтрации можно объединить в одну строку filter
, например:
-
detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000
Примеры запросов
Запросите 10 последних действий для объекта на Диске:
{
"itemName": "items/ITEM_ID",
"pageSize": 10
}
Запросите консолидированные действия для каждого элемента Диска, находящегося в родительской папке:
{
"ancestorName": "items/ITEM_ID",
"consolidationStrategy": {
"legacy": {}
}
}
Запросите все действия MOVE
и RENAME
объект на Диске:
{
"itemName": "items/ITEM_ID",
"filter": "detail.action_detail_case:(MOVE RENAME)"
}
Запросить всю активность с 1 января 2018 г. по восточному стандартному времени:
{
"ancestorName": "items/root",
"filter": "time >= \"2018-01-01T00:00:00-05:00\""
}
Запросить все действия, кроме действий EDIT
, в течение июня 2017 г. по всемирному координированному времени:
{
"ancestorName": "items/root",
"filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}