item Package

item Package

downloadsession_client Module

The Content Library Item Download Session module provides classes and classes for downloading files in a session.

class com.vmware.content.library.item.downloadsession_client.File(config)

Bases: vmware.vapi.bindings.stub.VapiInterface

The File class provides methods for accessing files within a download session.

After a download session is created against a library item, the File class can be used to retrieve all downloadable content within the library item. Since the content may not be available immediately in a downloadable form on the server side, the client will have to prepare the file and wait for the file status to become File.PrepareStatus.PREPARED.

See com.vmware.content.library.item_client.DownloadSession.

Parameters:config (vmware.vapi.bindings.stub.StubConfiguration) – Configuration to be used for creating the stub.

class EndpointType(string)

Bases: vmware.vapi.bindings.enum.Enum

The File.EndpointType class defines the types of endpoints used to download the file.

Note

This class represents an enumerated type in the interface language definition. The class contains class attributes which represent the values in the current version of the enumerated type. Newer versions of the enumerated type may contain new values. To use new values of the enumerated type in communication with a server that supports the newer version of the API, you instantiate this class. See enumerated type description page.

Parameters:string (str) – String value for the EndpointType instance.

DIRECT = EndpointType(string='DIRECT')

A direct download endpoint indicating the location of the file on storage. The caller is responsible for retrieving the file from the storage location directly.

HTTPS = EndpointType(string='HTTPS')

An https download endpoint.

class File.Info(name=None, size=None, bytes_transferred=None, status=None, download_endpoint=None, checksum_info=None, error_message=None)

Bases: vmware.vapi.bindings.struct.VapiStruct

The File.Info class defines the downloaded file.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

• name (str) – The name of the file.
• size (long or None) – The file size, in bytes. This attribute may not be available immediately. It is guaranteed to be set when the client finishes downloading the file.
• bytes_transferred (long) – The number of bytes that have been transferred by the server so far for making this file prepared for download. This value may stay at zero till the client starts downloading the file.
• status (File.PrepareStatus) – The preparation status (UNPREPARED, PREPARE_REQUESTED, PREPARING, PREPARED, ERROR) of the file.
• download_endpoint (com.vmware.content.library.item_client.TransferEndpoint or None) – Endpoint at which the file is available for download. The value is valid only when the File.Info.status is File.PrepareStatus.PREPARED. This attribute won’t be set until the file status is File.PrepareStatus.PREPARED.
• checksum_info (com.vmware.content.library.item_client.File.ChecksumInfo or None) – The checksum information of the file. When the download is complete, you can retrieve the checksum from the File.get() method to verify the checksum for the downloaded file. The checksum is always calculated for the downloaded file, but this attribute won’t be set until the download is complete.
• error_message (com.vmware.vapi.std_client.LocalizableMessage or None) – Error message for a failed preparation when the prepare status is File.PrepareStatus.ERROR. This attribute won’t be set unless there was an error with the file transfer.

class File.PrepareStatus(string)

Bases: vmware.vapi.bindings.enum.Enum

The File.PrepareStatus class defines the state of the file in preparation for download.

Note

This class represents an enumerated type in the interface language definition. The class contains class attributes which represent the values in the current version of the enumerated type. Newer versions of the enumerated type may contain new values. To use new values of the enumerated type in communication with a server that supports the newer version of the API, you instantiate this class. See enumerated type description page.

Parameters:string (str) – String value for the PrepareStatus instance.

ERROR = PrepareStatus(string='ERROR')

Prepare failed.

PREPARED = PrepareStatus(string='PREPARED')

Prepare succeeded. The file is ready for download.

PREPARE_REQUESTED = PrepareStatus(string='PREPARE_REQUESTED')

A prepare has been requested, however the server hasn’t started the preparation yet.

PREPARING = PrepareStatus(string='PREPARING')

A prepare has been requested and the file is in the process of being prepared.

UNPREPARED = PrepareStatus(string='UNPREPARED')

The file hasn’t been requested for preparation.

File.get(download_session_id, file_name)

Retrieves file download information for a specific file.

Parameters:

• download_session_id (str) – Identifier of the download session. The parameter must be an identifier for the resource type: com.vmware.content.library.item.DownloadSession.
• file_name (str) – Name of the file requested.

Return type:

File.Info

Returns:

The File.Info instance containing the status of the file and its download link if available.

Raise :

com.vmware.vapi.std.errors_client.NotFound if the download session associated with download_session_id does not exist.

Raise :

com.vmware.vapi.std.errors_client.InvalidArgument if there is no file with the specified file_name.

Raise :

com.vmware.vapi.std.errors_client.Unauthorized if you do not have all of the privileges described as follows:

• The resource com.vmware.content.library.Item referenced by the parameter libraryItemId requires System.Read.

File.list(download_session_id)

Lists the information of all the files in the library item associated with the download session.

Parameters:

download_session_id (str) – Identifier of the download session. The parameter must be an identifier for the resource type: com.vmware.content.library.item.DownloadSession.

Return type:

list of File.Info

Returns:

The list of File.Info instances.

Raise :

com.vmware.vapi.std.errors_client.NotFound if the download session associated with download_session_id doesn’t exist.

Raise :

com.vmware.vapi.std.errors_client.Unauthorized if you do not have all of the privileges described as follows:

• The resource com.vmware.content.library.Item referenced by the parameter libraryItemId requires System.Read.

File.prepare(download_session_id, file_name, endpoint_type=None)

Requests a file to be prepared for download.

Parameters:

• download_session_id (str) – Identifier of the download session. The parameter must be an identifier for the resource type: com.vmware.content.library.item.DownloadSession.
• file_name (str) – Name of the file requested for download.
• endpoint_type (File.EndpointType or None) – Endpoint type request, one of HTTPS, DIRECT. This will determine the type of the File.Info.download_endpoint that is generated when the file is prepared. The File.EndpointType.DIRECT is only available to users who have the ContentLibrary.ReadStorage privilege. If not specified the default is File.EndpointType.HTTPS.

Return type:

File.Info

Returns:

File information containing the status of the request and the download link to the file.

Raise :

com.vmware.vapi.std.errors_client.NotFound if the download session does not exist.

Raise :

com.vmware.vapi.std.errors_client.InvalidArgument if there is no file with the specified file_name.

Raise :

com.vmware.vapi.std.errors_client.Unauthorized if the the download session wasn’t created with the ContentLibrary.ReadStorage privilege and the caller requested a File.EndpointType.DIRECT endpoint type.

updatesession_client Module

The Content Library Item Update Session module provides classes and classes for updating files in a session.

class com.vmware.content.library.item.updatesession_client.File(config)

Bases: vmware.vapi.bindings.stub.VapiInterface

The File class provides methods for accessing files within an update session.

After an update session is created against a library item, the File class can be used to make changes to the underlying library item metadata as well as the content of the files. The following changes can be made:

• deleting an existing file within the library item. This deletes both the metadata and the content.
• updating an existing file with new content.
• adding a new file to the library item.

The above changes are not applied or visible until the session is completed. See com.vmware.content.library.item_client.UpdateSession.

Parameters:config (vmware.vapi.bindings.stub.StubConfiguration) – Configuration to be used for creating the stub.

class AddSpec(name=None, source_type=None, source_endpoint=None, size=None, checksum_info=None)

Bases: vmware.vapi.bindings.struct.VapiStruct

The File.AddSpec class describes the properties of the file to be uploaded.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

• name (str) – The name of the file being uploaded.
• source_type (File.SourceType) – The source type (NONE, PUSH, PULL) from which the file content will be retrieved.
• source_endpoint (com.vmware.content.library.item_client.TransferEndpoint) – Location from which the Content Library Service will fetch the file, rather than requiring a client to upload the file. This attribute is optional and it is only relevant when the value of sourceType is File.SourceType.PULL.
• size (long or None) – The file size, in bytes. If specified the server will verify it received the correct size.
• checksum_info (com.vmware.content.library.item_client.File.ChecksumInfo or None) – 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. If not specified the server does not verify the checksum.

class File.Info(name=None, source_type=None, size=None, checksum_info=None, source_endpoint=None, upload_endpoint=None, bytes_transferred=None, status=None, error_message=None)

Bases: vmware.vapi.bindings.struct.VapiStruct

The File.Info class defines the uploaded file.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

• name (str) – The name of the file.
• source_type (File.SourceType) – The source type (NONE, PUSH, PULL) from which the file is being retrieved. This may be File.SourceType.NONE if the file is not being changed.
• size (long or None) – The file size, in bytes as received by the server. This attribute is guaranteed to be set when the server has completely received the file. This attribute won’t be set until the file status is com.vmware.content.library.item_client.TransferStatus.READY.
• checksum_info (com.vmware.content.library.item_client.File.ChecksumInfo or None) – The checksum information of the file received by the server. If not specified the server does not verify the checksum.
• source_endpoint (com.vmware.content.library.item_client.TransferEndpoint) – A source endpoint from which to retrieve the file. This attribute is optional and it is only relevant when the value of sourceType is File.SourceType.PULL.
• upload_endpoint (com.vmware.content.library.item_client.TransferEndpoint) – An upload endpoint to which the client can push the content. This attribute is optional and it is only relevant when the value of sourceType is File.SourceType.PUSH.
• bytes_transferred (long) – The number of bytes of this file that have been received by the server.
• status (com.vmware.content.library.item_client.TransferStatus) – The transfer status (WAITING_FOR_TRANSFER, TRANSFERRING, READY, VALIDATING, ERROR) of this file.
• error_message (com.vmware.vapi.std_client.LocalizableMessage or None) – Details about the transfer error. An error message is set if the status is com.vmware.content.library.item_client.TransferStatus.ERROR.

class File.SourceType(string)

Bases: vmware.vapi.bindings.enum.Enum

The File.SourceType class defines how the file content is retrieved.

Note

This class represents an enumerated type in the interface language definition. The class contains class attributes which represent the values in the current version of the enumerated type. Newer versions of the enumerated type may contain new values. To use new values of the enumerated type in communication with a server that supports the newer version of the API, you instantiate this class. See enumerated type description page.

Parameters:string (str) – String value for the SourceType instance.

NONE = SourceType(string='NONE')

No source type has been requested.

PULL = SourceType(string='PULL')

The server is pulling content from a URL. The URL scheme can be http, https, file, or ds.

PUSH = SourceType(string='PUSH')

The client is uploading content using HTTP(S) PUT requests.

class File.ValidationError(name=None, error_message=None)

Bases: vmware.vapi.bindings.struct.VapiStruct

The File.ValidationError class defines the validation error of a file in the session.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

• name (str) – The name of the file.
• error_message (com.vmware.vapi.std_client.LocalizableMessage) – A message indicating why the file was considered invalid.

class File.ValidationResult(has_errors=None, missing_files=None, invalid_files=None)

Bases: vmware.vapi.bindings.struct.VapiStruct

The File.ValidationResult class defines the result of validating the files in the session.

Tip

The arguments are used to initialize data attributes with the same names.

Parameters:

• has_errors (bool) – Whether the validation was succesful or not. In case of errors, the File.ValidationResult.missing_files and File.ValidationResult.invalid_files will contain at least one entry.
• missing_files (set of str) – A set containing the names of the files that are required but the client hasn’t added.
• invalid_files (list of File.ValidationError) – A list containing the files that have been identified as invalid and details about the error.

File.add(update_session_id, file_spec)

Requests file content to be changed (either created, or updated). Depending on the source type of the file, this method 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 method 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.

Parameters:

• update_session_id (str) – Identifier of the update session to be modified. The parameter must be an identifier for the resource type: com.vmware.content.library.item.UpdateSession.
• file_spec (File.AddSpec) – 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.

Return type:

File.Info

Returns:

An File.Info class containing upload links as well as server side state tracking the transfer of the file.

Raise :

com.vmware.vapi.std.errors_client.InvalidArgument if the file_spec is invalid.

Raise :

com.vmware.vapi.std.errors_client.NotFound if the update session doesn’t exist.

Raise :

com.vmware.vapi.std.errors_client.Unauthorized if the caller doesn’t have ContentLibrary.ReadStorage privilege on the library item of the update session and source type File.SourceType.PULL is requested for a file or datastore source endpoint (that is, not HTTP or HTTPs based endpoint).

File.get(update_session_id, file_name)

Retrieves information about a specific file in the snapshot of the library item at the time when the update session was created.

Parameters:

• update_session_id (str) – Identifier of the update session. The parameter must be an identifier for the resource type: com.vmware.content.library.item.UpdateSession.
• file_name (str) – Name of the file.

Return type:

File.Info

Returns:

Information about the file.

Raise :

com.vmware.vapi.std.errors_client.NotFound if the update session doesn’t exist.

Raise :

com.vmware.vapi.std.errors_client.InvalidArgument if the file doesn’t exist in the library item associated with the update session.

Raise :

com.vmware.vapi.std.errors_client.Unauthorized if you do not have all of the privileges described as follows:

• The resource com.vmware.content.library.Item referenced by the parameter libraryItemId requires System.Read.

File.list(update_session_id)

Lists all files in the library item associated with the update session.

Parameters:

update_session_id (str) – Identifier of the update session. The parameter must be an identifier for the resource type: com.vmware.content.library.item.UpdateSession.

Return type:

list of File.Info

Returns:

The list of the files in the library item associated with the update session. This list may be empty if the caller has removed all the files as part of this session (in which case completing the update session will result in an empty library item).

Raise :

com.vmware.vapi.std.errors_client.NotFound if the update session doesn’t exist.

Raise :

com.vmware.vapi.std.errors_client.Unauthorized if you do not have all of the privileges described as follows:

• The resource com.vmware.content.library.Item referenced by the parameter libraryItemId requires System.Read.

File.remove(update_session_id, file_name)

Requests a file to be removed. The file will only be effectively removed when the update session is completed.

Parameters:

• update_session_id (str) – Identifier of the update session. The parameter must be an identifier for the resource type: com.vmware.content.library.item.UpdateSession.
• file_name (str) – Name of the file to be removed.

Raise :

com.vmware.vapi.std.errors_client.NotFound if the update session doesn’t exist.

Raise :

com.vmware.vapi.std.errors_client.InvalidArgument if the file doesn’t exist in the library item associated with the update session.

File.validate(update_session_id)

Validates the files in the update session with the referenced identifier and ensures all necessary files are received. In the case where a file is missing, this method will return its name in the File.ValidationResult.missing_files set. The user can add the missing files and try re-validating. For other type of errors, File.ValidationResult.invalid_files will contain the list of invalid files.

Parameters:update_session_id (str) – Identifier of the update session to validate. The parameter must be an identifier for the resource type: com.vmware.content.library.item.UpdateSession. Return type:File.ValidationResult Returns:A validation result containing missing files or invalid files and the reason why they are invalid. Raise :com.vmware.vapi.std.errors_client.NotFound if no update session with the given identifier exists. Raise :com.vmware.vapi.std.errors_client.NotAllowedInCurrentState if the update session is not in the com.vmware.content.library.item_client.UpdateSessionModel.State.ACTIVE state, or if some of the files that will be uploaded by the client aren’t received correctly.