120 lines
4.3 KiB
Plaintext
120 lines
4.3 KiB
Plaintext
namespace team_log
|
|
|
|
import async
|
|
import common
|
|
import team
|
|
import team_common
|
|
import users_common
|
|
|
|
###############################
|
|
# Routes declarations
|
|
###############################
|
|
|
|
struct GetTeamEventsArg
|
|
limit UInt32(min_value=1, max_value=1000) = 1000
|
|
"The maximal number of results to return per call. Note that some calls may not return
|
|
:field:`limit` number of events, and may even return no events, even with `has_more` set to true.
|
|
In this case, callers should fetch again using :route:`get_events/continue`."
|
|
account_id users_common.AccountId?
|
|
"Filter the events by account ID. Return ony events with this account_id as either
|
|
Actor, Context, or Participants."
|
|
time team_common.TimeRange?
|
|
"Filter by time range."
|
|
category EventCategory?
|
|
"Filter the returned events to a single category."
|
|
|
|
example default
|
|
limit=50
|
|
category=groups
|
|
|
|
# This is used only for `json_encode` in metaserver/tests/util/event_helper.py
|
|
# simply because I don't know how to use the list.
|
|
alias TeamEventList = List(TeamEvent)
|
|
|
|
struct GetTeamEventsResult
|
|
events List(TeamEvent)
|
|
"List of events. Note that events are not guaranteed to be sorted by their timestamp value."
|
|
cursor String
|
|
"Pass the cursor into :route:`get_events/continue` to obtain additional events.
|
|
|
|
The value of :field:`cursor` may change for each response from :route:`get_events/continue`,
|
|
regardless of the value of :field:`has_more`; older cursor strings may expire.
|
|
|
|
Thus, callers should ensure that they update their cursor based on the latest value of
|
|
:field:`cursor` after each call, and poll regularly if they wish to poll for new events.
|
|
|
|
Callers should handle reset exceptions for expired cursors."
|
|
has_more Boolean
|
|
"Is true if there may be additional events that have not been returned yet.
|
|
An additional call to :route:`get_events/continue` can retrieve them.
|
|
Note that :field:`has_more` may be :val:`true`, even if :field:`events` is empty."
|
|
|
|
example default
|
|
events = [default]
|
|
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
|
|
has_more = false
|
|
|
|
union GetTeamEventsError
|
|
"Errors that can be raised when calling :route:`get_events`."
|
|
|
|
account_id_not_found
|
|
"No user found matching the provided account_id."
|
|
invalid_time_range
|
|
"Invalid time range."
|
|
|
|
example default
|
|
account_id_not_found = null
|
|
|
|
route get_events(GetTeamEventsArg, GetTeamEventsResult, GetTeamEventsError)
|
|
"Retrieves team events.
|
|
|
|
Events have a lifespan of two years. Events older than two years will not be returned.
|
|
|
|
Many attributes note 'may be missing due to historical data gap'.
|
|
|
|
Note that the file_operations category and & analogous paper events are not available on all
|
|
Dropbox Business :link:`plans /business/plans-comparison`.
|
|
Use :link:`features/get_values /developers/documentation/http/teams#team-features-get_values`
|
|
to check for this feature.
|
|
|
|
Permission : Team Auditing."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "audit-log-team"
|
|
|
|
struct GetTeamEventsContinueArg
|
|
cursor String
|
|
"Indicates from what point to get the next set of events."
|
|
|
|
example default
|
|
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
|
|
|
|
|
|
union GetTeamEventsContinueError
|
|
"Errors that can be raised when calling :route:`get_events/continue`."
|
|
|
|
bad_cursor
|
|
"Bad cursor."
|
|
|
|
reset common.DropboxTimestamp
|
|
"Cursors are intended to be used quickly. Individual cursor values are normally valid for days,
|
|
but in rare cases may be reset sooner.
|
|
|
|
Cursor reset errors should be handled by fetching a new cursor from :route:`get_events`.
|
|
|
|
The associated value is the approximate timestamp of the most recent event returned by the cursor.
|
|
This should be used as a resumption point when calling :route:`get_events` to obtain a new cursor."
|
|
|
|
example default
|
|
bad_cursor = null
|
|
|
|
route get_events/continue(GetTeamEventsContinueArg, GetTeamEventsResult, GetTeamEventsContinueError)
|
|
"Once a cursor has been retrieved from :route:`get_events`, use this to paginate through all events.
|
|
|
|
Permission : Team Auditing."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "audit-log-team"
|