Model danych interfejsu Drive Activity API

W tym przewodniku omawiamy główne komponenty odpowiedzi w interfejsie Google Drive Activity API, a także przykłady i sposoby ich interpretacji.

Obiekty

• DriveActivity – jest to główny zasób zwracany przez zapytania do interfejsu Drive Activity API. Opisuje one co najmniej 1 użytkownika wykonującego co najmniej 1 działanie mające wpływ na co najmniej 1 cel.

• Timestamp i TimeRange – opisują odpowiednio pojedynczy moment w czasie wystąpienia aktywności lub początek i koniec jej wystąpienia w danym okresie.

• Actor – zazwyczaj Actor to użytkownik. Czasami zdarzenie systemowe może jednak aktywować Action, gdy administrator działa jako użytkownik lub w imieniu siebie albo gdy jest wykonywany przez osobę niemożliwą do zidentyfikowania. Komunikat Actor opisuje każdy z tych przypadków.

• Target – Target to obiekt działania, np. plik, folder, dysk współdzielony lub komentarz do pliku. Pamiętaj, że wiele typów działań obsługuje więcej niż jeden rodzaj celu. Na przykład chociaż właściwość Edit zasadniczo ma zastosowanie do plików na Dysku, inne działania, takie jak Rename i Create, mogą też mieć zastosowanie do folderów na Dysku i dysków współdzielonych. Cele, które nie są elementami na Dysku, nadal mogą się odnosić do folderu głównego na dysku lub do dokumentu nadrzędnego zawierającego komentarz do pliku.

• Action – z każdym DriveActivityzasobem powiązane jest co najmniej jedno działanie. Element Action jest autonomiczny, podobnie jak wydarzenie, ponieważ obejmuje nie tylko szczegółowy typ i informacje na temat działania, ale także Actor, Target oraz Timestamp lub TimeRange. Aby uniknąć nadmiarowości, Action nie wypełni własnych pól Target, Actor ani pól czasu, gdy są one takie same jak pole ogólne DriveActivity.

• ActionDetail – jest to konkretny typ i szczegółowe informacje o elemencie Action. Na przykład szczegóły działania Move zawierają lokalizację źródłową i docelową, a element PermissionChange określa, kto może teraz uzyskać dostęp do dokumentu i z jakimi uprawnieniami.

Przykładowe odpowiedzi

Użytkownik zmodyfikował plik na Dysku:

Prosty zasób DriveActivity może zawierać tylko jedno działanie, na przykład edytowanie 1 pliku przez użytkownika.

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

Dane wyjściowe zawierają te wartości:

• ACCOUNT_ID: identyfikator użytkownika. Można go używać z interfejsem People API, aby uzyskać więcej informacji.
• ITEM_ID: identyfikator elementu na Dysku.
• TITLE: tytuł elementu na Dysku.

Zauważ, że pole Action w tej odpowiedzi nie zawiera wartości Actor, Target ani TimeStamp, ponieważ są one takie same jak ogólna wartość DriveActivity.

Dwóch użytkowników edytowało ten sam plik w podobnych momentach:

Po włączeniu konsolidacji powiązane działania są grupowane w jeden DriveActivity. W tym przykładzie pogrupowaliśmy 2 podobne działania: 1 typ działania Edit pochodzących od 2 różnych użytkowników.

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

Dane wyjściowe zawierają te wartości:

• ACCOUNT_ID_1: identyfikator pierwszego użytkownika. Można go używać z interfejsem People API, aby uzyskać więcej informacji.
• ACCOUNT_ID_2: identyfikator drugiego użytkownika.
• ITEM_ID: identyfikator elementu na Dysku.
• TITLE: tytuł elementu na Dysku.

Pamiętaj, że działania w tej odpowiedzi nie obejmują polecenia Target, ponieważ jest ono identyczne z ogólną wartością DriveActivity.

Ten przykład pokazuje też, jak aplikacje mogą korzystać tylko z informacji podsumowujących w polu DriveActivity bez uwzględniania poszczególnych działań. Odpowiedź wskazuje, że 2 użytkowników edytowało dany plik w określonym przedziale czasu.

Użytkownik przeniósł 2 pliki do nowego katalogu:

W tym przykładzie strategia konsolidacji grupowała 2 powiązane działania Move, ponieważ pliki zostały przeniesione z tego samego źródła do tego samego miejsca docelowego w tym samym czasie.

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

Dane wyjściowe zawierają te wartości:

• ACCOUNT_ID: identyfikator użytkownika. Można go używać z interfejsem People API, aby uzyskać więcej informacji.
• ITEM_ID_1: identyfikator pierwszego elementu na Dysku.
• ITEM_ID_2: identyfikator drugiego elementu na Dysku.
• TITLE_1: tytuł pierwszego elementu na Dysku.
• TITLE_2: tytuł drugiego elementu na Dysku.

Pamiętaj, że działania w tej odpowiedzi nie obejmują właściwości Actor ani TimeStamp, ponieważ są one identyczne z ogólnymi wartościami DriveActivity.