Datenmodell der Drive Activity API

In diesem Leitfaden werden die Hauptkomponenten einer Antwort in der Google Drive Activity API anhand von Beispielen und deren Interpretation erläutert.

Objekte

• DriveActivity: Dies ist die primäre Ressource, die bei Abfragen an die Drive Activity API zurückgegeben wird. Es beschreibt einen oder mehrere Akteure, die eine oder mehrere Aktionen ausführen, die ein oder mehrere Ziele betreffen.

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

• Actor: In der Regel ist ein Actor ein Endnutzer. Manchmal kann ein Systemereignis jedoch ein Action auslösen, wenn ein Administrator als Nutzer oder als der Nutzer agiert oder wenn das Ereignis von einer nicht identifizierbaren Person ausgeführt wird. Die Actor-Nachricht enthält 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. Beachten Sie, dass viele Aktionstypen mehr als eine Art von Ziel unterstützen. Beispiel: Obwohl Edit allgemein für Drive-Dateien gilt, können andere Aktionen wie Rename und Create auch für Drive-Ordner und geteilte Ablagen gelten. Ziele, die keine Drive-Elemente sind, können dennoch auf ein Laufwerk verweisen, z. B. auf den Stammordner eines Laufwerks oder auf das übergeordnete Dokument mit einem Dateikommentar.

• Action – Jede DriveActivity-Ressource hat eine oder mehrere zugehörige Aktionen. Ein Action ist wie ein Ereignis in sich geschlossen, da es nicht nur den detaillierten Typ und die Informationen zur Aktion enthält, sondern auch ein Actor, eine Target und entweder einen Timestamp oder einen TimeRange. Um Redundanz zu vermeiden, füllt ein Action keine eigenen Target-, Actor- oder Zeitfelder aus, wenn diese mit dem gesamten DriveActivity identisch sind.

• ActionDetail: Dies sind der spezifische Typ und die detaillierten Informationen zu einem Action. Ein Move-Aktionsdetail hat beispielsweise einen Quell- und einen Zielspeicherort und ein PermissionChange gibt an, wer jetzt auf ein Dokument zugreifen kann und mit welchen Berechtigungen.

Beispielantworten

Ein Nutzer hat eine Datei in Google Drive bearbeitet:

Eine einfache DriveActivity-Ressource kann nur eine Aktion enthalten, z. B. das Bearbeiten einer Datei durch einen Nutzer.

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "drive_item":{ "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 zusammen mit der People API verwendet werden, um weitere Informationen zu erhalten.
• ITEM_ID: die ID der Drive-Datei.
• TITLE: der Titel der Drive-Datei.

Hinweis: Action in dieser Antwort enthält nicht Actor, Target oder TimeStamp, da sie mit der gesamten DriveActivity identisch sind.

Zwei Nutzer haben dieselbe Datei gleichzeitig bearbeitet:

Wenn die Konsolidierung aktiviert ist, werden zusammengehörige Aktionen in einer DriveActivity gruppiert. In diesem Beispiel sind zwei ähnliche Aktionen gruppiert: ein Edit-Aktionstyp von zwei verschiedenen Nutzern.

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "time_range":{
    "start_time":{ "seconds":"1541089823", "nanos":712000000 },
    "end_time":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"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 zusammen mit der People API verwendet werden, um weitere Informationen zu erhalten.
• ACCOUNT_ID_2: die ID des zweiten Nutzers.
• ITEM_ID: die ID der Drive-Datei.
• TITLE: der Titel der Drive-Datei.

Beachten Sie, dass die Aktionen in dieser Antwort nicht das Target enthalten, da es mit dem gesamten DriveActivity identisch ist.

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

Ein Nutzer hat zwei Dateien in ein neues Verzeichnis verschoben:

In diesem Beispiel wurden im Rahmen der Konsolidierungsstrategie zwei verwandte Move-Aktionen gruppiert, da die Dateien gleichzeitig aus derselben Quelle zum selben Ziel verschoben wurden.

"activities":[{
  "primary_action_detail":{
    "move":{
      "added_parents":[ { ... } ]
      "removed_parents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
    }
  ]
}]

Diese Ausgabe enthält die folgenden Werte:

• ACCOUNT_ID: die ID des Nutzers. Sie kann zusammen 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

Die Aktionen in dieser Antwort enthalten nicht Actor oder TimeStamp, da sie mit der gesamten DriveActivity identisch sind.