R: R6 Class representing a File

File {sevenbridges2}

R Documentation

R6 Class representing a File

Description

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`
## ------------------------------------------------

## Not run: 
# 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()

## End(Not run)


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

## Not run: 
# 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()

## End(Not run)


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

## Not run: 
# 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()

## End(Not run)


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

## Not run: 
# 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")

## End(Not run)


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

## Not run: 
# 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"))

## End(Not run)


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

## Not run: 
# 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)

## End(Not run)


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

## Not run: 
# 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()

## End(Not run)


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

## Not run: 
# 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()

## End(Not run)


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

## Not run: 
# 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"))

## End(Not run)


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

## Not run: 
# 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")

## End(Not run)


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

## Not run: 
# 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()

## End(Not run)


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

## Not run: 
# 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()

## End(Not run)


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

## Not run: 
# 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 = ".")

## End(Not run)


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

## Not run: 
 # 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
             )

## End(Not run)

[Package sevenbridges2 version 0.2.0 Index]

R6 Class representing a File

Description

Super class

Public fields

Methods

Public methods

Method new()

Usage

Arguments

Method print()

Usage

Examples

Method detailed_print()

Usage

Details

Examples

Method reload()

Usage

Arguments

Returns

Examples

Method update()

Usage

Arguments

Returns

Examples

Method add_tag()

Usage

Arguments

Examples

Method copy_to()

Usage

Arguments

Returns

Examples

Method get_download_url()

Usage

Arguments

Examples

Method get_metadata()

Usage

Arguments

Examples

Method set_metadata()

Usage

Arguments

Examples

Method move_to_folder()

Usage

Arguments

Returns

Examples

Method list_contents()

Usage

Arguments

Returns

Examples

Method delete()

Usage

Examples

Method download()

Usage

Arguments

Examples

Method submit_export()

Usage

Arguments

Returns

Examples

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `print()`

Method `detailed_print()`

Method `reload()`

Method `update()`

Method `add_tag()`

Method `copy_to()`

Method `get_download_url()`

Method `get_metadata()`

Method `set_metadata()`

Method `move_to_folder()`

Method `list_contents()`

Method `delete()`

Method `download()`

Method `submit_export()`

Method `clone()`