Anfragen über die Google Drive Activity API senden

In dieser Anleitung wird erläutert, wie Sie Anfragen in der Google Drive Activity API mit der Methode activity.query stellen.

Abfrageschlüssel

Es gibt zwei Möglichkeiten, Aktivitäten anzufordern: nach Google Drive-Element oder für alle Elemente innerhalb einer Ordnerhierarchie.

  • itemName: Das Format für diesen Schlüssel ist „items/ITEM_ID“. Normalerweise ist dies eine Datei in Drive. Wenn Sie für diesen Schlüssel einen Ordner angeben, werden die Aktivitäten für den Ordner angezeigt, z. B. der Zeitpunkt der Erstellung oder Umbenennung.

  • ancestorName: Das Format für diesen Schlüssel ist „items/ITEM_ID“. Die Antwort enthält Aktivitäten für alle Elemente in der Unterstruktur unter diesem Ordner.

Wenn kein Schlüssel festgelegt ist, wird standardmäßig das ancestorName von „items/root“ verwendet und es wird die Aktivität für alle Elemente in Ihrer Ablage angezeigt.

Seitenumbruch

Mit dem Feld pageSize können Sie eine ungefähre Anzahl von Aktivitäten anfordern, die in jeder Antwort zurückgegeben werden sollen. Die tatsächliche Anzahl der zurückgegebenen Aktivitäten variiert, sodass Ihre Anwendung in der Antwort beliebige Mengen verarbeiten sollte.

Die Seitengröße ist begrenzt. Wenn Ihre Anwendung viele Aktivitäten benötigt, stellen Sie mehrere Anfragen mit Paginierung, anstatt einen hohen Wert für pageSize festzulegen. Wenn insbesondere mehr Aktivitäten abgerufen werden müssen, als in der Antwort enthalten sind, enthält die Antwort auch eine nextPageToken. Wiederholen Sie dieselbe Anfrage, um weitere Ergebnisse abzurufen, fügen Sie jedoch das Feld pageToken mit dem Wert nextPageToken aus der vorherigen Antwort hinzu.

Konsolidierung

Action-Objekte werden häufig innerhalb einer einzelnen DriveActivity-Ressource gruppiert und zurückgegeben. Einige Action-Gruppierungen erfolgen spontan, z. B. wenn ein Element in einen freigegebenen Ordner verschoben wird, wodurch eine Berechtigungsänderung ausgelöst wird.

Sie können auch einen ConsolidationStrategy (auch Zusammenfassung oder Batching genannt) in der Anfrage angeben. Dadurch sind andere Gruppierungen zusammengehöriger Action-Objekte möglich, z. B. mehrere Akteure, die ein Element bearbeiten, oder ein Actor, das mehrere Dateien in einen neuen Drive-Ordner verschiebt.

Während eine einzelne Action eine Actor und eine Target hat, kann der resultierende DriveActivity nach der Gruppierung mehrere Akteure und mehrere Ziele haben. Auch nach der Gruppierung gibt es jedoch immer eine „primäre“ Aktion, die je nach angeforderter Konsolidierungsstrategie entweder repräsentativ oder die wichtigste aller Aktionen in der Ressource DriveActivity ist.

Unabhängig davon, ob die Konsolidierung aktiviert ist oder nicht, reicht es für viele Clients aus, nur die Inhalte der obersten Ebene einer DriveActivity-Ressource anzusehen (z. B. die kollektiven Akteure und Ziele in primaryActionDetail) und die detaillierten Aktionen in der Antwort zu ignorieren.

Filter

Sie können die Aktionen einschränken, die in der Ressource DriveActivity zurückgegeben werden können. Erstellen Sie dazu in der activity.query-Anfrage einen filter-String. Es werden zwei Felder unterstützt: time und detail.action_detail_case.

Nach Zeitraum filtern

Wenn Sie Aktionen nach Zeitraum einschränken möchten, geben Sie den Feldnamen time mit numerischen Operatoren für Datumswerte an, verbunden mit einem optionalen „AND“. Verwenden Sie Millisekunden seit dem 1. Januar 1970 oder das RFC 3339-Format, z. B.:

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

Nach Typ filtern

Zur Einschränkung nach Aktionstyp wenden Sie den Feldnamen detail.action_detail_case mit dem Operator "has" (:) an. Verwenden Sie entweder einen einzelnen Wert oder eine Liste zulässiger Aktionstypen in Klammern und durch ein Leerzeichen getrennt. Eine Liste der Aktionstypen finden Sie in den ActionDetail-Objekten.

Wenn Sie einen Aktionstyp aus der Antwort ausschließen möchten, setzen Sie am Anfang des Filterstrings einen Bindestrich (-).

Hier einige Beispiele für Aktionstypen:

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

Kombinationen

Diese Filterbedingungen können in einem einzelnen filter-String kombiniert werden, z. B.:

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

Beispielanfragen

So fordern Sie die zehn letzten Aktivitäten für ein Drive-Element an:

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

Fordern Sie konsolidierte Aktivitäten für jedes Drive-Element unter einem Ancestor-Ordner an:

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

So fordern Sie alle MOVE- und RENAME-Aktionen für ein Drive-Element an:

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

Alle Aktivitäten seit dem 1. Januar 2018 (EST) anfordern:

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

Alle Aktivitäten mit Ausnahme von EDIT Aktionen im Juni 2017 (UTC) anfordern:

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