This API has a deprecated equivalent from v7.0U1.
Add Item Updatesession File
Requests file content to be changed (either created, or updated). Depending on the source type of the file, this operation will either return an upload endpoint where the client can push the content, or the server will pull from the provided source endpoint. If a file with the same name already exists in this session, this operation will be used to update the content of the existing file. When importing a file directly from storage, where the source endpoint is a file or datastore URI, you will need to have the ContentLibrary.ReadStorage privilege on the library item. If the file is located in the same directory as the library storage backing folder, the server will move the file instead of copying it, thereby allowing instantaneous import of files for efficient backup and restore scenarios. In all other cases, a copy is performed rather than a move.
if you do not have all of the privileges described as follows: - Operation execution requires System.Anonymous.
Request
URLURL
https://{api_host}/api/content/library/item/update-session/{update_session_id}/file
Path Parameters
Path Parameters
string
update_session_id
Required
Identifier of the update session to be modified. The parameter must be an identifier for the resource type: com.vmware.content.library.item.UpdateSession.
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
LibraryItemUpdatesessionFileAddSpec of mimetype application/json
Required
Specification for the file that needs to be added or updated. This includes whether the client wants to push the content or have the server pull it.
{
"name": "string",
"source_type": "NONE"
}
string
name
Required
The name of the file being uploaded.
source_type
Required
The File.SourceType enumerated type defines how the file content is retrieved.
NONE : No source type has been requested.
PUSH : The client is uploading content using HTTP(S) PUT requests.
PULL : The server is pulling content from a URL. The URL scheme can be http, https, file, or ds.
Possible values are: NONE , PUSH , PULL
checksum_info
Optional
The checksum of the file. If specified, the server will verify the checksum once the file is received. If there is a mismatch, the upload will fail. For ova files, this value should not be set. If unset, the server will not verify the checksum.
integer
size
Optional
The file size, in bytes. If unset, the server will not verify it received the correct size.
source_endpoint
Optional
Location from which the Content Library Service will fetch the file, rather than requiring a client to upload the file. This field is optional and it is only relevant when the value of File.AddSpec.source-type is PULL.
Authentication
This operation uses the following authentication methods.
Response
Response
Response BodyResponse Body
201 Created returns
LibraryItemUpdatesessionFileInfo
of type application/json
An File.Info structure containing upload links as well as server side state tracking the transfer of the file.
{
"bytes_transferred": 0,
"checksum_info": {
"algorithm": "SHA1",
"checksum": "string"
},
"error_message": {
"args": [
"string"
],
"default_message": "string",
"id": "string",
"localized": "string",
"params": {
"key": {
"d": 0,
"dt": "string",
"format": "SHORT_DATE",
"i": 0,
"l": {
"id": "string",
"params": "StdLocalizationParam Object"
},
"precision": 0,
"s": "string"
}
}
},
"keep_in_storage": false,
"name": "string",
"size": 0,
"source_endpoint": {
"ssl_certificate_thumbprint": "string",
"uri": "string"
},
"source_type": "NONE",
"status": "WAITING_FOR_TRANSFER",
"upload_endpoint": {
"ssl_certificate_thumbprint": "string",
"uri": "string"
}
}
integer
bytes_transferred
Required
The number of bytes of this file that have been received by the server.
source_type
Required
The File.SourceType enumerated type defines how the file content is retrieved.
NONE : No source type has been requested.
PUSH : The client is uploading content using HTTP(S) PUT requests.
PULL : The server is pulling content from a URL. The URL scheme can be http, https, file, or ds.
Possible values are: NONE , PUSH , PULL
status
Required
The TransferStatus enumerated type defines the transfer state of a file.
WAITING_FOR_TRANSFER : Indicates that a file has been defined for a library item and its content needs to be uploaded.
TRANSFERRING : Indicates that data is being transferred to the file.
READY : Indicates that the file has been fully transferred and is ready to be used.
VALIDATING : Indicates that the file is being validated (checksum, type adapters).
ERROR : Indicates that there was an error transferring or validating the file.
Possible values are: WAITING_FOR_TRANSFER , TRANSFERRING , READY , VALIDATING , ERROR
string
name
Required
The name of the file.
boolean
keep_in_storage
Optional
Whether or not the file will be kept in storage upon update session completion. The flag is true for most files, and false for metadata files such as manifest and certificate file of update session with library item type OVF. Any file with File.Info.keep-in-storage set to false will not show up in the list of files returned from File.list upon update session completion. If unset, the file will be kept in storage upon update session completion.
integer
size
Optional
The file size, in bytes as received by the server. This field is guaranteed to be set when the server has completely received the file. This field won’t be set until the file status is READY.
source_endpoint
Optional
A source endpoint from which to retrieve the file. This field is optional and it is only relevant when the value of File.Info.source-type is PULL.
checksum_info
Optional
The checksum information of the file received by the server. If unset, the server does not verify the checksum.
error_message
Optional
Details about the transfer error. An error message is set if the status is ERROR.
upload_endpoint
Optional
An upload endpoint to which the client can push the content. This field is optional and it is only relevant when the value of File.Info.source-type is PUSH.
Errors
400
com.vmware.vapi.std.errors.invalid_argument : if the fileSpec is invalid. | com.vmware.vapi.std.errors.not_allowed_in_current_state : if the content of the library item associated with the update session has been deleted from the storage backings (see LibraryModel#storageBackings) associated with it. if metadata files such as manifest and certificate file are added after the OVF descriptor file. This is applicable to update sessions with library item type OVF only. This error was added in vSphere 6.8.0.
403
com.vmware.vapi.std.errors.unauthorized : if the caller doesn’t have ContentLibrary.ReadStorage privilege on the library item of the update session and source type PULL is requested for a file or datastore source endpoint (that is, not HTTP or HTTPs based endpoint).
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
$LibraryItemUpdatesessionFileAddSpec = Initialize-LibraryItemUpdatesessionFileAddSpec -Name "MyName" -SourceType "NONE"
Invoke-CreateUpdateSessionIdItemFile -UpdateSessionId "MyUpdateSessionId" -LibraryItemUpdatesessionFileAddSpec $LibraryItemUpdatesessionFileAddSpec
PowerCLI Client SDK All Parameters Example
$LibraryItemTransferEndpoint = Initialize-LibraryItemTransferEndpoint -Uri "MyUri" -SslCertificateThumbprint "MySslCertificateThumbprint"
$LibraryItemFileChecksumInfo = Initialize-LibraryItemFileChecksumInfo -Algorithm "SHA1" -Checksum "MyChecksum"
$LibraryItemUpdatesessionFileAddSpec = Initialize-LibraryItemUpdatesessionFileAddSpec -Name "MyName" -SourceType "NONE" -SourceEndpoint $LibraryItemTransferEndpoint -Size 0 -ChecksumInfo $LibraryItemFileChecksumInfo
Invoke-CreateUpdateSessionIdItemFile -UpdateSessionId "MyUpdateSessionId" -LibraryItemUpdatesessionFileAddSpec $LibraryItemUpdatesessionFileAddSpec
cURL Command
curl -X POST -H "vmware-api-session-id: b00db39f948d13ea1e59b4d6fce56389" -H "Content-Type: application/json" -d '{"checksum_info":{"algorithm":"SHA1","checksum":"string"},"name":"string","size":0,"source_endpoint":{"ssl_certificate_thumbprint":"string","uri":"string"},"source_type":"NONE"}' https://{api_host}/api/content/library/item/update-session/{update_session_id}/file
Vendor Extensions
This operation contains the following vendor extensions defined in the spec:
x-vmw-doc-deprecated-method: post
x-vmw-doc-deprecated-path: /rest/com/vmware/content/library/item/updatesession/file/id:{update_session_id}?~action=add
x-vmw-doc-operation: add
Availability
Added in 7.0U2
