REST API - put

vcenter vm guest filesystem transfers: put

Initiates an operation to transfer a file to the guest.

Obtains a URL to the file inside the guest to be transferred from the client. The user should send a HTTP PUT request specifying the file content in the body of the request. Multiple PUT request cannot be sent to the URL simultaneously. URL will be invalidated after a successful PUT request is sent. 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.

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

. 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

PUT https://{server}/api/vcenter/vm/{vm}/guest/filesystem

{
    "path" : "string",
    "credentials" : {
        "password" : "secret string",
        "user_name" : "string",
        "saml_token" : "secret string",
        "type" : "USERNAME_PASSWORD",
        "interactive_session" : true
    },
    "file_attributes" : {
        "last_accessed" : "2015-01-01T22:13:05.651Z",
        "windows" : {
            "hidden" : true,
            "read_only" : true
        },
        "last_modified" : "2015-01-01T22:13:05.651Z",
        "posix" : {
            "group_id" : 1,
            "owner_id" : 1,
            "permissions" : "string"
        }
    },
    "overwrite" : true,
    "file_size" : 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 credentials.
-.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 destination path in the guest to transfer the file from the client. It cannot be a path to a directory or a symbolic link.
-.file_attributes	file_attributes_create_spec	Optional. File attributes of the file that has to be created in the guest. See vcenter.vm.guest.filesystem.transfers.file_attributes_create_spec. If any file attribute is not specified, then the default value of that field will be set for the file.
-.file_attributes.last_modified	date_time	The date and time the file was last modified. If this property is not specified the default value will be the time when the file is created inside the guest. 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. Set if a specific modification time is desired.
-.file_attributes.last_accessed	date_time	The date and time the file was last accessed. If this property is not specified the default value will be the time when the file is created inside the guest. 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. Set if a specific access time is desired.
-.file_attributes.windows	windows_file_attributes_create_spec	Windows-specific file creation information. 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. Sgoud be set if the guest operating system is Windows.
-.file_attributes.windows.hidden	boolean	The file is hidden. 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.
-.file_attributes.windows.read_only	boolean	The file is read-only. 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.
-.file_attributes.posix	posix_file_attributes_create_spec	Posix-specific file creation information. 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. Sgoud be set if the guest operating system is Posix-based.
-.file_attributes.posix.owner_id	long	The owner ID. If this property is not specified when passing a vcenter.vm.guest.filesystem.transfers.posix_file_attributes_create_spec object to put, the default value will be the owner Id of the user who invoked the file transfer operation. 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. Defaults to uid of user invoking the operation.
-.file_attributes.posix.group_id	long	The group ID. If this property is not specified when passing a vcenter.vm.guest.filesystem.transfers.posix_file_attributes_create_spec object to put, the default value will be the group Id of the user who invoked the file transfer operation. 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. Defaults to gid of user invoking the operation.
-.file_attributes.posix.permissions	string	The file permissions in chmod(2) format. If this property is not specified when passing a vcenter.vm.guest.filesystem.transfers.posix_file_attributes_create_spec object to put, the file will be created with 0644 permissions. This field is interpreted as octal. XXX expand on this with a description of what the numbers mean. 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. Defaults to 0644.
-.file_size	long	Size of the file to transfer to the guest in bytes. This specifies how many bytes are read; any extra are ignored. XXX need to call out what happens (if anythng) if the size is too big to fit. Appears to be no check.
-.overwrite	boolean	Optional. If true, the destination file is clobbered.

Response:

HTTP Status Code: 200

Response Body Structure:

"http://myurl.com"

Headers:

None

Type:

Name	Type	Description
bold = required
-	URI	A URL to which the user has to send a PUT request. 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 can be uploaded to 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. The URL is valid only for 10 minutes from the time it is generated. Also, the URL becomes invalid whenever the virtual machine is powered off, suspended or unregistered.

Errors:

HTTP Status Code	Type	Description
400	already_exists	if `path` exists and `overwrite` is false. XXX verify this
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.
500	unable_to_allocate_resource	if is insuffcient space for a new file of `file_size`.
401	unauthenticated	if the `credentials` object was not valid.
403	unauthorized	if `path` cannot be accessed.
400	unsupported	if the operation is not supported by the VMware Tools in the guest OS.