A library item groups multiple files within one logical unit. You can perform various tasks with the items in a content library.

You can upload files to a library item in a local library and update existing items. You can download the content of a library item from a subscribed library and use the item, for example, to deploy a virtual machine. You can remove the content of a library item from a subscribed library to free storage space and keep only the metadata of the library item. When you no longer need local library items, you can delete them and they are removed from the subscribed library when a synchronization task is completed.

You can create a library item from a specific item type, for example, .ovf and VM template. The Content Library service must support the library item type to handle the item correctly. If no support is provided for a specified type, the Content Library service handles the library item in the default way, without adding metadata to the library item or guiding the upload process. For information about the supported VM template types, see the vSphere Virtual Machine Administration documentation.

Creating an Empty Library Item

You can create as many library items as needed and associate them with a local content library. You can create a library item by using the POST https://<vcenter_ip_address_or_fqdn>/api/content/library/item HTTP request.

Querying Library Items

You can perform numerous query operations on library items.

You can retrieve a list of all items in a library, retrieve a library item that has a specific type or name, and find a library item that is not cached on the disk. You can then update the library item content from the subscribed library.

You can use the GET https://<vcenter_ip_address_or_fqdn>/api/content/library/item?library_id HTTP request to retrieve a list of all items in a particular library.

You can filter the items contained in a library and retrieve only the items matching specific criteria. For example, you might want to remove or update only specific items in a library. You can use the POST https://<vcenter_ip_address_or_fqdn>/api/content/library/item?action=find HTTP request to filter items in a particular library.

Editing the Settings of a Library Item

You can use the PATCH https://<vcenter_ip_address_or_fqdn>/api/content/library/item/<library_item_id> HTTP request to edit the properties of a library item such as name, description, and type.

Uploading a File from a Local System to a Library Item

You can upload different types of files from a local system to a library item that you want to use in the vSphere Automation environment.

To upload a file, you must create an empty library item and verify that you have access to the UpdateSession and File services.

  1. Use the LibraryItemUpdateSessionModel data structure to track the changes that you make to the library item.

  2. Create an update session by using the UpdateSession service.

  3. Use the LibraryItemUpdatesessionFileAddSpec data structure to describe the upload method and other properties of the file to be uploaded.

  4. Create the request for changing the item by using the File service.

  5. Upload the file that is on the local system.

  6. Complete and delete the update session to apply the changes to the library item.

Upload a File from a URL to a Library Item

You can upload different types of files from a URL to a library item that you want to use in the vSphere Automation environment.

To upload a file, you must first create an empty library item and verify that you have access to the UpdateSession and File services.

  1. Use the LibraryItemUpdateSessionModel data structure to track the changes that you make to the library item.

  2. Create an update session by using the UpdateSession service.

  3. Create a file specification to describe the upload method and other properties of the file to be uploaded.

  4. Specify the location of the file you want to upload by using the LibraryItemTransferEndpoint data structure.

  5. Add the file source endpoint to the file specification.

  6. Create a request for changing the item by using the configured file specification.

  7. Complete the update session to apply the changes to the library item.

Downloading Files to a Local System from a Library Item

You might want to download files to a local system from a library item and then make changes to the files before you use them.

  1. Create a download session model to specify the item, which contains the file that you want to download.

  2. Access the File service and retrieve the file that you want to export to your system within the new download session.

  3. Prepare the files that you want to download and wait until the files are in the prepared state.

  4. Retrieve the download endpoint URI of the files.

  5. Download the files by using an HTTP GET request.

  6. Delete the download session after all files are downloaded.

Synchronizing a Library Item in a Subscribed Content Library

The items in a subscribed library have features that are distinct from the items in a local library. Synchronizing the content and the metadata of an item in a subscribed library depends on the synchronization mechanism of the subscribed library. You can use the PATCH https://<vcenter_ip_address_or_fqdn>/api/content/library/subscribed-item/<library_item_id>?action=sync HTTP request to force the synchronization of an individual library item in a subscribed library.

Removing the Content of a Library Item

You can remove the content from a library item to free space on your storage.

If you create a subscribed library with the option to synchronize library content on demand, only the metadata for the library items is stored. When you want to use the items in the library, you must force synchronization on the items to download their content. When you no longer need the files in an item, you can remove the cached content of the library item and free storage space. You can use the POST https://<vcenter_ip_address_or_fqdn>/api/content/library/subscribed-item/<library_item_id>?action=evict HTTP request to evict the cached content of a library item in a subscribed library.

Deleting a Library Item

You can remove a library item from a local library when you no longer need it.

You can use the DELETE https://<vcenter_ip_address_or_fqdn>/api/content/library/item/<library_item_id> HTTP request to remove a library item from a library. The item content is asynchronously removed from the storage.

You cannot remove items from a subscribed library. If you remove an item from a local library, the item is removed from the subscribed library when you perform a synchronization task on the subscribed library item.