List Guest Filesystem Files
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.
if you do not have all of the privileges described as follows: - The resource VirtualMachine referenced by the parameter vm requires VirtualMachine.GuestOperations.Query.
Request
URLURL
https://{api_host}/api/vcenter/vm/{vm}/guest/filesystem/files?action=list
Path Parameters
Path Parameters
string
vm
Required
Virtual Machine to perform the operation on. The parameter must be an identifier for the resource type: VirtualMachine.
Header Parameters
Header Parameters
string
vmware-api-session-id
Required
Required session ID, acquired from Create Session API under CIS product
vmware-api-session-id example
"b00db39f948d13ea1e59b4d6fce56389"
Request Body
Request Body
VmGuestFilesystemFilesListRequestBody of mimetype application/json
Required
This is a request body class for an operation.
(The request body parameter is missing description)
{
"credentials": {
"interactive_session": false,
"type": "USERNAME_PASSWORD"
},
"path": "string"
}
string
path
Required
The complete path to the directory or file to query.
filter
Optional
Specification to match files for which information should be returned. If unset, the behavior is the equivalent to a Files.FilterSpec with all fields unset which means all filenames match the filter.
iteration
Optional
The specification of a page of results to be retrieved. If unset, the first page will be retrieved.
Authentication
This operation uses the following authentication methods.
Response
Response
Response BodyResponse Body
200 OK returns
VmGuestFilesystemFilesListResult
of type application/json
A Files.ListResult object containing information for all the matching files in filter and the total number of files that can be returned.
{
"end_index": 0,
"files": [
{
"filename": "string",
"size": 0,
"type": "FILE"
}
],
"start_index": 0,
"status": "READY",
"total": 0
}
array of
VmGuestFilesystemFilesSummary
files
Required
A list of Files.Summary structures containing information for all the matching files.
status
Required
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.
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.
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.
Possible values are: READY , END_OF_DATA
integer
total
Required
The total number of results from the Files.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.
integer
end_index
Optional
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. If unset no items were returned.
integer
start_index
Optional
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. If unset no items were returned.
Errors
400
com.vmware.vapi.std.errors.invalid_argument : if path is too long. The value of com.vmware.vapi.std.errors.Error#data will contain all the fields defined in the FileErrorDetails providing additional information about the failure. If {@param.iteration} contains invalid data. If filter contains an invalid regular expression. | com.vmware.vapi.std.errors.not_allowed_in_current_state : if the virtual machine is not running. | com.vmware.vapi.std.errors.unsupported : if the operation is not supported by the VMware Tools in the guest operating system. if the operation is disabled by the VMware Tools in the guest operating system.
403
com.vmware.vapi.std.errors.unauthorized : if path cannot be accessed. if path cannot be listed because the guest authentication will not allow the operation.
404
com.vmware.vapi.std.errors.not_found : if the virtual machine is not found. if path is not found. The value of com.vmware.vapi.std.errors.Error#data will contain all the fields defined in the FileErrorDetails providing additional information about the failure.
default
‘Default’ means this response is used for all HTTP codes that are not covered individually for this operation.
Code Samples
PowerCLI Client SDK Example
$VmGuestCredentials = Initialize-VmGuestCredentials -InteractiveSession $false -Type "USERNAME_PASSWORD"
$VmGuestFilesystemFilesListRequestBody = Initialize-VmGuestFilesystemFilesListRequestBody -Credentials $VmGuestCredentials -Path "MyPath"
Invoke-ListVmFilesystemFiles -Vm "MyVm" -VmGuestFilesystemFilesListRequestBody $VmGuestFilesystemFilesListRequestBody
PowerCLI Client SDK All Parameters Example
$VmGuestCredentials = Initialize-VmGuestCredentials -InteractiveSession $false -Type "USERNAME_PASSWORD" -UserName "MyUserName" -Password "MyPassword" -SamlToken "MySamlToken"
$VmGuestFilesystemFilesIterationSpec = Initialize-VmGuestFilesystemFilesIterationSpec -Size 0 -Index 0
$VmGuestFilesystemFilesFilterSpec = Initialize-VmGuestFilesystemFilesFilterSpec -MatchPattern "MyMatchPattern"
$VmGuestFilesystemFilesListRequestBody = Initialize-VmGuestFilesystemFilesListRequestBody -Credentials $VmGuestCredentials -Path "MyPath" -Iteration $VmGuestFilesystemFilesIterationSpec -VarFilter $VmGuestFilesystemFilesFilterSpec
Invoke-ListVmFilesystemFiles -Vm "MyVm" -VmGuestFilesystemFilesListRequestBody $VmGuestFilesystemFilesListRequestBody
cURL Command
curl -X POST -H "vmware-api-session-id: b00db39f948d13ea1e59b4d6fce56389" -H "Content-Type: application/json" -d '{"credentials":{"interactive_session":false,"password":"string","saml_token":"string","type":"USERNAME_PASSWORD","user_name":"string"},"filter":{"match_pattern":"string"},"iteration":{"index":0,"size":0},"path":"string"}' https://{api_host}/api/vcenter/vm/{vm}/guest/filesystem/files?action=list
Vendor Extensions
This operation contains the following vendor extensions defined in the spec:
x-vmw-doc-operation: list
Availability
Added in 7.0.2.0
