Help Center> MapReduce Service> API Reference> API V2> Cluster HDFS File API> Obtaining the List of Files from a Specified Directory
Updated on 2023-10-24 GMT+08:00

Obtaining the List of Files from a Specified Directory

Function

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

Constraints

None

Debugging

You can debug this API in API Explorer. Automatic authentication is supported. API Explorer can automatically generate sample SDK code and provide the sample SDK code debugging.

URI

GET /v2/{project_id}/clusters/{cluster_id}/files
Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

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

cluster_id

Yes

String

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

path

Yes

String

The file directory. For example, to access the /tmp/test directory list, the value 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:

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

offset

No

String

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

limit

No

String

The 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

String

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

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

order

No

String

The list sorting mode. Possible values:

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

The default value is desc.

Request Parameters

None

Response Parameters

Table 2 Response parameters

Parameter

Type

Description

total_count

Integer

The total number of files, which is irrelevant to pagination.

files

Array of FileStatusV2 objects

The file list. For details, see Table 3.

Table 3 FileStatus parameters

Parameter

Type

Description

path_suffix

String

The 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

The file owner.

group

String

The file owner group.

permission

String

The permission information.

replication

Integer

The number of replicas.

block_size

Integer

The block size.

length

Integer

The file length.

type

String

The file type. Possible values:

  • FILE: file
  • DIRECTORY: directory

children_num

Integer

The number of files in the directory.

access_time

Long

The file access time.

modification_time

Long

The file modification time.

Example Request

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

Example Response

Status code: 200

Obtaining the file list of a specified directory is successful.
{
    "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 Codes

See Status Codes.

Error Codes

See Error Codes.