Help Center/ MapReduce Service/ API Reference/ API V2/ Cluster HDFS File API/ Obtaining the List of Files from a Specified Directory - ShowHdfsFileList
Updated on 2026-09-15 GMT+08:00

Obtaining the List of Files from a Specified Directory - ShowHdfsFileList

Function

This API is used to retrieve the file list information under a specified HDFS directory in an MRS cluster, including file names, sizes, permissions, and modification times, for browsing and inspecting data files in the cluster HDFS.

Constraints

None

Debugging

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

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependency

    mrs:cluster:listFiles

    List

    cluster *

    • g:ResourceTag/<tag-key>

    • g:EnterpriseProjectId

    • mrs:file:list

    -

URI

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

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

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

Constraints

N/A

Range

The value must consist of 1 to 64 characters. Only letters and digits are allowed.

Default Value

N/A

cluster_id

Yes

String

Definition

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

Constraints

N/A

Range

The value can contain 1 to 64 characters, including only letters, digits, underscores (_), and hyphens (-).

Default Value

N/A

Table 2 Query parameters

Parameter

Mandatory

Type

Description

path

Yes

String

Definition

File category. For example, to access the /tmp/test directory, the value must be a directory. The URI is /v2/{project_id}/clusters/{cluster_id}/files?path=%2Ftmp %2Ftest.

Constraints

N/A

Range

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.

Default Value

N/A

offset

No

String

Definition

Pagination parameter. The file list is queried from the offset.

Constraints

N/A

Range

Greater than or equal to 1.

Default Value

1

limit

No

String

Definition

Maximum number of records displayed on a page.

Constraints

N/A

Range

1~1000

Default Value

100

sort_key

No

String

Definition

Attribute used for sorting the list.

Constraints

N/A

Range

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

Default Value

path_suffix

order

No

String

Definition

List sorting method.

Constraints

N/A

Range

  • desc: descending order
  • asc: ascending order

Default Value

desc

Request Parameters

None

Response Parameters

Table 3 Response parameters

Parameter

Type

Description

total_count

Integer

Definition

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

Range

N/A

files

Array of FileStatusV2 objects

Definition

File list. For details, see Table 4.

Range

N/A

Table 4 FileStatus parameters

Parameter

Type

Description

path_suffix

String

Definition

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.

Range

N/A

owner

String

Definition

File owner.

Range

N/A

group

String

Definition

File owner group.

Range

N/A

permission

String

Definition

Permission information.

Range

N/A

replication

Integer

Definition

Number of replicas.

Range

N/A

block_size

Integer

Definition

Size of a file storage block, in bytes.

Range

N/A

length

Integer

Definition

Actual length of the file, in bytes.

Range

N/A

type

String

Definition

File type

Range

  • FILE: file
  • DIRECTORY: directory

children_num

Integer

Definition

Number of files in the directory.

Range

N/A

access_time

Long

Definition

File access time, in Unix timestamp format (milliseconds).

Range

N/A

modification_time

Long

Definition

File modification time, in Unix timestamp format (milliseconds).

Range

N/A

Example Request

Obtain the list of files from a specified directory.

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"
        }
    ]
}

SDK Sample Code

The SDK sample code is as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.mrs.v2.region.MrsRegion;
import com.huaweicloud.sdk.mrs.v2.*;
import com.huaweicloud.sdk.mrs.v2.model.*;


public class ShowHdfsFileListSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        MrsClient client = MrsClient.newBuilder()
                .withCredential(auth)
                .withRegion(MrsRegion.valueOf("<YOUR REGION>"))
                .build();
        ShowHdfsFileListRequest request = new ShowHdfsFileListRequest();
        request.withClusterId("{cluster_id}");
        try {
            ShowHdfsFileListResponse response = client.showHdfsFileList(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkmrs.v2.region.mrs_region import MrsRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkmrs.v2 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = MrsClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(MrsRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ShowHdfsFileListRequest()
        request.cluster_id = "{cluster_id}"
        response = client.show_hdfs_file_list(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    mrs "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := mrs.MrsClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := mrs.NewMrsClient(hcClient)

    request := &model.ShowHdfsFileListRequest{}
	request.ClusterId = "{cluster_id}"
	response, err := client.ShowHdfsFileList(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

See Status Codes.

Error Codes

See Error Codes.