Anfragen in der Google Drive Activity API senden

In diesem Leitfaden wird erläutert, wie Sie mit der Methode activity.query Anfragen an die Google Drive Activity API senden.

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, wird dessen Aktivität angezeigt, z. B. wann er erstellt oder umbenannt wurde.

  • 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 werden Aktivitäten 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 beliebige Mengen in der Antwort verarbeiten sollte.

Die Seitengröße ist begrenzt. Wenn Ihre Anwendung viele Aktivitäten benötigt, stellen Sie mehrere Anfragen über die Paginierung, anstatt einen großen Wert für pageSize festzulegen. Wenn mehr Aktivitäten abgerufen werden müssen als in der Antwort enthalten ist, enthält die Antwort auch einen 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 oft innerhalb einer einzelnen DriveActivity-Ressource gruppiert und zurückgegeben. Einige Action-Gruppierungen werden spontan ausgeführt, z. B. das Verschieben eines Elements in einen freigegebenen Ordner, wodurch eine Berechtigungsänderung ausgelöst wird.

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

Während eine einzelne Action eine Actor und ein 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 möglicherweise aus, nur die Inhalte der obersten Ebene einer DriveActivity-Ressource anzusehen (z. B. die kollektiven Akteure und Ziele innerhalb des 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önnten. 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, verbunden durch ein optionales „AND“, an. 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

Für eine 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 einzigen 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
}

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

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

Alle MOVE- und RENAME-Aktionen für ein Drive-Element anfordern:

{
  "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"
}