Listing Objects

Updated on 2024-12-03 GMT+08:00

View PDF

NOTICE:

If you have any questions during development, post them on the Issues page of GitHub.

You can call list_bucket_objects to list objects in a bucket.

Parameter Description

Field	Type	Mandatory or Optional	Description
option	The context of the bucket. For details, see Configuring option.	Mandatory	Bucket parameter
prefix	char *	Optional	Name prefix that the objects to be listed must contain
marker	char *	Optional	Object name to start with when listing objects in a bucket. All objects are listed in the lexicographical order
delimiter	char *	Optional	Character used to group object names. If the object name contains the delimiter parameter, the character string from the first character to the first delimiter in the object name is grouped under a single result element, commonPrefix. (If a prefix is specified in the request, the prefix must be removed from the object name.) For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, and subdirectories are also listed. In big data scenarios, parallel file systems usually have deep directory levels and each directory has a large number of files. In such case, you are advised to configure [delimiter="/"] to list the content in the current directory, but not list subdirectories, thereby improving the listing efficiency.
maxkeys	int	Mandatory	Maximum number of objects listed in the response body. The value ranges from 1 to 1000. If the value is not in this range, 1000 objects are returned by default.
handler	obs_list_objects_handler *	Mandatory	Callback function
callback_data	void *	Optional	Callback data

Sample Code

static void test_list_bucket_objects(char *bucket_name)
{
    // Create and initialize option.
    obs_options option;
    init_obs_options(&option);
    option.bucket_options.host_name = "<your-endpoint>";
    option.bucket_options.bucket_name = "<Your bucketname>";

    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables ACCESS_KEY_ID and SECRET_ACCESS_KEY.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
    option.bucket_options.access_key = getenv("ACCESS_KEY_ID");
    option.bucket_options.secret_access_key = getenv("SECRET_ACCESS_KEY");

    // Set response callback function.
    obs_list_objects_handler list_bucket_objects_handler =
    {
        { &response_properties_callback, &listobjects_complete_callback },
        &list_objects_callback
    };
    
    // Customize callback data.
    list_bucket_callback_data data;
    memset(&data, 0, sizeof(list_bucket_callback_data)); 
    // List objects.
    list_bucket_objects(&option, "<prefix>", "<marker>", "<delimiter>", "<maxkeys>", &list_bucket_objects_handler, &data); 
    if (OBS_STATUS_OK == data.ret_status) {
        printf("list bucket objects successfully. \n");
    }
    else
    {
        printf("list bucket objects failed(%s).\n", 
        obs_get_status_name(data.ret_status));
    }
}

NOTE:

Information of a maximum of 1000 objects can be listed each time. If a bucket contains more than 1000 objects and list_objects_data.is_truncated is true in the returned result, not all objects are returned. In such cases, you can use list_objects_data.next_marker to obtain the start position for next listing.
To obtain all objects, you can list them in paging mode.

Parent topic: Object Management

Previous topic: Managing Object ACLs

Next topic: Deleting Objects