vsphere-automation-content

The Ruby gem for the vSphere Content API

  • API version: 2.0.0
  • Package version: 0.2.2

Installation

Add this line to your application's Gemfile:

gem 'vsphere-automation-content'

And then execute:

$ bundle

Or install it yourself as:

$ gem install vsphere-automation-content

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'vsphere-automation-content'

# Setup authorization
VSphereAutomation.configure do |config|
  # Configure API key authorization: api_key
  config.api_key['vmware-api-session-id'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['vmware-api-session-id'] = 'Bearer'
end

api_instance = VSphereAutomation::Content::ConfigurationApi.new
action = 'action_example' # String | ~action=get

begin
  #Retrieves the current configuration values.
  result = api_instance.get(action)
  p result
rescue VSphereAutomation::ApiError => e
  puts "Exception when calling ConfigurationApi->get: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://<vcenter>/rest

Class Method HTTP request Description
VSphereAutomation::Content::ConfigurationApi get POST /com/vmware/content/configuration Retrieves the current configuration values.
VSphereAutomation::Content::ConfigurationApi update PATCH /com/vmware/content/configuration Updates the configuration. The update is incremental. Any field in the ConfigurationModel structure that is unset will not be modified. Note that this update operation doesn't guarantee an atomic change of all the properties. In the case of a system crash or failure, some of the properties could be left unchanged while others may be updated.
VSphereAutomation::Content::LibraryApi find POST /com/vmware/content/library Returns a list of all the visible (as determined by authorization policy) libraries matching the requested Library.FindSpec.
VSphereAutomation::Content::LibraryApi get GET /com/vmware/content/library/id:library_id Returns a given LibraryModel.
VSphereAutomation::Content::LibraryApi list GET /com/vmware/content/library Returns the identifiers of all libraries of any type in the Content Library.
VSphereAutomation::Content::LibraryApi update PATCH /com/vmware/content/library/id:library_id Updates the properties of a library.

This is an incremental update to the library. Any field in the LibraryModel structure that is unset will not be modified.

This operation will only update the common properties for all library types. This will not, for example, update the LibraryModel#publishInfo of a local library, nor the LibraryModel#subscriptionInfo of a subscribed library. Specific properties are updated in LocalLibrary#update and SubscribedLibrary#update.
VSphereAutomation::Content::LibraryItemApi copy POST /com/vmware/content/library/item/id:source_library_item_id Copies a library item.

Copying a library item allows a duplicate to be made within the same or different library. The copy occurs by first creating a new library item, whose identifier is returned. The content of the library item is then copied asynchronously. This copy can be tracked as a task.

If the copy fails, Content Library Service will roll back the copy by deleting any content that was already copied, and removing the new library item. A failure during rollback may require manual cleanup by an administrator.

A library item cannot be copied into a subscribed library.
VSphereAutomation::Content::LibraryItemApi create POST /com/vmware/content/library/item Creates a new library item.

A new library item is created without any content. After creation, content can be added through the UpdateSession and File services.

A library item cannot be created in a subscribed library.
VSphereAutomation::Content::LibraryItemApi delete DELETE /com/vmware/content/library/item/id:library_item_id Deletes a library item.

This operation will immediately remove the item from the library that owns it. The content of the item will be asynchronously removed from the storage backings. The content deletion can be tracked with a task. In the event that the task fails, an administrator may need to manually remove the files from the storage backing.

This operation cannot be used to delete a library item that is a member of a subscribed library. Removing an item from a subscribed library requires deleting the item from the original published local library and syncing the subscribed library.
VSphereAutomation::Content::LibraryItemApi find POST /com/vmware/content/library/item?~action=find Returns identifiers of all the visible (as determined by authorization policy) library items matching the requested Item.FindSpec.
VSphereAutomation::Content::LibraryItemApi get GET /com/vmware/content/library/item/id:library_item_id Returns the ItemModel with the given identifier.
VSphereAutomation::Content::LibraryItemApi list GET /com/vmware/content/library/item Returns the identifiers of all items in the given library.
VSphereAutomation::Content::LibraryItemApi publish POST /com/vmware/content/library/item/id:library_item_id Publishes the library item to specified subscriptions of the library. If no subscriptions are specified, then publishes the library item to all subscriptions of the library.
VSphereAutomation::Content::LibraryItemApi update PATCH /com/vmware/content/library/item/id:library_item_id Updates the specified properties of a library item.

This is an incremental update to the library item. Fields that are unset in the update specification are left unchanged.

This operation cannot update a library item that is a member of a subscribed library. Those items must be updated in the source published library and synchronized to the subscribed library.
VSphereAutomation::Content::LibraryItemDownloadSessionApi cancel POST /com/vmware/content/library/item/download-session/id:download_session_id?~action=cancel Cancels the download session. This operation will abort any ongoing transfers and invalidate transfer urls that the client may be downloading from.
VSphereAutomation::Content::LibraryItemDownloadSessionApi create POST /com/vmware/content/library/item/download-session Creates a new download session.
VSphereAutomation::Content::LibraryItemDownloadSessionApi delete DELETE /com/vmware/content/library/item/download-session/id:download_session_id Deletes a download session. This removes the session and all information associated with it.

Removing a download session leaves any current transfers for that session in an indeterminate state (there is no guarantee that the transfers will be able to complete). However there will no longer be a means of inspecting the status of those downloads except by seeing the effect on the library item.

Download sessions for which there is no download activity or which are complete will automatically be expired and then deleted after a period of time.
VSphereAutomation::Content::LibraryItemDownloadSessionApi fail POST /com/vmware/content/library/item/download-session/id:download_session_id Terminates the download session with a client specified error message.

This is useful in transmitting client side failures (for example, not being able to download a file) to the server side.
VSphereAutomation::Content::LibraryItemDownloadSessionApi get GET /com/vmware/content/library/item/download-session/id:download_session_id Gets the download session with the specified identifier, including the most up-to-date status information for the session.
VSphereAutomation::Content::LibraryItemDownloadSessionApi keep_alive POST /com/vmware/content/library/item/download-session/id:download_session_id?~action=keep-alive Keeps a download session alive. This operation is allowed only if the session is in the DownloadSessionModel.State#ACTIVE state.

If there is no activity for a download session for a certain period of time, the download session will expire. The download session expiration timeout is configurable in the Content Library Service system configuration. The default is five minutes. Invoking this operation enables a client to specifically extend the lifetime of an active download session.
VSphereAutomation::Content::LibraryItemDownloadSessionApi list GET /com/vmware/content/library/item/download-session Lists the identifiers of the download sessions created by the calling user. Optionally may filter by library item.
VSphereAutomation::Content::LibraryItemDownloadsessionFileApi get POST /com/vmware/content/library/item/downloadsession/file/id:download_session_id?~action=get Retrieves file download information for a specific file.
VSphereAutomation::Content::LibraryItemDownloadsessionFileApi list GET /com/vmware/content/library/item/downloadsession/file Lists the information of all the files in the library item associated with the download session.
VSphereAutomation::Content::LibraryItemDownloadsessionFileApi prepare POST /com/vmware/content/library/item/downloadsession/file/id:download_session_id Requests a file to be prepared for download.
VSphereAutomation::Content::LibraryItemFileApi get POST /com/vmware/content/library/item/file/id:library_item_id Retrieves the information for a single file in a library item by its name.
VSphereAutomation::Content::LibraryItemFileApi list GET /com/vmware/content/library/item/file Lists all of the files that are stored within a given library item.
VSphereAutomation::Content::LibraryItemStorageApi get POST /com/vmware/content/library/item/storage/id:library_item_id Retrieves the storage information for a specific file in a library item.
VSphereAutomation::Content::LibraryItemStorageApi list GET /com/vmware/content/library/item/storage Lists all storage items for a given library item.
VSphereAutomation::Content::LibraryItemUpdateSessionApi cancel POST /com/vmware/content/library/item/update-session/id:update_session_id?~action=cancel Cancels the update session and sets its state to UpdateSessionModel.State#CANCELED. This operation will free up any temporary resources currently associated with the session.

This operation is not allowed if the session has been already completed.

Cancelling an update session will cancel any in progress transfers (either uploaded by the client or pulled by the server). Any content that has been already received will be scheduled for deletion.
VSphereAutomation::Content::LibraryItemUpdateSessionApi complete POST /com/vmware/content/library/item/update-session/id:update_session_id Completes the update session. This indicates that the client has finished making all the changes required to the underlying library item. If the client is pushing the content to the server, the library item will be updated once this call returns. If the server is pulling the content, the call may return before the changes become visible. In that case, the client can track the session to know when the server is done.

This operation requires the session to be in the UpdateSessionModel.State#ACTIVE state.

Depending on the type of the library item associated with this session, a type adapter may be invoked to verify the validity of the files uploaded. The user can explicitly validate the session before completing the session by using the content.library.item.updatesession.File#validate operation.

Modifications are not visible to other clients unless the session is completed and all necessary files have been received.
VSphereAutomation::Content::LibraryItemUpdateSessionApi create POST /com/vmware/content/library/item/update-session Creates a new update session. An update session is used to make modifications to a library item. Modifications are not visible to other clients unless the session is completed and all necessary files have been received.

Content Library Service allows only one single update session to be active for a specific library item.
VSphereAutomation::Content::LibraryItemUpdateSessionApi delete DELETE /com/vmware/content/library/item/update-session/id:update_session_id Deletes an update session. This removes the session and all information associated with it.

Removing an update session leaves any current transfers for that session in an indeterminate state (there is no guarantee that the server will terminate the transfers, or that the transfers can be completed). However there will no longer be a means of inspecting the status of those uploads except by seeing the effect on the library item.

Update sessions for which there is no upload activity or which are complete will automatically be deleted after a period of time.
VSphereAutomation::Content::LibraryItemUpdateSessionApi fail POST /com/vmware/content/library/item/update-session/id:update_session_id?~action=fail Terminates the update session with a client specified error message.

This is useful in transmitting client side failures (for example, not being able to access a file) to the server side.
VSphereAutomation::Content::LibraryItemUpdateSessionApi get GET /com/vmware/content/library/item/update-session/id:update_session_id Gets the update session with the specified identifier, including the most up-to-date status information for the session.
VSphereAutomation::Content::LibraryItemUpdateSessionApi keep_alive POST /com/vmware/content/library/item/update-session/id:update_session_id?~action=keep-alive Keeps an update session alive.

If there is no activity for an update session after a period of time, the update session will expire, then be deleted. The update session expiration timeout is configurable in the Content Library Service system configuration. The default is five minutes. Invoking this operation enables a client to specifically extend the lifetime of the update session.
VSphereAutomation::Content::LibraryItemUpdateSessionApi list GET /com/vmware/content/library/item/update-session Lists the identifiers of the update session created by the calling user. Optionally may filter by library item.
VSphereAutomation::Content::LibraryItemUpdateSessionApi update PATCH /com/vmware/content/library/item/update-session/id:update_session_id Updates the properties of an update session.

This is an incremental update to the update session. Any field in the UpdateSessionModel structure that is unset will not be modified.

This operation will only update the property UpdateSessionModel#warningBehavior of the update session. This will not, for example, update the UpdateSessionModel#libraryItemId or UpdateSessionModel#state of an update session.

This operation requires the session to be in the UpdateSessionModel.State#ACTIVE state.
VSphereAutomation::Content::LibraryItemUpdatesessionFileApi add POST /com/vmware/content/library/item/updatesession/file/id:update_session_id 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.
VSphereAutomation::Content::LibraryItemUpdatesessionFileApi get POST /com/vmware/content/library/item/updatesession/file/id:update_session_id?~action=get Retrieves information about a specific file in the snapshot of the library item at the time when the update session was created.
VSphereAutomation::Content::LibraryItemUpdatesessionFileApi list GET /com/vmware/content/library/item/updatesession/file Lists all files in the library item associated with the update session.
VSphereAutomation::Content::LibraryItemUpdatesessionFileApi remove POST /com/vmware/content/library/item/updatesession/file/id:update_session_id?~action=remove Requests a file to be removed. The file will only be effectively removed when the update session is completed.
VSphereAutomation::Content::LibraryItemUpdatesessionFileApi validate POST /com/vmware/content/library/item/updatesession/file/id:update_session_id?~action=validate 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 operation will return its name in the ValidationResult#missingFiles set. The user can add the missing files and try re-validating. For other type of errors, ValidationResult#invalidFiles will contain the list of invalid files.
VSphereAutomation::Content::LibrarySubscribedItemApi evict POST /com/vmware/content/library/subscribed-item/id:library_item_id Evicts the cached content of a library item in a subscribed library.

This operation allows the cached content of a library item to be removed to free up storage capacity. This operation will only work when a library item is synchronized on-demand. When a library is not synchronized on-demand, it always attempts to keep its cache up-to-date with the published source. Evicting the library item will set ItemModel#cached to false.
VSphereAutomation::Content::LibrarySubscribedItemApi sync POST /com/vmware/content/library/subscribed-item/id:library_item_id?~action=sync Forces the synchronization of an individual library item in a subscribed library.

Synchronizing an individual item will update that item's metadata from the remote source. If the source library item on the remote library has been deleted, this operation will delete the library item from the subscribed library as well.

The default behavior of the synchronization is determined by the SubscriptionInfo of the library which owns the library item.

  • If SubscriptionInfo#onDemand is true, then the file content is not synchronized by default. In this case, only the library item metadata is synchronized. The file content may still be forcefully synchronized by passing true for the forceSyncContent parameter.
  • If SubscriptionInfo#onDemand is false, then this call will always synchronize the file content. The forceSyncContent parameter is ignored when the subscription is not on-demand.
When the file content has been synchronized, the ItemModel#cached field will be true.

This operation will return immediately and create an asynchronous task to perform the synchronization.
VSphereAutomation::Content::LibrarySubscriptionsApi create POST /com/vmware/content/library/subscriptions/id:library Creates a subscription of the published library.
VSphereAutomation::Content::LibrarySubscriptionsApi delete POST /com/vmware/content/library/subscriptions/id:library?~action=delete Deletes the specified subscription of the published library. The subscribed library associated with the subscription will not be deleted.
VSphereAutomation::Content::LibrarySubscriptionsApi get POST /com/vmware/content/library/subscriptions/id:library?~action=get Returns information about the specified subscription of the published library.
VSphereAutomation::Content::LibrarySubscriptionsApi list GET /com/vmware/content/library/subscriptions Lists the subscriptions of the published library.
VSphereAutomation::Content::LibrarySubscriptionsApi update PATCH /com/vmware/content/library/subscriptions/id:library Updates the specified subscription of the published library.

This is an incremental update to the subscription. Except for the UpdateSpecPlacement structure, fields that are unset in the update specification will be left unchanged. If spec#subscribedLibraryPlacement is specified, all fields of the current subscribed library placement will be replaced by this placement.
VSphereAutomation::Content::LocalLibraryApi create POST /com/vmware/content/local-library Creates a new local library.
VSphereAutomation::Content::LocalLibraryApi delete DELETE /com/vmware/content/local-library/id:library_id Deletes the specified local library.

Deleting a local library will remove the entry immediately and begin an asynchronous task to remove all cached content for the library. If the asynchronous task fails, file content may remain on the storage backing. This content will require manual removal.
VSphereAutomation::Content::LocalLibraryApi get GET /com/vmware/content/local-library/id:library_id Returns a given local library.
VSphereAutomation::Content::LocalLibraryApi list GET /com/vmware/content/local-library Returns the identifiers of all local libraries in the Content Library.
VSphereAutomation::Content::LocalLibraryApi publish POST /com/vmware/content/local-library/id:library_id Publishes the library to specified subscriptions. If no subscriptions are specified, then publishes the library to all its subscriptions.
VSphereAutomation::Content::LocalLibraryApi update PATCH /com/vmware/content/local-library/id:library_id Updates the properties of a local library.

This is an incremental update to the local library. Fields that are unset in the update specification will be left unchanged.
VSphereAutomation::Content::SubscribedLibraryApi create POST /com/vmware/content/subscribed-library Creates a new subscribed library.

Once created, the subscribed library will be empty. If the LibraryModel#subscriptionInfo property is set, the Content Library Service will attempt to synchronize to the remote source. This is an asynchronous operation so the content of the published library may not immediately appear.
VSphereAutomation::Content::SubscribedLibraryApi delete DELETE /com/vmware/content/subscribed-library/id:library_id Deletes the specified subscribed library.

Deleting a subscribed library will remove the entry immediately and begin an asynchronous task to remove all cached content for the library. If the asynchronous task fails, file content may remain on the storage backing. This content will require manual removal.
VSphereAutomation::Content::SubscribedLibraryApi evict POST /com/vmware/content/subscribed-library/id:library_id?~action=evict Evicts the cached content of an on-demand subscribed library.

This operation allows the cached content of a subscribed library to be removed to free up storage capacity. This operation will only work when a subscribed library is synchronized on-demand.
VSphereAutomation::Content::SubscribedLibraryApi get GET /com/vmware/content/subscribed-library/id:library_id Returns a given subscribed library.
VSphereAutomation::Content::SubscribedLibraryApi list GET /com/vmware/content/subscribed-library Returns the identifiers of all subscribed libraries in the Content Library.
VSphereAutomation::Content::SubscribedLibraryApi probe POST /com/vmware/content/subscribed-library?~action=probe Probes remote library subscription information, including URL, SSL certificate and password. The resulting ProbeResult structure describes whether or not the subscription configuration is successful.
VSphereAutomation::Content::SubscribedLibraryApi sync POST /com/vmware/content/subscribed-library/id:library_id Forces the synchronization of the subscribed library.

Synchronizing a subscribed library forcefully with this operation will perform the same synchronization behavior as would run periodically for the library. The SubscriptionInfo#onDemand setting is respected. Calling this operation on a library that is already in the process of synchronizing will have no effect.
VSphereAutomation::Content::SubscribedLibraryApi update PATCH /com/vmware/content/subscribed-library/id:library_id Updates the properties of a subscribed library.

This is an incremental update to the subscribed library. Fields that are unset in the update specification will be left unchanged.

Documentation for Models