Anfragen in der Google Drive Activity API senden

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

Suchanfrageschlüssel

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

  • itemName: Das Format für diesen Schlüssel lautet „items/ITEM_ID“. In der Regel ist dies eine Datei in Drive. Wenn Sie einen Ordner für diesen Schlüssel angeben, werden Aktivitäten für den Ordner 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 im untergeordneten Knoten unter diesem Ordner.

Wenn kein Schlüssel festgelegt ist, wird standardmäßig die ancestorName von „items/root“ verwendet und Aktivitäten für alle Elemente in Google Drive werden 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 kann variieren. Ihre App sollte daher beliebige Mengen in der Antwort verarbeiten.

Die Seitengröße ist begrenzt. Wenn Ihre App viele Aktivitäten benötigt, senden Sie mehrere Anfragen mithilfe der Paginierung, anstatt einen hohen Wert für pageSize festzulegen. Wenn möglicherweise mehr Aktivitäten abgerufen werden können, als in der Antwort enthalten sind, enthält die Antwort auch einen nextPageToken. Wenn Sie weitere Ergebnisse abrufen möchten, wiederholen Sie dieselbe Anfrage, fügen Sie aber ein pageToken-Feld mit dem Wert nextPageToken aus der vorherigen Antwort hinzu.

Konsolidierung

Action-Objekte werden häufig gruppiert und in einer einzigen DriveActivity-Ressource zurückgegeben. Einige Action-Gruppen entstehen spontan, z. B. wenn ein Element in einen freigegebenen Ordner verschoben wird, was eine Berechtigungsänderung auslöst.

Sie können auch einen ConsolidationStrategy (manchmal auch Aggregation oder Batching genannt) in der Anfrage angeben. So sind andere Gruppierungen ähnlicher Action-Objekte möglich, z. B. mehrere Bearbeiter für ein Element oder ein Actor, das mehrere Dateien in einen neuen Drive-Ordner verschiebt.

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

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

Filter

Du kannst die Aktionen einschränken, die in der DriveActivity-Ressource zurückgegeben werden können, indem du in der activity.query-Anfrage einen filter-String erstellst. Es gibt zwei unterstützte Felder: time und detail.action_detail_case.

Nach Zeitraum filtern

Wenn Sie Aktionen auf einen bestimmten Zeitraum beschränken möchten, geben Sie den Feldnamen time mit numerischen Operatoren für Datumswerte an, die durch ein optionales „AND“ verbunden sind. 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

Wenn Sie die Ergebnisse nach Aktionstyp einschränken möchten, verwenden Sie den Feldnamen detail.action_detail_case mit dem Operator „hat“ (:). Verwenden Sie entweder einen einzelnen Wert oder eine Liste zulässiger Aktionstypen, die in Klammern und durch ein Leerzeichen getrennt sind. Eine Liste der Aktionstypen finden Sie in den ActionDetail-Objekten.

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

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 übergeordneten 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 anfordern (EST):

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

Alle Aktivitäten (außer EDIT-Aktionen) für Juni 2017 in UTC anfordern:

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