API actions

`files_file_create(context, data_dict)`

Create a new file.

This action passes uploaded file to the storage without strict validation. File is converted into standard upload object and everything else is controlled by storage. The same file may be uploaded to one storage and rejected by other, depending on configuration.

This action is way too powerful to use it directly. The recommended approach is to register a different action for handling specific type of uploads and call current action internally.

When uploading a real file(or using werkqeug.datastructures.FileStorage), name parameter can be omited. In this case, the name of uploaded file is used.

ckanapi action files_file_create upload@path/to/file.txt

When uploading a raw content of the file using string or bytes object, name is mandatory.

ckanapi action files_file_create upload@<(echo -n "hello world") name=file.txt

Requires storage with CREATE capability.

PARAMETER	DESCRIPTION
`name`	human-readable name of the file. Default: guess using upload field TYPE: `str`
`storage`	name of the storage that will handle the upload. Default: `default` TYPE: `str`
`upload`	content of the file as bytes, file descriptor or uploaded file TYPE: `Uploadable`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with file details.

`files_file_show(context, data_dict)`

Show file details.

This action only displays information from DB record. There is no way to get the content of the file using this action(or any other API action).

ckanapi action files_file_show id=226056e2-6f83-47c5-8bd2-102e2b82ab9a

PARAMETER	DESCRIPTION
`id`	ID of the file TYPE: `str`
`completed`	use `False` to show incomplete uploads. Default: `True` TYPE: `bool`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with file details

`files_file_rename(context, data_dict)`

Rename the file.

This action changes human-readable name of the file, which is stored in DB. Real location of the file in the storage is not modified.

ckanapi action files_file_show \
    id=226056e2-6f83-47c5-8bd2-102e2b82ab9a \
    name=new-name.txt

Args: id (str): ID of the file name (str): new name of the file completed (bool): use False to rename incomplete uploads. Default: True

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with file details

`files_file_replace(context, data_dict)`

Replace content of the file.

New file must have the same MIMEtype as the original file.

Size and content hash from the new file will replace original values. All other fields, including name, remain unchanged.

ckanapi action files_file_replace id=123 upload@path/to/file.txt

Requires storage with CREATE and REMOVE capability.

PARAMETER	DESCRIPTION
`id`	ID of the replaced file TYPE: `str`
`upload`	content of the file as bytes, file descriptor or uploaded file TYPE: `Uploadable`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with file details.

`files_file_delete(context, data_dict)`

Remove file from storage.

Unlike packages, file has no state field. Removal usually means that file details removed from DB and file itself removed from the storage.

Some storage can implement revisions of the file and keep archived versions or backups. Check storage documentation if you need to know whether there are chances that file is not completely removed with this operation.

Requires storage with REMOVE capability.

ckanapi action files_file_delete id=226056e2-6f83-47c5-8bd2-102e2b82ab9a

PARAMETER	DESCRIPTION
`id`	ID of the file TYPE: `str`
`completed`	use `False` to remove incomplete uploads. Default: `True` TYPE: `bool`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of the removed file.

`files_file_search(context, data_dict)`

Search files.

This action is not stabilized yet and will change in future.

Provides an ability to search files using exact filter by name, content_type, size, owner, etc. Results are paginated and returned in package_search manner, as dict with count and results items.

All columns of File model can be used as filters. Before the search, type of column and type of filter value are compared. If they are the same, original values are used in search. If type different, column value and filter value are casted to string.

This request produces size = 10 SQL expression:

ckanapi action files_file_search size:10

This request produces size::text = '10' SQL expression:

ckanapi action files_file_search size=10

Even though results are usually not changed, using correct types leads to more efficient search.

Apart from File columns, the following Owner properties can be used for searching: owner_id, owner_type, pinned.

storage_data and plugin_data are dictionaries. Filter's value for these fields used as a mask. For example, storage_data={"a": {"b": 1}} matches any File with storage_data containing item a with value that contains b=1. This works only with data represented by nested dictionaries, without other structures, like list or sets.

Experimental feature: File columns can be passed as a pair of operator and value. This feature will be replaced by strictly defined query language at some point:

ckanapi action files_file_search size:'["<", 100]' content_type:'["like", "text/%"]'

Fillowing operators are accepted: =, <, >, !=, like

PARAMETER	DESCRIPTION
`start`	index of first row in result/number of rows to skip. Default: `0` TYPE: `int`
`rows`	number of rows to return. Default: `10` TYPE: `int`
`sort`	name of File column used for sorting. Default: `name` TYPE: `str`
`reverse`	sort results in descending order. Default: `False` TYPE: `bool`
`storage_data`	mask for `storage_data` column. Default: `{}` TYPE: `dict[str, Any]`
`plugin_data`	mask for `plugin_data` column. Default: `{}` TYPE: `dict[str, Any]`
`owner_id`	show only specific owner id if present. Default: `None` TYPE: `str`
`owner_type`	show only specific owner type if present. Default: `None` TYPE: `str`
`pinned`	show only pinned/unpinned items if present. Default: `None` TYPE: `bool`
`completed`	use `False` to search incomplete uploads. Default: `True` TYPE: `bool`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with `count` and `results`

`files_file_scan(context, data_dict)`

List files of the owner.

This action internally calls files_file_search, but with static values of owner filters. If owner is not specified, files filtered by current user. If owner is specified, user must pass authorization check to see files.

PARAMETER	DESCRIPTION
`owner_id`	ID of the owner TYPE: `str`
`owner_type`	type of the owner TYPE: `str`
`**rest`	The all other parameters are passed as-is to `files_file_search`. TYPE: `Any`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with `count` and `results`

`files_transfer_ownership(context, data_dict)`

Transfer file ownership.

PARAMETER	DESCRIPTION
`id`	ID of the file upload TYPE: `str`
`completed`	use `False` to transfer incomplete uploads. Default: `True` TYPE: `bool`
`owner_id`	ID of the new owner TYPE: `str`
`owner_type`	type of the new owner TYPE: `str`
`force`	move file even if it's pinned. Default: `False` TYPE: `bool`
`pin`	pin file after transfer to stop future transfers. Default: `False` TYPE: `bool`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of updated file

`files_file_pin(context, data_dict)`

Pin file to the current owner.

Pinned file cannot be transfered to a different owner. Use it to guarantee that file referred by entity is not accidentally transferred to a different owner.

PARAMETER	DESCRIPTION
`id`	ID of the file TYPE: `str`
`completed`	use `False` to pin incomplete uploads. Default: `True` TYPE: `bool`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of updated file

`files_file_unpin(context, data_dict)`

Pin file to the current owner.

Pinned file cannot be transfered to a different owner. Use it to guarantee that file referred by entity is not accidentally transferred to a different owner.

PARAMETER	DESCRIPTION
`id`	ID of the file TYPE: `str`
`completed`	use `False` to unpin incomplete uploads. Default: `True` TYPE: `bool`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of updated file

`files_multipart_start(context, data_dict)`

Initialize multipart(resumable,continuous,signed,etc) upload.

Apart from standard parameters, different storages can require additional data, so always check documentation of the storage before initiating multipart upload.

When upload initialized, storage usually returns details required for further upload. It may be a presigned URL for direct upload, or just an ID of upload which must be used with files_multipart_update.

Requires storage with MULTIPART capability.

PARAMETER	DESCRIPTION
`storage`	name of the storage that will handle the upload. Default: `default` TYPE: `str`
`name`	name of the uploaded file. TYPE: `str`
`content_type`	MIMEtype of the uploaded file. Used for validation TYPE: `str`
`size`	Expected size of upload. Used for validation TYPE: `oint`
`hash`	Expected content hash. If present, used for validation. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of initiated upload. Depends on used storage

`files_multipart_update(context, data_dict)`

Update incomplete upload.

Depending on storage this action may require additional parameters. Most likely, upload with the fragment of uploaded file.

Requires storage with MULTIPART capability.

PARAMETER	DESCRIPTION
`id`	ID of the incomplete upload TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of the updated upload

`files_multipart_refresh(context, data_dict)`

Refresh details of incomplete upload.

Can be used if upload process was interrupted and client does not how many bytes were already uploaded.

Requires storage with MULTIPART capability.

PARAMETER	DESCRIPTION
`id`	ID of the incomplete upload TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of the updated upload

`files_multipart_complete(context, data_dict)`

Finalize multipart upload and transform it into completed file.

Depending on storage this action may require additional parameters. But usually it just takes ID and verify that content type, size and hash provided when upload was initialized, much the actual value.

If data is valid and file is completed inside the storage, new File entry with file details created in DB and file can be used just as any normal file.

Requires storage with MULTIPART capability.

PARAMETER	DESCRIPTION
`id`	ID of the incomplete upload TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with details of the created file

`files_resource_upload(context, data_dict)`

Create a new file inside resource storage.

This action internally calls files_file_create with ignore_auth=True and always uses resources storage.

New file is not attached to resource. You need to call files_transfer_ownership manually, when resource created.

PARAMETER	DESCRIPTION
`name`	human-readable name of the file. Default: guess using upload field TYPE: `str`
`upload`	content of the file as bytes, file descriptor or uploaded file TYPE: `Uploadable`

RETURNS	DESCRIPTION
`dict[str, Any]`	dictionary with file details