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 wszystkich elementów 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. kiedy został utworzony lub przemianowany.

  • 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 zostanie 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 Twoja aplikacja powinna obsługiwać w odpowiedzi dowolne ilości.

Rozmiary stron są ograniczone. Jeśli Twoja aplikacja wymaga wielu aktywności, zamiast ustawiania dużej wartości parametru pageSize wyślij kilka żądań z użyciem podziału na strony. Jeśli w odpowiedzi jest mniej aktywności niż ta, którą chcesz pobrać, 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 pojedynczego zasobu DriveActivity. Niektóre z tych Actiongrupowań powstają spontanicznie, np. gdy 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 inne grupowania powiązanych obiektów Action, np. wielu aktorów edytujących jeden element lub jeden obiekt Actor przenoszący wiele plików do nowego folderu na Dysku.

Pojedynczy element Action ma 1 element Actor i 1 element Target, ale po zgrupowaniu tworzony element DriveActivity może mieć wielu wykonawców i wiele elementów docelowych. Jednak nawet po zgrupowaniu 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 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 czasowego, określ nazwę pola time za pomocą operatorów liczbowych na wartościach daty połączonych 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 znaków 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 całej aktywności (z wyjątkiem działań EDIT) z czerwca 2017 roku 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"
}