Przesyłanie żądań w interfejsie Google Drive Activity API

Z tego przewodnika dowiesz się, jak wysyłać żądania do interfejsu Google Drive Activity API za pomocą metody activity.query.

Klucz zapytania

Możesz prosić o aktywność na 2 sposoby: według elementu na Dysku Google lub we wszystkich elementach w hierarchii folderów.

• itemName: format tego klucza to „items/ITEM_ID”. Zwykle jest to plik na Dysku. Jeśli określisz folder dla tego klucza, będzie w nim widoczna aktywność związana z tym folderem, na przykład data utworzenia lub nazwy tego folderu.

• ancestorName: format tego klucza to „items/ITEM_ID”, a odpowiedź zawiera aktywność dotyczącą wszystkich elementów w poddrzewie poniżej tego folderu.

Gdy nie jest ustawiony żaden klucz, domyślnie jest używany ancestorName elementu „items/root” (element główny) i pokazuje aktywność dla wszystkich elementów na Dysku.

Podział na strony

Pole pageSize pozwala zażądać przybliżonej liczby działań do zwrócenia w każdej odpowiedzi. Rzeczywista liczba zwracanych działań będzie się różnić, dlatego aplikacja powinna obsłużyć w odpowiedzi dowolne ilości.

Rozmiary stron są ograniczone. Jeśli aplikacja wymaga wielu działań, zamiast ustawiać dużą wartość pageSize, wysyłaj wiele żądań z wykorzystaniem podziału na strony. Jeśli do pobrania może być dostępnych więcej aktywności, niż jest zawarte w odpowiedzi, odpowiedź będzie też zawierać element nextPageToken. Aby pobrać więcej wyników, powtórz to samo żądanie, ale dodaj pole pageToken z wartością nextPageToken z poprzedniej odpowiedzi.

Konsolidacja

Obiekty Action są często grupowane i zwracane w ramach jednego zasobu DriveActivity. Niektóre grupowanie Action odbywa się spontanicznie. Na przykład przeniesienie elementu do folderu udostępnionego powoduje zmianę uprawnień.

W żądaniu możesz też określić element ConsolidationStrategy (nazywany czasem agregacją lub grupowaniem). Dzięki temu można grupować powiązane obiekty Action, np. przez kilka osób edytujących jeden element lub przeniesienie wielu plików za pomocą Actor do nowego folderu na Dysku.

Chociaż pojedynczy element Action ma 1 element Actor i 1 Target, po grupowaniu DriveActivity może mieć wielu podmiotów i wiele elementów docelowych. Jednak nawet po grupowaniu zawsze występuje „główne” działanie, które jest albo reprezentatywne lub najważniejsze ze wszystkich działań w zasobie DriveActivity, w zależności od oczekiwanej strategii konsolidacji.

W efekcie, niezależnie od tego, czy konsolidacja jest włączona, wielu klientów może wyświetlać tylko zawartość najwyższego poziomu zasobu DriveActivity (np. zbiorowe podmioty i cele w primaryActionDetail) i ignorować szczegółowe działania w odpowiedzi.

Filtry

Możesz ograniczyć działania, które mogą być zwracane w zasobie DriveActivity, tworząc ciąg filter w żądaniu activity.query. Dostępne są 2 obsługiwane pola: time i detail.action_detail_case.

Filtruj według czasu

Aby ograniczyć działania według zakresu czasu, wpisz nazwę pola time z operatorami numerycznymi w wartościach dat, połączoną opcjonalną operatorem „AND”. Użyj milisekund od 1 stycznia 1970 r. lub formatu RFC 3339, na przykład:

• time > 1452409200000 AND time <= 1492812924310
• time >= "2016-01-10T01:02:03-05:00"

Filtruj według typu:

Aby ograniczyć zakres według typu działania, zastosuj nazwę pola detail.action_detail_case z operatorem „has” (:). Użyj liczby pojedynczej lub listy dozwolonych typów działań ujętych w nawiasy i rozdzielone spacją. Listę typów działań znajdziesz w obiektach ActionDetail.

Aby wykluczyć z odpowiedzi typ działania, dodaj łącznik (-) na początku ciągu filtra.

Oto kilka przykładów działań:

• detail.action_detail_case:RENAME
• detail.action_detail_case:(CREATE RESTORE)
• -detail.action_detail_case:MOVE

Kombinacje

Te warunki filtrowania można połączyć w pojedynczy ciąg znaków filter, na przykład:

• detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

Przykładowe żądania

Poproś o 10 ostatnich aktywności dotyczących elementu na Dysku:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

Żądaj skonsolidowanych działań dla każdego elementu na Dysku pod folderem nadrzędnym:

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

Poproś o wszystkie działania MOVE i RENAME dotyczące elementu na Dysku:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

Poproś o całą aktywność od 1 stycznia 2018 r. czasu EST:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

Poproś o całą aktywność z wyjątkiem działań EDIT w czerwcu 2017 r. czasu UTC:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}