Help Center/ MapReduce Service/ API Reference (ME-Abu Dhabi Region)/ API V2/ Cluster HDFS File API/ Obtaining the List of Files from a Specified Directory
Updated on 2022-12-14 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.

URI

  • Format

    GET /v2/{project_id}/clusters/{cluster_id}/files

  • Parameter description
    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:

    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

    String

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

    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

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

  • Example request
    GET /v2/{project_id}/clusters/{cluster_id}/files?path={directory}&offset={offset}&limit={limit}&sort_key={sort_key}&order={order}
  • 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 Codes

See Status Codes.

Error Codes

See Error Codes.