564 lines
20 KiB
Plaintext
564 lines
20 KiB
Plaintext
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."
|
|
|
|
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,
|
|
sometimes there are legal restrictions due to copyright claims."
|
|
|
|
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."
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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."
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
#
|
|
# 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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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"
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
route templates/get_for_team(GetTemplateArg, GetTemplateResult, TemplateError)
|
|
"Get the schema for a specified template."
|
|
|
|
attrs
|
|
auth="team"
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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"
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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"
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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"
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|
|
|
|
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
|
|
api_group="properties"
|
|
owner = "api-platform"
|