R6 Class representing a File

R6 Class representing a resource for managing files and folders.

Super class

sevenbridges2::Item -> File

Public fields

URL

List of URL endpoints for this resource.

id

File ID.

name

File name.

size

File size.

project

Project ID if any, where file/folder is located.

created_on

Date file/folder was created on.

modified_on

Date file/folder was modified on.

storage

File/folder's storage type.

origin

Task ID if file/folder is produced by some task execution.

tags

List of tags associated with the file.

metadata

List for metadata associated with the file.

url

File download URL.

parent

Parent folder ID.

type

This can be of type file or folder.

secondary_files

Secondary files linked to the file if exist.

Methods

Public methods

• File$new()

• File$print()

• File$detailed_print()

• File$reload()

• File$update()

• File$add_tag()

• File$copy_to()

• File$get_download_url()

• File$get_metadata()

• File$set_metadata()

• File$move_to_folder()

• File$list_contents()

• File$delete()

• File$download()

• File$submit_export()

• File$clone()

---

Method new()

Create a new File object.

Usage

File$new(res = NA, ...)

Arguments

res

Response containing File object information.

...

Other response arguments.

---

Method print()

Print method for File class.

Usage

File$print()

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Print file object
 file_object$print()
}

---

Method detailed_print()

Detailed print method for File class.

Usage

File$detailed_print()

Details

The call returns the file's name, its tags, and all of its metadata. Apart from regular file fields there are some additional fields:

• storage field denotes the type of storage for the file which can be either PLATFORM or VOLUME depending on where the file is stored.

• origin field denotes the task that produced the file, if it was created by a task on the Seven Bridges Platform.

• metadata field lists the metadata fields and values for the file.

• tags field lists the tags for the file. Learn more about tagging your files on the Platform.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Detailed print of file object
 file_object$detailed_print()
}

---

Method reload()

Reload File object information.

Usage

File$reload(...)

Arguments

...

Other arguments that can be passed to core api() function like 'fields', etc.

Returns

File object.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Reload file object
 file_object$reload()
}

---

Method update()

Updates the name, the full set metadata, and tags for a specified file. .

Usage

File$update(name = NULL, metadata = NULL, tags = NULL, ...)

Arguments

name

The new name of the file.

metadata

The metadata fields and their values that you want to update. This is a named list of key-value pairs. The keys and values are strings.

tags

The tags you want to update, represented as unnamed list of values to add as tags.

...

Other arguments that can be passed to core api() function like 'limit', 'offset', 'fields', etc.

Returns

Updated File object.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Update file object
 file_object$update(name = "new_name")
}

---

Method add_tag()

This method allows you to tag files on the Platform. You can tag your files on the Platform with keywords to make it easier to identify and organize files you’ve imported from public datasets or copied between projects.
More details on how to use this call can be found here.

Usage

File$add_tag(tags, overwrite = FALSE, ...)

Arguments

tags

The tags you want to update, represented as unnamed list of values to add as tags.

overwrite

Set to TRUE if you want to overwrite existing tags. Default: FALSE.

...

Additional parameters that can be passed to the method.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Add new tag to file object
 file_object$add_tag(tags = c("new_tag"))
}

---

Method copy_to()

This call copies the specified file to a new project. Files retain their metadata when copied, but may be assigned new names in their target project. To make this call, you should have copy permission within the project you are copying from.
Note: If you want to copy multiple files, the recommended way is to do it in bulk considering the API rate limit (learn more). You can do that using Auth$copy_files() operation.

Usage

File$copy_to(project, name = NULL, ...)

Arguments

project

The ID of the project or a Project object where you want to copy the file to.

name

The new name the file will have in the target project. If its name will not change, omit this key.

...

Other arguments that can be passed to core api() function like 'fields', etc.

Returns

Copied File object.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Copy file object to project
 file_object$copy_to(project = project)
}

---

Method get_download_url()

This method returns a URL that you can use to download the specified file.

Usage

File$get_download_url(...)

Arguments

...

Other arguments that can be passed to core api() function like 'fields', etc.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Get download url for file object
 file_object$get_download_url()
}

---

Method get_metadata()

This call returns the metadata values for the specified file.

Usage

File$get_metadata(...)

Arguments

...

Other arguments that can be passed to core api() function like 'fields', etc.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Get metadata for file object
 file_object$get_metadata()
}

---

Method set_metadata()

This call changes the metadata values for the specified file.
More details about how to modify metadata, you can find in the API documentation.

Usage

File$set_metadata(metadata_fields, overwrite = FALSE, ...)

Arguments

metadata_fields

Enter a list of key-value pairs of metadata fields and metadata values.

overwrite

Set to TRUE if you want to overwrite existing tags. Default: FALSE.

...

Other arguments that can be passed to core api() function like 'fields', etc.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Set metadata for file object
 file_object$set_metadata(metadata_fields = list("field_1" = "value_1"))
}

---

Method move_to_folder()

This call moves a file from one folder to another. Moving of files is only allowed within the same project.

Usage

File$move_to_folder(parent, name = NULL)

Arguments

parent

The ID of target folder or a File object which must be of type FOLDER.

name

Specify a new name for a file in case you want to rename it. If you want to use the same name, omit this key.

Returns

Moved File object.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Move file object to a project
 file_object$move_to_folder(parent = "parent-folder-id")
}

---

Method list_contents()

List folder contents.

Usage

File$list_contents(
  limit = getOption("sevenbridges2")$limit,
  offset = getOption("sevenbridges2")$offset,
  ...
)

Arguments

limit

The maximum number of collection items to return for a single request. Minimum value is 1. The maximum value is 100 and the default value is 50. This is a pagination-specific attribute.

offset

The zero-based starting index in the entire collection of the first item to return. The default value is 0. This is a pagination-specific attribute.

...

Other arguments that can be passed to core api() function like 'fields', etc.

Returns

Collection of File objects.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # List folder's content
 file_object$list_contents()
}

---

Method delete()

Delete method for File objects.

Usage

File$delete()

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Delete file object
 file_object$delete()
}

---

Method download()

Download method for File objects. It allows download a platform file to your local computer. To specify the destination for your download, you should provide the path to the destination directory as directory_path parameter.

Usage

File$download(
  directory_path,
  filename = self$name,
  method = "curl",
  retry_count = getOption("sevenbridges2")$default_retry_count,
  retry_timeout = getOption("sevenbridges2")$default_retry_timeout
)

Arguments

directory_path

Path to the destination directory of a new file.

filename

Full name for the new file, including its extension. By default, the name field of File object will be used.

method

Method to be used for downloading files. By default, this parameter is set to curl.

retry_count

Number of retries if error occurs during download.

retry_timeout

Number of seconds between two retries.

Examples

\dontrun{
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Download file object
 file_object$download(directory_path = ".")
}

---

Method submit_export()

This call lets you queue a job to export this file from a project on the Platform into a volume. The file selected for export must not be a public file or an alias. Aliases are objects stored in your cloud storage bucket which have been made available on the Platform. The volume you are exporting to must be configured for read-write access. To do this, set the access_mode parameter to RW when creating or modifying a volume.

Essentially, the call writes to your cloud storage bucket via the volume. If this call is successful, the original project file will become an alias to the newly exported object on the volume. The source file will be deleted from the Platform and, if no more copies of this file exist, it will no longer count towards your total storage price on the Platform.
In summary, once you export a file from the Platform to a volume, it is no longer part of the storage on the Platform and cannot be exported again.

Read more about this operation in our documentation here.
If you want to export multiple files, the recommended way is to do it in bulk considering the API rate limit (learn more) (bulk operations will be implemented in next releases).

Usage

File$submit_export(
  destination_volume,
  destination_location,
  overwrite = FALSE,
  copy_only = FALSE,
  properties = NULL,
  ...
)

Arguments

destination_volume

Volume id or Volume object you want to export files into. Required.

destination_location

Volume-specific location to which the file will be exported. This location should be recognizable to the underlying cloud service as a valid key or path to a new file. Please note that if this volume has been configured with a prefix parameter, the value of prefix will be prepended to location before attempting to create the file on the volume.

If you would like to export the file into some folder on the volume, please add folder name as prefix before file name in form <folder-name>/<file-name>.

overwrite

Set to TRUE of you want to overwrite the item that already exists at the destination. Default: FALSE.

copy_only

If TRUE, file will be copied to a volume but source file will remain on the Platform.

properties

Named list of additional volume properties, like:

• sse_algorithm - S3 server-side encryption to use when exporting to this bucket. Supported values: AES256 (SSE-S3 encryption), aws:kms, null (no server-side encryption). Default: AES256.

• sse_aws_kms_key_id: Applies to type: s3. If AWS KMS encryption is used, this should be set to the required KMS key. If not set and aws:kms is set as sse_algorithm, default KMS key is used.

• aws_canned_acl: S3 canned ACL to apply on the object on during export. Supported values: any one of S3 canned ACLs; null (do not apply canned ACLs). Default: null.

...

Other arguments that can be passed to core api() function like 'fields', etc.

Returns

Export object.

Examples

\dontrun{
 # x is API response when file is requested
 file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Export file object to a volume
 file_object$submit_export(
               destination_volume = volume,
               destination_location = location
             )
}

---

Method clone()

The objects of this class are cloneable with this method.

Usage

File$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

## ------------------------------------------------
## Method `File$print`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Print file object
 file_object$print()
}


## ------------------------------------------------
## Method `File$detailed_print`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Detailed print of file object
 file_object$detailed_print()
}


## ------------------------------------------------
## Method `File$reload`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Reload file object
 file_object$reload()
}


## ------------------------------------------------
## Method `File$update`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Update file object
 file_object$update(name = "new_name")
}


## ------------------------------------------------
## Method `File$add_tag`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Add new tag to file object
 file_object$add_tag(tags = c("new_tag"))
}


## ------------------------------------------------
## Method `File$copy_to`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Copy file object to project
 file_object$copy_to(project = project)
}


## ------------------------------------------------
## Method `File$get_download_url`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Get download url for file object
 file_object$get_download_url()
}


## ------------------------------------------------
## Method `File$get_metadata`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Get metadata for file object
 file_object$get_metadata()
}


## ------------------------------------------------
## Method `File$set_metadata`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Set metadata for file object
 file_object$set_metadata(metadata_fields = list("field_1" = "value_1"))
}


## ------------------------------------------------
## Method `File$move_to_folder`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Move file object to a project
 file_object$move_to_folder(parent = "parent-folder-id")
}


## ------------------------------------------------
## Method `File$list_contents`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # List folder's content
 file_object$list_contents()
}


## ------------------------------------------------
## Method `File$delete`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Delete file object
 file_object$delete()
}


## ------------------------------------------------
## Method `File$download`
## ------------------------------------------------

if (FALSE) {
# x is API response when file is requested
file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Download file object
 file_object$download(directory_path = ".")
}


## ------------------------------------------------
## Method `File$submit_export`
## ------------------------------------------------

if (FALSE) {
 # x is API response when file is requested
 file_object <- File$new(
                    res = x,
                    href = x$href,
                    auth = auth,
                    response = attr(x, "response")
                   )

 # Export file object to a volume
 file_object$submit_export(
               destination_volume = volume,
               destination_location = location
             )
}