Skip to content
This repository has been archived by the owner on Oct 27, 2022. It is now read-only.

Latest commit

 

History

History

content

README.md

vsphere-automation-content

The Ruby gem for the vSphere Content API

  • API version: 2.0.0
  • Package version: 0.4.7

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

begin
  #Retrieves the current configuration values.
  result = api_instance.get
  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?~action=get Retrieves the current configuration values.
VSphereAutomation::Content::ConfigurationApi update PATCH /com/vmware/content/configuration Updates the configuration. The update is incremental. Any {@term field} in the {@link ConfigurationModel} {@term structure} that is {@term unset} will not be modified. Note that this update {@term 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?~action=find Returns a list of all the visible (as determined by authorization policy) libraries matching the requested {@link Library.FindSpec}.
VSphereAutomation::Content::LibraryApi get GET /com/vmware/content/library/id:{library_id} Returns a given {@link 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 {@term field} in the {@link LibraryModel} {@term structure} that is {@term unset} will not be modified.

This {@term operation} will only update the common properties for all library types. This will not, for example, update the {@link LibraryModel#publishInfo} of a local library, nor the {@link LibraryModel#subscriptionInfo} of a subscribed library. Specific properties are updated in {@link LocalLibrary#update} and {@link SubscribedLibrary#update}.
VSphereAutomation::Content::LibraryItemApi copy POST /com/vmware/content/library/item/id:{source_library_item_id}?~action=copy 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 {@link UpdateSession} and {@link File} {@term 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 {@term 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 {@term 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 {@link Item.FindSpec}.
VSphereAutomation::Content::LibraryItemApi get GET /com/vmware/content/library/item/id:{library_item_id} Returns the {@link 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}?~action=publish 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. {@term Fields} that are {@term unset} in the update specification are left unchanged.

This {@term 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 {@term 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}?~action=fail 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 {@link 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 {@term 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}?~action=prepare Requests a file to be prepared for download.
VSphereAutomation::Content::LibraryItemFileApi get POST /com/vmware/content/library/item/file/id:{library_item_id}?~action=get 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}?~action=get 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 {@link UpdateSessionModel.State#CANCELED}. This {@term operation} will free up any temporary resources currently associated with the session.

This {@term 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}?~action=complete 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 {@term operation} requires the session to be in the {@link 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 {@link content.library.item.updatesession.File#validate} {@term 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 {@term 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 {@term field} in the {@link UpdateSessionModel} {@term structure} that is {@term unset} will not be modified.

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

This {@term operation} requires the session to be in the {@link UpdateSessionModel.State#ACTIVE} state.
VSphereAutomation::Content::LibraryItemUpdatesessionFileApi add POST /com/vmware/content/library/item/updatesession/file/id:{update_session_id}?~action=add Requests file content to be changed (either created, or updated). Depending on the source type of the file, this {@term 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 {@term 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 {@term operation} will return its name in the {@link ValidationResult#missingFiles} set. The user can add the missing files and try re-validating. For other type of errors, {@link ValidationResult#invalidFiles} will contain the list of invalid files.
VSphereAutomation::Content::LibrarySubscribedItemApi evict POST /com/vmware/content/library/subscribed-item/id:{library_item_id}?~action=evict Evicts the cached content of a library item in a subscribed library.

This {@term operation} allows the cached content of a library item to be removed to free up storage capacity. This {@term 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 {@link 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 {@term operation} will delete the library item from the subscribed library as well.

The default behavior of the synchronization is determined by the {@link SubscriptionInfo} of the library which owns the library item.

  • If {@link 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 {@param.name forceSyncContent} {@term parameter}.
  • If {@link SubscriptionInfo#onDemand} is false, then this call will always synchronize the file content. The {@param.name forceSyncContent} {@term parameter} is ignored when the subscription is not on-demand.
When the file content has been synchronized, the {@link ItemModel#cached} {@term field} will be true.

This {@term 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 {@link UpdateSpecPlacement} {@term structure}, {@term fields} that are {@term unset} in the update specification will be left unchanged. If {@param.name spec#subscribedLibraryPlacement} is specified, all {@term 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}?~action=publish 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. {@term Fields} that are {@term 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 {@link 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 {@term operation} allows the cached content of a subscribed library to be removed to free up storage capacity. This {@term 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 {@link ProbeResult} {@term structure} describes whether or not the subscription configuration is successful.
VSphereAutomation::Content::SubscribedLibraryApi sync POST /com/vmware/content/subscribed-library/id:{library_id}?~action=sync Forces the synchronization of the subscribed library.

Synchronizing a subscribed library forcefully with this {@term operation} will perform the same synchronization behavior as would run periodically for the library. The {@link SubscriptionInfo#onDemand} setting is respected. Calling this {@term 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. {@term Fields} that are {@term unset} in the update specification will be left unchanged.

Documentation for Models