Create Guest Filesystem Transfers
Initiates an operation to transfer a file to or from the guest. If the power state of the Virtual Machine is changed when the file transfer is in progress, or the Virtual Machine is migrated, then the transfer operation is aborted.
When transferring a file into the guest and overwriting an existing file, the old file attributes are not preserved.
In order to ensure a secure connection to the host when transferring a file using HTTPS, the X.509 certificate for the host must be used to authenticate the remote end of the connection. The certificate of the host that the virtual machine is running on can be retrieved using the following fields: XXX insert link to certificate in Host config XXX
if you do not have all of the privileges described as follows: - The resource VirtualMachine referenced by the parameter vm requires VirtualMachine.GuestOperations.Modify.
Request
URLURL
https://{api_host}/api/vcenter/vm/{vm}/guest/filesystem?action=create
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
VmGuestFilesystemTransfersCreateRequestBody 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"
},
"spec": {
"path": "string"
}
}
spec
Required
A specification of the type of file transfer and any applicable attibutes.
Authentication
This operation uses the following authentication methods.
Response
Response
Response BodyResponse Body
201 Created returns
string
formatted as uri
of type application/json
The URL to which the user has to send an HTTP request. The URL will become invalid once a successful request is sent. If the file is being transferred from the guest, an HTTP GET should be used. If the file is being transferred to the guest, HTTP PUT should be used. The URL is valid only for 10 minutes from the time it is generated. The URL becomes invalid whenever the virtual machine is powered off, suspended, unregistered or migrated to a new host. The host part of the URL is returned as * if the hostname to be used is the name of the server to which the call was made. For example, if the call is made to esx-svr-1.domain1.com, and the file is available for download from https://esx-svr-1.domain1.com/guestFile?id=1&token=1234, the URL returned may be {@literal aHR0cHM6Ly8mIzQyOy9ndWVzdEZpbGU/aWQ9MSZ0b2tlbj0xMjM0}. The client replaces the asterisk with the server name on which it invoked the call.
Errors
400
com.vmware.vapi.std.errors.already_exists : if Transfers.CreateSpec.path in spec exists and Transfers.FileCreationAttributes.overwrite is false when transferring a file to the guest. | com.vmware.vapi.std.errors.invalid_argument : if Transfers.CreateSpec.path in spec is not a file. 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 Transfers.CreateSpec.path in spec 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. | 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 OS. if the operation is disabled by the VMware Tools in the guest OS.
403
com.vmware.vapi.std.errors.unauthorized : if Transfers.CreateSpec.path in spec cannot be accessed. if Transfers.CreateSpec.path in spec cannot be copied 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 Transfers.CreateSpec.path in spec 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.
500
com.vmware.vapi.std.errors.resource_busy : if the virtual machine is busy. | com.vmware.vapi.std.errors.unable_to_allocate_resource : if is insuffcient space for the new file when transferring a file to the guest.
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"
$VmGuestFilesystemTransfersCreateSpec = Initialize-VmGuestFilesystemTransfersCreateSpec -Path "MyPath"
$VmGuestFilesystemTransfersCreateRequestBody = Initialize-VmGuestFilesystemTransfersCreateRequestBody -Credentials $VmGuestCredentials -Spec $VmGuestFilesystemTransfersCreateSpec
Invoke-CreateVmGuestFilesystem -Vm "MyVm" -VmGuestFilesystemTransfersCreateRequestBody $VmGuestFilesystemTransfersCreateRequestBody
PowerCLI Client SDK All Parameters Example
$VmGuestCredentials = Initialize-VmGuestCredentials -InteractiveSession $false -Type "USERNAME_PASSWORD" -UserName "MyUserName" -Password "MyPassword" -SamlToken "MySamlToken"
$VmGuestFilesystemTransfersWindowsFileAttributesCreateSpec = Initialize-VmGuestFilesystemTransfersWindowsFileAttributesCreateSpec -Hidden $false -ReadOnly $false
$VmGuestFilesystemTransfersPosixFileAttributesCreateSpec = Initialize-VmGuestFilesystemTransfersPosixFileAttributesCreateSpec -OwnerId 0 -GroupId 0 -Permissions "MyPermissions"
$VmGuestFilesystemTransfersFileCreationAttributes = Initialize-VmGuestFilesystemTransfersFileCreationAttributes -Size 0 -Overwrite $false -LastModified (Get-Date) -LastAccessed (Get-Date) -Windows $VmGuestFilesystemTransfersWindowsFileAttributesCreateSpec -Posix $VmGuestFilesystemTransfersPosixFileAttributesCreateSpec
$VmGuestFilesystemTransfersCreateSpec = Initialize-VmGuestFilesystemTransfersCreateSpec -Path "MyPath" -Attributes $VmGuestFilesystemTransfersFileCreationAttributes
$VmGuestFilesystemTransfersCreateRequestBody = Initialize-VmGuestFilesystemTransfersCreateRequestBody -Credentials $VmGuestCredentials -Spec $VmGuestFilesystemTransfersCreateSpec
Invoke-CreateVmGuestFilesystem -Vm "MyVm" -VmGuestFilesystemTransfersCreateRequestBody $VmGuestFilesystemTransfersCreateRequestBody
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"},"spec":{"attributes":{"last_accessed":"string","last_modified":"string","overwrite":false,"posix":{"group_id":0,"owner_id":0,"permissions":"string"},"size":0,"windows":{"hidden":false,"read_only":false}},"path":"string"}}' https://{api_host}/api/vcenter/vm/{vm}/guest/filesystem?action=create
Vendor Extensions
This operation contains the following vendor extensions defined in the spec:
x-vmw-doc-operation: create
Availability
Added in 7.0.2.0
