Datenmodell der Drive Activity API

In diesem Leitfaden werden die Hauptkomponenten einer Antwort in der Google Drive Activity API erläutert. Außerdem finden Sie Beispiele und Informationen zur Interpretation.

Objekte

  • DriveActivity: Dies ist die primäre Ressource, die von Abfragen an die Drive Activity API zurückgegeben wird. Sie beschreibt eine oder mehrere Akteure, die eine oder mehrere Aktionen ausführen, die sich auf ein oder mehrere Ziele auswirken.

  • Timestamp und TimeRange: Diese beschreiben entweder einen einzelnen Zeitpunkt, zu dem die Aktivität stattgefunden hat, oder den Beginn und das Ende der Aktivität in einem bestimmten Zeitraum.

  • Actor: In der Regel ist ein Actor ein Endnutzer. Manchmal kann ein Systemereignis jedoch eine Action auslösen, wenn ein Administrator als Nutzer oder in seiner eigenen Rolle agiert oder wenn die Aktion von einer nicht identifizierbaren Person ausgeführt wird. Die Actor-Nachricht umschließt jeden dieser Fälle.

  • Target: Ein Target ist das Objekt einer Aktivität, z. B. eine Datei, ein Ordner, eine geteilte Ablage oder ein Dateikommentar. Viele Aktionstypen unterstützen mehrere Zieltypen. Edit gilt beispielsweise allgemein für Google Drive-Dateien, aber auch andere Aktionen wie Rename und Create können auf Google Drive-Ordner und geteilte Ablagen angewendet werden. Ziele, die keine Drive-Elemente sind, können sich dennoch auf ein Drive-Element beziehen, z. B. auf den Stammordner einer Drive-Ablage oder das übergeordnete Dokument, das einen Dateikommentar enthält.

  • Action: Jede DriveActivity-Ressource hat eine oder mehrere zugehörige Aktionen. Ein Action ist wie ein Ereignis in sich geschlossen. Es enthält nicht nur den detaillierten Typ und Informationen zur Aktion, sondern auch ein Actor, ein Target und entweder ein Timestamp oder TimeRange. Um Redundanzen zu vermeiden, werden in einer Action keine eigenen Felder für Target, Actor oder Zeit angegeben, wenn diese mit den Feldern der gesamten DriveActivity übereinstimmen.

  • ActionDetail: Der spezifische Typ und detaillierte Informationen zu einer Action. Ein Move-Aktionshinweis enthält beispielsweise einen Quell- und einen Zielspeicherort und ein PermissionChange gibt an, wer jetzt mit welchen Berechtigungen auf ein Dokument zugreifen kann.

Beispielantworten

Im Folgenden finden Sie einige Beispielantworten.

Ein Nutzer hat eine Datei in Drive bearbeitet

Eine DriveActivity-Ressource kann nur eine Aktion enthalten, z. B. wenn ein Nutzer eine Datei bearbeitet.

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } } ],
  "timestamp":{ "seconds":"1536794657", "nanos":791000000 },
  "actions":[ { "detail":{ "edit":{} } } ]
}]

Diese Ausgabe enthält die folgenden Werte:

  • ACCOUNT_ID: die ID des Nutzers. Sie kann mit der People API verwendet werden, um weitere Informationen zu erhalten.
  • ITEM_ID: die ID des Drive-Elements.
  • TITLE: der Titel des Drive-Elements.

Das Action-Objekt in dieser Antwort enthält keine Actor-, Target- oder timestamp-Elemente, da sie mit den Elementen der gesamten DriveActivity identisch sind.

Zwei Nutzer haben dieselbe Datei ungefähr zur selben Zeit bearbeitet.

Wenn ein ConsolidationStrategy verwendet wird, werden zugehörige Aktionen in einer kombinierten DriveActivity gruppiert. In diesem Beispiel sind zwei ähnliche Aktionen gruppiert: ein Edit-Aktionstyp von zwei verschiedenen Nutzern.

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "timeRange":{
    "startTime":{ "seconds":"1541089823", "nanos":712000000 },
    "endTime":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

Diese Ausgabe enthält die folgenden Werte:

  • ACCOUNT_ID_1: die ID des ersten Nutzers. Sie kann mit der Personen API verwendet werden, um weitere Informationen zu erhalten.
  • ACCOUNT_ID_2: die ID des zweiten Nutzers.
  • ITEM_ID: die ID des Drive-Elements.
  • TITLE: der Titel des Drive-Elements.

Das Action-Objekt in dieser Antwort enthält kein Target, da es mit dem gesamten DriveActivity identisch ist.

Das Beispiel zeigt auch, wie Apps nur die Zusammenfassungsinformationen in DriveActivity verwenden, ohne sich die einzelnen Aktionen anzusehen. Die Antwort gibt an, dass zwei Nutzer eine bestimmte Datei über einen bestimmten Zeitraum bearbeitet haben.

Ein Nutzer hat zwei Dateien in ein neues Verzeichnis verschoben.

In diesem Beispiel hat ConsolidationStrategy zwei ähnliche Move-Aktionen gruppiert, da die Dateien gleichzeitig von derselben Quelle an dasselbe Ziel verschoben wurden.

"activities":[{
  "primaryActionDetail":{
    "move":{
      "addedParents":[ { ... } ]
      "removedParents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
    }
  ]
}]

Diese Ausgabe enthält die folgenden Werte:

  • ACCOUNT_ID: die ID des Nutzers. Sie kann mit der People API verwendet werden, um weitere Informationen zu erhalten.
  • ITEM_ID_1: die ID des ersten Drive-Elements.
  • ITEM_ID_2: die ID des zweiten Drive-Elements.
  • TITLE_1: der Titel des ersten Drive-Elements.
  • TITLE_2: der Titel des zweiten Drive-Elements.

Das Action-Objekt in dieser Antwort enthält weder Actor noch timestamp, da sie mit dem gesamten DriveActivity übereinstimmen.