Updated on 2022-12-08 GMT+08:00

Obtaining Files from a Specified Directory

Function

This API is used to obtain the list of files from a specified directory in an MRS cluster.

URI

  • Format

    GET /v2/{project_id}/clusters/{cluster_id}/files?path={directory}&offset={offset}&limit={limit}&sort_key={sort_key}&order={order}

  • URI parameter description
    Table 1 URI parameter description

    Parameter

    Mandatory

    Description

    project_id

    Yes

    Project ID. For details on how to obtain the project ID, see Obtaining a Project ID.

    cluster_id

    Yes

    Cluster ID For details on how to obtain the cluster ID, see Obtaining a Cluster ID.

    path

    Yes

    File directory. For example, to access the /tmp/test directory list, the directory must be a directory. The overall URI is as follows:

    /v2/{project_id}/clusters/{cluster_id}/files?path=%2Ftmp%2Ftest

    A single-level directory must comply with the following rules:

    1. The directory path cannot be left blank.
    2. The value cannot start or end with a period (.).
    3. The value cannot contain the following characters: /:*?"<>|\;&,'`!{}[]$%+
    4. The value cannot exceed 255 characters.

    offset

    No

    Pagination parameter. The file list is queried from the offset. The default value is 0.

    limit

    No

    Pagination parameter, indicating the maximum number of records on a page. The default value is 100 and the maximum value is 1000.

    sort_key

    No

    The list is sorted by this attribute. The following attributes are supported:

    • path_suffix: file or directory name
    • length: file size
    • modification_time: modification time

    The default value is path_suffix, indicating that files or directories are sorted by file or directory name.

    order

    No

    List sorting mode:

    • desc: Files are displayed in the descending order.
    • asc: Files are displayed in ascending order.

    The default value is desc.

Request

Request parameters

None.

Response

Table 2 Response parameter description

Parameter

Type

Description

total_count

Integer

Total number of files, which is irrelevant to pagination.

files

Array of FileStatus

File list. For details, see Table 3.

Table 3 FileStatus description

Parameter

Type

Description

path_suffix

String

File name extension in the current directory. For example, if you obtain the /tmp/test file in the /tmp directory, the value of path_suffix is test.

owner

String

File owner.

group

String

File owner group.

permission

String

Permission information.

replication

Integer

Number of replicas.

block_size

Integer

Block size.

length

Integer

File length.

type

String

The following file types are supported:

  • FILE: file
  • DIRECTORY: directory

children_num

Integer

Number of files in the directory.

access_time

Long

File access time.

modification_time

Long

File modification time

Example

  • Example request

    None.

  • Example response
    • Example of a successful response
      {
          "total_count": 2,
          "files": [
              {
                  "access_time": 0,
                  "block_size": 0,
                  "children_num": 0,
                  "group": "hadoop",
                  "length": 0,
                  "modification_time": 1587179516623,
                  "owner": "hdfs",
                  "path_suffix": "app-logs",
                  "permission": "777",
                  "replication": 0,
                  "type": "DIRECTORY"
              },
              {
                  "access_time": 1587267212761,
                  "block_size": 134217728,
                  "children_num": 0,
                  "group": "hadoop",
                  "length": 23666188,
                  "modification_time": 1587222156003,
                  "owner": "root",
                  "path_suffix": "data-m-00000",
                  "permission": "644",
                  "replication": 3,
                  "type": "FILE"
              }
          ]
      }
      

Status Code

For details about status codes, see Status Codes.