REST API - list

vcenter vm guest filesystem files: list

Returns information about files and directories in the guest.

Files are returned in operating system-specific (inode) order. If the directory is modified between queries, missing or duplicate results can occur.

. Warning: This operation is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Request:

HTTP request

POST https://{server}/api/vcenter/vm/{vm}/guest/filesystem/files

?action=list

{
    "filter" : {
        "match_pattern" : "string"
    },
    "path" : "string",
    "credentials" : {
        "password" : "secret string",
        "user_name" : "string",
        "saml_token" : "secret string",
        "type" : "USERNAME_PASSWORD",
        "interactive_session" : true
    },
    "iteration" : {
        "size" : 1,
        "index" : 1
    }
}

Path Parameters

Name	Type	Description
Required
vm	string	Virtual Machine to perform the operation on.

Body Parameters:

Name	Type	Description
bold = required
-.credentials	credentials	The guest authentication data.
-.credentials.interactive_session	boolean	If set, the operation will interact with the logged-in desktop session in the guest. This requires that the logged-on user matches the user specified by the vcenter.vm.guest.credentials. This is currently only supported for USERNAME_PASSWORD. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
-.credentials.type	string	The guest credentials type. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Types of guest credentials. Warning: This enumeration is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Value is one of: USERNAME_PASSWORD: USERNAME_PASSWORD credentials contains the information necessary to authenticate within a guest using a username and password. This method of authentication is stateless. To use USERNAME_PASSWORD, populate userName and password with the appropriate login information. Once populated, you can use USERNAME_PASSWORD in any guest operations function call. . Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. SAML_BEARER_TOKEN: SAML_BEARER_TOKEN contains the information necessary to authenticate within a guest using a SAML token. SAML Bearer token credentials relies on a guest alias that associates a guest account with the subject and certificate encoded in a SAML Bearer token obtained from the VMware SSO Server. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
-.credentials.user_name	string	For SAML_BEARER_TOKEN, this is the guest user to be associated with the credentials. For USERNAME_PASSWORD this is the guest username. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. It is only relevant when type has value [USERNAME_PASSWORD, SAML_BEARER_TOKEN]. If no user is specified for SAML_BEARER_TOKEN, a guest dependent mapping will decide what guest user account is applied.
-.credentials.password	secret	password. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. It is only relevant when type has value USERNAME_PASSWORD. This field is optional and it is only relevant when the value of `type` is USERNAME_PASSWORD.
-.credentials.saml_token	secret	SAML Bearer Token. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. It is only relevant when type has value SAML_BEARER_TOKEN. This field is optional and it is only relevant when the value of `type` is SAML_BEARER_TOKEN.
-.path	string	The complete path to the directory or file to query.
-.iteration	iteration_spec	Optional. The specification of a page of results to be retrieved.
-.iteration.size	long	Specifies the maximum number of results to return. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If unset information about at most 50 files will be returned.
-.iteration.index	long	Which result to start the list with. If this value exceeds the number of results, an empty list will be returned. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If unset, the start of the list of files will be returned.
-.filter	filter_spec	Optional. Specification to match files for which information should be returned.
-.filter.match_pattern	string	The perl-compatible regular expression used to filter the returned files. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If unset the pattern *'.'** (match everything) is used.

Response:

HTTP Status Code: 200

Response Body Structure:

{
    "total" : 1,
    "start_index" : 1,
    "files" : [
        {
            "filename" : "string",
            "size" : 1,
            "type" : "FILE"
        },
        {
            "filename" : "string",
            "size" : 1,
            "type" : "FILE"
        }
    ],
    "end_index" : 1,
    "status" : "READY"
}

Headers:

None

Type:

Name	Type	Description
bold = required
-	list_result	A vcenter.vm.guest.filesystem.files.list_result object containing information for all the matching files in `filter` and the total number of files that can be returned.
-.files	summary[]	A list of vcenter.vm.guest.filesystem.files.summary structures containing information for all the matching files. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
-.files[].filename	string	The name of the file. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
-.files[].type	string	The type of file. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Defines the valid types of files. Warning: This enumeration is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Value is one of: FILE: normal file. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. DIRECTORY: directory. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. SYMLINK: symbolic link. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
-.files[].size	long	The file size in bytes. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
-.total	long	The total number of results from the list. This is a hint to the user of the iterator regarding how many items are available to be retrieved. The total could change if the inventory of items are being changed. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.
-.start_index	long	Positional index into the logical item list of the first item returned in the list of results. The first item in the logical item list has an index of 0. This is a hint to the user of the iterator regarding the logical position in the iteration. For example, this can be used to display to the user which page of the iteration is being shown. The total could change if the inventory of items are being changed. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If unset no items were returned.
-.end_index	long	Positional index into the logical item list of the last item returned in the list of results. The first item in the logical item list has an index of 0. This is a hint to the user of the iterator regarding the logical position in the iteration. For example, this can be used to display to the user which page of the iteration is being shown. The total could change if the inventory of items are being changed. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Optional. If unset no items were returned.
-.status	string	The last status for the iterator that indicates whether any more results can be expected if the caller continues to make requests for more data using the iterator. Warning: This attribute is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. The last status for the iterator. A field of this type is returned as part of the result and indicates to the caller of the API whether it can continue to make requests for more data. The last status only reports on the state of the iteration at the time data was last returned. As a result, it not does guarantee if the next call will succeed in getting more data or not. Failures to retrieve results will be returned as Error responses. These last statuses are only returned when the iterator is operating as expected. Warning: This enumeration is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. Value is one of: READY: Iterator has more data pending and is ready to provide it. The caller can request the next page of data at any time. The number of results returned may be less than the requested size. In other words, the iterator may not fill the page. The iterator has returned at least 1 result. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented. END_OF_DATA: Iterator has finished iterating through its inventory. There are currently no more entities to return and the caller can terminate iteration. If the iterator returned some data, the marker may be set to allow the iterator to continue from where it left off when additional data does become available. This value is used to indicate that all available data has been returned by the iterator. Warning: This constant is part of a new feature in development. It may be changed at any time and may not have all supported functionality implemented.

Errors:

HTTP Status Code	Type	Description
400	invalid_argument	if `path` is too long. XXX standard enhanced error link XXX
400	not_allowed_in_current_state	if the virtual machine is not running.
404	not_found	if the virtual machine is not found.
500	resource_busy	if the virtual machine is busy.
503	service_unavailable	if the VMware Tools is not running.
403	unauthorized	if `path` cannot be accessed.
401	unauthenticated	if the `credentials` object was not valid.
400	unsupported	if the operation is not supported by the VMware Tools in the guest operating system.