-
Notifications
You must be signed in to change notification settings - Fork 41
/
file_properties.stone
550 lines (425 loc) · 20.1 KB
/
file_properties.stone
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
namespace file_properties
"This namespace contains helpers for property and template metadata endpoints.
These endpoints enable you to tag arbitrary key/value data to Dropbox files.
The most basic unit in this namespace is the :type:`PropertyField`. These fields encapsulate the
actual key/value data.
Fields are added to a Dropbox file using a :type:`PropertyGroup`. Property groups contain a
reference to a Dropbox file and a :type:`PropertyGroupTemplate`. Property groups are uniquely
identified by the combination of their associated Dropbox file and template.
The :type:`PropertyGroupTemplate` is a way of restricting the possible key names and value types
of the data within a property group. The possible key names and value types are explicitly
enumerated using :type:`PropertyFieldTemplate` objects.
You can think of a property group template as a class definition for a particular key/value
metadata object, and the property groups themselves as the instantiations of these objects.
Templates are owned either by a user/app pair or team/app pair. Templates and their associated
properties can't be accessed by any app other than the app that created them, and even then, only
when the app is linked with the owner of the template (either a user or team).
User-owned templates are accessed via the user-auth file_properties/templates/*_for_user endpoints, while
team-owned templates are accessed via the team-auth file_properties/templates/*_for_team endpoints. Properties
associated with either type of template can be accessed via the user-auth properties/* endpoints.
Finally, properties can be accessed from a number of endpoints that return metadata, including
`files/get_metadata`, and `files/list_folder`. Properties can also be added during upload, using
`files/upload`.
"
alias TemplateId = String(min_length=1,pattern="(/|ptid:).*")
alias PathOrId = String(pattern="/(.|[\\r\\n])*|id:.*|(ns:[0-9]+(/.*)?)")
alias Id = String(min_length=1)
alias PropertiesSearchCursor = String(min_length=1)
#
# Core data types
#
struct PropertyField
"Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox
files as a :type:`PropertyGroup`."
name String
"Key of the property field associated with a file and template.
Keys can be up to 256 bytes."
value String
"Value of the property field associated with a file and template.
Values can be up to 1024 bytes."
example default
name = "Security Policy"
value = "Confidential"
struct PropertyGroup
"A subset of the property fields described by the corresponding :type:`PropertyGroupTemplate`.
Properties are always added to a Dropbox file as a :type:`PropertyGroup`.
The possible key names and value types in this group are defined by the
corresponding :type:`PropertyGroupTemplate`."
template_id TemplateId
"A unique identifier for the associated template."
fields List(PropertyField)
"The actual properties associated with the template. There can be up to 32
property types per template."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
fields = [default]
struct PropertyFieldTemplate
"Defines how a single property field may be structured. Used exclusively by :type:`PropertyGroupTemplate`."
name String
"Key of the property field being described. Property field keys can be up to 256 bytes."
description String
"Description of the property field. Property field descriptions can be up to 1024 bytes."
type PropertyType
"Data type of the value of this property field. This type
will be enforced upon property creation and modifications."
union
"Data type of the given property field added."
string
"The associated property field will be of type string. Unicode is supported."
example default
string = null
example default
name = "Security Policy"
description = "This is the security policy of the file or folder described.
Policies can be Confidential, Public or Internal."
type = default
struct PropertyGroupTemplate
"Defines how a property group may be structured."
name String
"Display name for the template. Template names can
be up to 256 bytes."
description String
"Description for the template. Template descriptions
can be up to 1024 bytes."
fields List(PropertyFieldTemplate)
"Definitions of the property fields associated with this template.
There can be up to 32 properties in a single template."
example default
name = "Security"
description = "These properties describe how confidential this file or folder is."
fields = [default]
#
# Property routes
#
struct AddPropertiesArg
path PathOrId
"A unique identifier for the file or folder."
property_groups List(PropertyGroup)
"The property groups which are to be added to a Dropbox file. No two groups in the input should
refer to the same template."
example default
path = "/my_awesome/word.docx"
property_groups = [default]
union LookupError
malformed_path String
not_found
"There is nothing at the given path."
not_file
"We were expecting a file, but the given path refers to something that isn't a file."
not_folder
"We were expecting a folder, but the given path refers to something that isn't a folder."
restricted_content
"The file cannot be transferred because the content is restricted. For example, we might restrict a file due to legal requirements."
union LookUpPropertiesError
property_group_not_found
"No property group was found."
union TemplateError
template_not_found TemplateId
"Template does not exist for the given identifier."
restricted_content
"You do not have permission to modify this template."
union PropertiesError extends TemplateError
path LookupError
unsupported_folder
"This folder cannot be tagged. Tagging folders is not supported for team-owned templates."
union InvalidPropertyGroupError extends PropertiesError
property_field_too_large
"One or more of the supplied property field values is too large."
does_not_fit_template
"One or more of the supplied property fields does not conform to the template specifications."
duplicate_property_groups
"There are 2 or more property groups referring to the same templates in the input. "
union AddPropertiesError extends InvalidPropertyGroupError
property_group_already_exists
"A property group associated with this template and file already exists."
route properties/add(AddPropertiesArg, Void, AddPropertiesError)
"Add property groups to a Dropbox file. See :route:`templates/add_for_user` or
:route:`templates/add_for_team` to create new templates."
attrs
scope = "files.metadata.write"
struct OverwritePropertyGroupArg
path PathOrId
"A unique identifier for the file or folder."
property_groups List(PropertyGroup, min_items=1)
"The property groups \"snapshot\" updates to force apply. No two groups in the input should
refer to the same template."
example default
path = "/my_awesome/word.docx"
property_groups = [default]
route properties/overwrite(OverwritePropertyGroupArg, Void, InvalidPropertyGroupError)
"Overwrite property groups associated with a file. This endpoint should be used
instead of :route:`properties/update` when property groups are being updated via a
\"snapshot\" instead of via a \"delta\". In other words, this endpoint will delete all
omitted fields from a property group, whereas :route:`properties/update` will only
delete fields that are explicitly marked for deletion."
attrs
scope = "files.metadata.write"
struct PropertyGroupUpdate
template_id TemplateId
"A unique identifier for a property template."
add_or_update_fields List(PropertyField)?
"Property fields to update. If the property field already exists, it is updated.
If the property field doesn't exist, the property group is added."
remove_fields List(String)?
"Property fields to remove (by name), provided they exist."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
add_or_update_fields = [default]
remove_fields = []
struct UpdatePropertiesArg
path PathOrId
"A unique identifier for the file or folder."
update_property_groups List(PropertyGroupUpdate)
"The property groups \"delta\" updates to apply."
example default
path = "/my_awesome/word.docx"
update_property_groups = [default]
union UpdatePropertiesError extends InvalidPropertyGroupError
property_group_lookup LookUpPropertiesError
route properties/update(UpdatePropertiesArg, Void, UpdatePropertiesError)
"Add, update or remove properties associated with the supplied file and templates.
This endpoint should be used instead of :route:`properties/overwrite` when property groups
are being updated via a \"delta\" instead of via a \"snapshot\" . In other words, this endpoint
will not delete any omitted fields from a property group, whereas :route:`properties/overwrite`
will delete any fields that are omitted from a property group."
attrs
scope = "files.metadata.write"
struct RemovePropertiesArg
path PathOrId
"A unique identifier for the file or folder."
property_template_ids List(TemplateId)
"A list of identifiers for a template created by :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
path = "/my_awesome/word.docx"
property_template_ids = ["ptid:1a5n2i6d3OYEAAAAAAAAAYa"]
union RemovePropertiesError extends PropertiesError
property_group_lookup LookUpPropertiesError
route properties/remove(RemovePropertiesArg, Void, RemovePropertiesError)
"Permanently removes the specified property group from the file. To remove specific property field key
value pairs, see :route:`properties/update`.
To update a template, see
:route:`templates/update_for_user` or :route:`templates/update_for_team`.
To remove a template, see
:route:`templates/remove_for_user` or :route:`templates/remove_for_team`."
attrs
scope = "files.metadata.write"
#
# Property Group Template Routes
#
struct AddTemplateArg extends PropertyGroupTemplate
example default
name = "Security"
description = "These properties describe how confidential this file or folder is."
fields = [default]
struct AddTemplateResult
template_id TemplateId
"An identifier for template added by See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
union ModifyTemplateError extends TemplateError
conflicting_property_names
"A property field key with that name already exists in the template."
too_many_properties
"There are too many properties in the changed template.
The maximum number of properties per template is 32."
too_many_templates
"There are too many templates for the team."
template_attribute_too_large
"The template name, description or one or more of the property field keys is too large."
route templates/add_for_user(AddTemplateArg, AddTemplateResult, ModifyTemplateError)
"Add a template associated with a user. See :route:`properties/add` to add properties to a file. This
endpoint can't be called on a team member or admin's behalf."
attrs
scope = "files.metadata.write"
route templates/add_for_team(AddTemplateArg, AddTemplateResult, ModifyTemplateError)
"Add a template associated with a team. See :route:`properties/add` to add properties to a file or folder.
Note: this endpoint will create team-owned templates."
attrs
auth="team"
scope = "files.team_metadata.write"
struct GetTemplateArg
template_id TemplateId
"An identifier for template added by route See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
struct GetTemplateResult extends PropertyGroupTemplate
example default
name = "Security"
description = "These properties describe how confidential this file or folder is."
fields = [default]
route templates/get_for_user(GetTemplateArg, GetTemplateResult, TemplateError)
"Get the schema for a specified template. This endpoint can't be called on a team member or admin's behalf."
attrs
scope = "files.metadata.read"
route templates/get_for_team(GetTemplateArg, GetTemplateResult, TemplateError)
"Get the schema for a specified template."
attrs
auth="team"
scope = "files.team_metadata.write"
struct UpdateTemplateArg
template_id TemplateId
"An identifier for template added by See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
name String?
"A display name for the template. template names can
be up to 256 bytes."
description String?
"Description for the new template. Template descriptions
can be up to 1024 bytes."
add_fields List(PropertyFieldTemplate)?
"Property field templates to be added to the group template.
There can be up to 32 properties in a single template."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
name = "New Security Template Name"
description = "These properties will describe how confidential this file or folder is."
add_fields = [default]
struct UpdateTemplateResult
template_id TemplateId
"An identifier for template added by route See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
route templates/update_for_user(UpdateTemplateArg, UpdateTemplateResult, ModifyTemplateError)
"Update a template associated with a user. This route can update the template name,
the template description and add optional properties to templates. This endpoint can't
be called on a team member or admin's behalf."
attrs
scope = "files.metadata.write"
route templates/update_for_team(UpdateTemplateArg, UpdateTemplateResult, ModifyTemplateError)
"Update a template associated with a team. This route can update the template name,
the template description and add optional properties to templates."
attrs
auth="team"
scope = "files.team_metadata.write"
struct ListTemplateResult
template_ids List(TemplateId)
"List of identifiers for templates added by See :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_ids = ["ptid:1a5n2i6d3OYEAAAAAAAAAYa"]
route templates/list_for_user(Void, ListTemplateResult, TemplateError)
"Get the template identifiers for a team. To get the schema of
each template use :route:`templates/get_for_user`. This endpoint can't be
called on a team member or admin's behalf."
attrs
scope = "files.metadata.read"
route templates/list_for_team(Void, ListTemplateResult, TemplateError)
"Get the template identifiers for a team. To get the schema of
each template use :route:`templates/get_for_team`."
attrs
auth="team"
scope = "files.team_metadata.write"
struct RemoveTemplateArg
template_id TemplateId
"An identifier for a template created by :route:`templates/add_for_user` or
:route:`templates/add_for_team`."
example default
template_id = "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
route templates/remove_for_user(RemoveTemplateArg, Void, TemplateError)
"Permanently removes the specified template created from :route:`templates/add_for_user`.
All properties associated with the template will also be removed. This action
cannot be undone."
attrs
scope = "files.metadata.write"
route templates/remove_for_team(RemoveTemplateArg, Void, TemplateError)
"Permanently removes the specified template created from :route:`templates/add_for_user`.
All properties associated with the template will also be removed. This action
cannot be undone."
attrs
auth="team"
scope = "files.team_metadata.write"
union TemplateOwnerType
user
"Template will be associated with a user."
team
"Template will be associated with a team."
example default
user = null
union LogicalOperator
"Logical operator to join search queries together."
or_operator
"Append a query with an \"or\" operator."
example default
or_operator = null
union PropertiesSearchMode
field_name String
"Search for a value associated with this field name."
example default
field_name = "Security"
struct PropertiesSearchQuery
query String
"The property field value for which to search across templates."
mode PropertiesSearchMode
"The mode with which to perform the search."
logical_operator LogicalOperator = or_operator
"The logical operator with which to append the query."
example default
query = "Confidential"
mode = default
logical_operator = default
union TemplateFilterBase
filter_some List(TemplateId, min_items=1)
"Only templates with an ID in the supplied list will be returned (a subset of
templates will be returned)."
example default
filter_some = ["ptid:1a5n2i6d3OYEAAAAAAAAAYa"]
union TemplateFilter extends TemplateFilterBase
filter_none
"No templates will be filtered from the result (all templates will be returned)."
example default
filter_none = null
struct PropertiesSearchArg
queries List(PropertiesSearchQuery, min_items=1)
"Queries to search."
template_filter TemplateFilter = filter_none
"Filter results to contain only properties associated with these template IDs."
example default
queries = [default]
template_filter = default
struct PropertiesSearchMatch
id Id
"The ID for the matched file or folder."
path String
"The path for the matched file or folder."
is_deleted Boolean
"Whether the file or folder is deleted."
property_groups List(PropertyGroup)
"List of custom property groups associated with the file."
example default
id = "id:a4ayc_80_OEAAAAAAAAAXz"
path = "/my_awesome/word.docx"
is_deleted = false
property_groups = [default]
struct PropertiesSearchResult
matches List(PropertiesSearchMatch)
"A list (possibly empty) of matches for the query."
cursor PropertiesSearchCursor?
"Pass the cursor into :route:`properties/search/continue` to continue to receive
search results. Cursor will be null when there are no more results."
example default
matches = [default]
union PropertiesSearchError
property_group_lookup LookUpPropertiesError
route properties/search(PropertiesSearchArg, PropertiesSearchResult, PropertiesSearchError)
"Search across property templates for particular property field values."
attrs
scope = "files.metadata.read"
struct PropertiesSearchContinueArg
cursor PropertiesSearchCursor
"The cursor returned by your last call to :route:`properties/search` or
:route:`properties/search/continue`."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
union PropertiesSearchContinueError
reset
"Indicates that the cursor has been invalidated. Call
:route:`properties/search` to obtain a new cursor."
route properties/search/continue (PropertiesSearchContinueArg, PropertiesSearchResult, PropertiesSearchContinueError)
"Once a cursor has been retrieved from :route:`properties/search`, use this to paginate through all
search results."
attrs
scope = "files.metadata.read"