Skip to main content
A newer release of this product is available.

Retrieve files and directories

Contributors
PDFs

GET /storage/volumes/{volume.uuid}/files/{path}

Retrieves a list of files and directories for a given directory of a volume along with the directory's properties or only the properties of a given file of a volume.

Learn more

Parameters

Name Type In Required Description

volume.uuid

string

path

True

Volume UUID

path

string

path

True

Relative path of a file or directory in the volume. The path field requires using "%2E" to represent "." and "%2F" to represent "/" for the path provided.

byte_offset

integer

query

False

The file offset to start reading from.

length

integer

query

False

Length of the range in bytes.

return_metadata

boolean

query

False

If true, the request returns metadata for the the directory or file specified in the path.

  • Default value:

unix_permissions

integer

query

False

Filter by unix_permissions

inode_number

integer

query

False

Filter by inode_number

accessed_time

string

query

False

Filter by accessed_time

creation_time

string

query

False

Filter by creation_time

type

string

query

False

Filter by type

owner_id

integer

query

False

Filter by owner_id

name

string

query

False

Filter by name

volume.uuid

string

query

False

Filter by volume.uuid

volume.name

string

query

False

Filter by volume.name

target

string

query

False

Filter by target

hard_links_count

integer

query

False

Filter by hard_links_count

changed_time

string

query

False

Filter by changed_time

size

integer

query

False

Filter by size

bytes_used

integer

query

False

Filter by bytes_used

is_empty

boolean

query

False

Filter by is_empty

is_vm_aligned

boolean

query

False

Filter by is_vm_aligned

modified_time

string

query

False

Filter by modified_time

qos_policy.uuid

string

query

False

Filter by qos_policy.uuid

qos_policy.name

string

query

False

Filter by qos_policy.name

is_snapshot

boolean

query

False

Filter by is_snapshot

inode_generation

integer

query

False

Filter by inode_generation

path

string

query

False

Filter by path

group_id

integer

query

False

Filter by group_id

is_junction

boolean

query

False

Filter by is_junction

fields

array[string]

query

False

Specify the fields to return.

max_records

integer

query

False

Limit the number of records returned.

return_records

boolean

query

False

The default is true for GET calls. When set to false, only the number of records is returned.

  • Default value: 1

return_timeout

integer

query

False

The number of seconds to allow the call to execute before returning. When iterating over a collection, the default is 15 seconds. ONTAP returns earlier if either max records or the end of the collection is reached.

  • Default value: 1

order_by

array[string]

query

False

Order results by specified fields and optional [asc

Response

Status: 200, Ok
Name Type Description

_links

_links

num_records

integer

Number of records.

records

array[file_info]
Example response 
{
  "_links": {
    "next": {
      "href": "/api/resourcelink"
    },
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "records": {
    "_links": {
      "metadata": {
        "href": "/api/resourcelink"
      },
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "accessed_time": "2019-06-12 11:00:16 -0400",
    "bytes_used": 4096,
    "changed_time": "2019-06-12 11:00:16 -0400",
    "creation_time": "2019-06-12 11:00:16 -0400",
    "group_id": 30,
    "hard_links_count": 1,
    "inode_generation": 214753547,
    "inode_number": 1695,
    "is_empty": "",
    "is_junction": "",
    "is_snapshot": "",
    "is_vm_aligned": "",
    "modified_time": "2019-06-12 11:00:16 -0400",
    "name": "test_file",
    "owner_id": 54738,
    "path": "d1/d2/d3",
    "qos_policy": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "qos1",
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
    },
    "size": 200,
    "target": "some_directory/some_other_directory/some_file",
    "type": "file",
    "unix_permissions": 493,
    "volume": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "volume1",
      "uuid": "028baa66-41bd-11e9-81d5-00a0986138f7"
    }
  }
}

Error

Status: Default, Error
Name Type Description

error

error
Example error 
{
  "error": {
    "arguments": {
      "code": "string",
      "message": "string"
    },
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

next

href

self

href

_links

Name Type Description

metadata

href

self

href

_links

Name Type Description

self

href

qos_policy

The QoS policy for the file. Both traditional and adaptive QoS policies are supported. If both qos_policy.uuid and qos_policy.name properties are specified in the same request, they must refer to the same QoS policy. To remove the file from a QoS policy, set the property qos_policy.name in a PATCH request to an empty string "" or "none".

Note Files which are in use as a LUN cannot be assigned to a QoS policy, instead use PATCH on /storage/luns to assign a QoS policy for such files.

Note that a QoS policy can be set on a file, or a file's volume, but not on both.

Name Type Description

_links

_links

name

string

The name of the QoS policy. To remove the file from a QoS policy, set this property to an empty string "" or set it to "none" in a PATCH request.

uuid

string

The unique identifier of the QoS policy. Valid in PATCH.

volume

Name Type Description

_links

_links

name

string

The name of the volume.

uuid

string

Unique identifier for the volume. This corresponds to the instance-uuid that is exposed in the CLI and ONTAPI. It does not change due to a volume move.

  • example: 028baa66-41bd-11e9-81d5-00a0986138f7

file_info

Information about a single file.

Name Type Description

_links

_links

accessed_time

string

Last access time of the file in date-time format.

bytes_used

integer

The actual number of bytes used on disk by this file. If byte_offset and length parameters are specified, this will return the bytes used by the file within the given range.

changed_time

string

Last time data or attributes changed on the file in date-time format.

creation_time

string

Creation time of the file in date-time format.

group_id

integer

The integer ID of the group of the file owner.

hard_links_count

integer

The number of hard links to the file.

inode_generation

integer

Inode generation number.

inode_number

integer

The file inode number.

is_empty

boolean

Specifies whether or not a directory is empty. A directory is considered empty if it only contains entries for "." and "..". This element is present if the file is a directory. In some special error cases, such as when the volume goes offline or when the directory is moved while retrieving this info, this field might not get set.

is_junction

boolean

Returns "true" if the directory is a junction.

is_snapshot

boolean

Returns "true" if the directory is a Snapshot copy.

is_vm_aligned

boolean

Returns true if the file is vm-aligned. A vm-aligned file is a file that is initially padded with zero-filled data so that its actual data starts at an offset other than zero. The amount by which the start offset is adjusted depends on the vm-align setting of the hosting volume.

modified_time

string

Last data modification time of the file in date-time format.

name

string

Name of the file.

owner_id

integer

The integer ID of the file owner.

path

string

Path of the file.

qos_policy

qos_policy

The QoS policy for the file. Both traditional and adaptive QoS policies are supported. If both qos_policy.uuid and qos_policy.name properties are specified in the same request, they must refer to the same QoS policy. To remove the file from a QoS policy, set the property qos_policy.name in a PATCH request to an empty string "" or "none".

Note Files which are in use as a LUN cannot be assigned to a QoS policy, instead use PATCH on /storage/luns to assign a QoS policy for such files.

Note that a QoS policy can be set on a file, or a file's volume, but not on both.

size

integer

The size of the file, in bytes.

target

string

The relative or absolute path contained in a symlink, in the form /.

type

string

Type of the file.

unix_permissions

integer

UNIX permissions to be viewed as an octal number. It consists of 4 digits derived by adding up bits 4 (read), 2 (write), and 1 (execute). The first digit selects the set user ID(4), set group ID (2), and sticky (1) attributes. The second digit selects permissions for the owner of the file; the third selects permissions for other users in the same group; the fourth selects permissions for other users not in the group.

volume

volume

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

error

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

target

string

The target parameter that caused the error.