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

Aktywność można poprosić o 2 sposoby: według elementu na Dysku Google lub według wszystkiego 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 on pokazywać aktywność związaną z tym folderem, np. jego utworzenie lub zmianę nazwy.

  • ancestorName: format tego klucza to „items/ITEM_ID”, a odpowiedź obejmuje aktywność dotyczącą wszystkich elementów w poddrzewie pod tym folderem.

Jeśli nie ustawisz żadnego klucza, domyślnie zostanie użyty parametr ancestorName „items/root” i wyświetlona aktywność dotycząca wszystkich elementów na Dysku.

Podział na strony

Pole pageSize umożliwia określenie przybliżonej liczby aktywności, które mają być zwracane w każdej odpowiedzi. Rzeczywista liczba zwróconych aktywności będzie się różnić, dlatego aplikacja powinna obsługiwać w odpowiedzi dowolne ilości.

Rozmiary stron są ograniczone. Jeśli Twoja aplikacja wymaga wielu aktywności, wyślij kilka żądań za pomocą podziału na strony zamiast ustawiania dużej wartości dla parametru pageSize. Jeśli w związku z tym, że może być więcej aktywności do pobrania niż jest podanych w odpowiedzi, odpowiedź będzie zawierać również nextPageToken. Aby uzyskać 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 z tych Actiongrupowań powstają spontanicznie, np. przeniesienie elementu do folderu współdzielonego powoduje zmianę uprawnień.

Możesz też określić w żądaniu ConsolidationStrategy (czasem nazywane agregacją lub grupowaniem). Umożliwia to tworzenie innych grup powiązanych obiektów Action, takich jak kilka elementów edytowanych przez wielu wykonawców lub jeden element Actor przenoszony do nowego folderu na Dysku.

Pojedyncza wartość Action ma 1 wartość Actor i 1 wartość Target, ale po zgrupowaniu tworzona wartość DriveActivity może mieć wielu wykonawców i wiele celów. Jednak nawet po pogrupowaniu zawsze istnieje „podstawowe” działanie, które jest albo reprezentatywne, albo najważniejsze ze wszystkich działań w zasobie DriveActivity, w zależności od wybranej strategii konsolidacji.

W efekcie wielu klientom może wystarczyć wyświetlanie tylko treści najwyższego poziomu zasobu DriveActivity (np. zbiorczych elementów i docelowych zasobów w ramach zasobu primaryActionDetail) niezależnie od tego, czy konsolidacja jest włączona.

Filtry

Możesz ograniczyć działania, które mogą zostać zwrócone w zasobie DriveActivity, tworząc ciąg znaków filter w żądaniu activity.query. Obsługiwane są 2 pola: time i detail.action_detail_case.

Filtruj według czasu

Aby ograniczyć działania według zakresu czasowego, użyj nazwy pola time z liczbowymi operatorami na wartościach daty połączonymi opcjonalnym operatorem „AND”. Użyj milisekund od 1 stycznia 1970 r. lub formatu RFC 3339, np.:

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

Filtruj według typu:

Aby zastosować ograniczenie według typu działania, użyj nazwy pola detail.action_detail_case z operatorem „ma” (:). Użyj pojedynczej wartości lub listy dozwolonych typów działań ujętych w nawiasy i oddzielonych spacjami. Aby znaleźć listę typów działań, przejrzyj obiekty ActionDetail.

Aby wykluczyć typ działania z odpowiedzi, na początku ciągu filtra umieść myślnik (-).

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

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

Połączenia

Te warunki filtrowania można łączyć w jednym ciągu tekstowym filter, np.:

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

Przykładowe żądania

Poproś o 10 ostatnich działań związanych z elementem na Dysku:

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

Aby poprosić o zbiorcze działania dotyczące każdego elementu na Dysku w ramach folderu nadrzędnego:

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

Prośba 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 roku czasu wschodniego:

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

Poproś o wyświetlenie wszystkich działań (z wyjątkiem działań EDIT) z czerwca 2017 r. według czasu uniwersalnego:

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