VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

PowerCLI Access to vSphere APIs

This chapter shows how to run example scripts by using the PowerCLI SDK cmdlets that bind directly to the vSphere APIs.
You can use the following mechanisms to access the vSphere APIs with PowerCLI:
  • For the
    vSphere Management API
    : use the
    Get-View
     cmdlet that allows you to manipulate VIM objects.
  • For the
    vSphere Automation API
    : use the
    vSphere Automation SDK for PowerShell
     with its
    Initialize-
     and
    Invoke-
     cmdlets.

Using Get-View

Use the Get-View cmdlet to view objects and call methods on the
vSphere Management API
. The Get-View cmdlet offers high performance by binding directly to the vSphere Management API.

Using the vSphere Automation SDK for PowerShell

Starting from VMware PowerCLI 12.4.0, you can use the
vSphere Automation SDK for PowerShell
 to communicate with the
vSphere Automation API
.
You can construct
vSphere Automation SDK
 cmdlets by using the
Initialize-
 and
Invoke-
 cmdlet verbs in combination with the names of the
vSphere Automation API
 data structures or operations.
Constructing vSphere Automation SDK Cmdlets
Use the Initialize and Invoke cmdlet verbs to construct vSphere Automation SDK Cmdlets.
  • Use
    Initialize-
     cmdlets to prepare the data structures, if any, for your API calls. These cmdlets function on the client side and do not communicate with the
    vSphere Automation API
     server.
  • Use
    Invoke-
     cmdlets to execute the operations on the server side.

Installing Microsoft PowerShell and VMware PowerCLI

To access vSphere APIs through cmdlets, you must have
Microsoft PowerShell
 and
VMware PowerCLI
 installed on your machine.
  1. Verify that PowerShell is available on your system. Windows users have PowerShell pre-installed, while Linux and macOS users must install it manually. For more information, see the PowerCLI Installation Guide.
  2. To install PowerCLI, open PowerShell and run the command:
    Install-Module
     -
    Name
    VMware.PowerCLI

Basic Authentication to the VIM API and the vSphere Automation API

With PowerCLI, you connect with a single command to the
vSphere Management API
 and the
vSphere Automation API
.
  1. Run the
    Connect-VIServer
     cmdlet with your credentials and you create authentication sessions to both vSphere APIs automatically.
    Connect-VIServer
     -
    Server
     vc1.example.com -
    User
     'MyUser' -
    Password
     'MyPassword'

Creating a Hello Folder with the VIM API Using PowerCLI

Because the
CreateFolder
 method is a part of the
vSphere Management API
, you must use the
Get-View
 cmdlet.
  1. Create a variable with the
    ServiceInstance
     object view.
    $serviceInstance = Get-View ServiceInstance
  2. Create a variable with the
    RootFolder
     object view.
    $rootFolderView = Get-View -Id $serviceInstance.Content.RootFolder
  3. To create your folder, invoke the
    CreateFolder
     method on the
    RootFolder
     view.
    $FolderMOID = $rootFolderView.CreateFolder('Hello Folder')

Tagging the Hello World Folder with the Automation API Through PowerCLI

The Tagging APIs are included in the
vSphere Automation API
 as a part of the
CIS REST APIs
 package (CIS stands for common infrastructure services). Therefore, you can use the
vSphere Automation SDK for PowerShell
 to access the Tagging APIs with PowerCLI.
To tag a folder, start by creating a tag category, then create a tag in that category, and finally associate the tag with the folder. Each step in the tag creation and application process requires two PowerCLI verbs, both the
Initialize
 and the
Invoke
.
  1. Create a tag category.
    $TaggingCategoryCreateSpec = Initialize-TaggingCategoryCreateSpec -Name "helloCategory" -Description "A tag category for custom folders" -Cardinality "SINGLE" -AssociableTypes "Folder"

$tagCategoryID = Invoke-CreateCategory -TaggingCategoryCreateSpec $TaggingCategoryCreateSpec
    The system returns the ID of the newly created tag category.
  2. Create a tag in that category. You use the tag category ID from the previous step.
    $TaggingTagCreateSpec = Initialize-TaggingTagCreateSpec -Name "helloTag" -Description "example of a tag from PowerCLI" -CategoryId $tagCategoryID

$tagID = Invoke-CreateTag -TaggingTagCreateSpec $TaggingTagCreateSpec
    The system returns the ID of the newly created tag.
  3. Associate the tag with the
    Hello World
     folder. You use the
    Hello World
     folder ID and the tag ID that you created in the previous step.
    $FolderID = Initialize-StdDynamicID -Type "Folder" -Id $FolderMOID.value

$TaggingTagAssociationAttachRequestBody = Initialize-TaggingTagAssociationAttachRequestBody -ObjectId $FolderID

Invoke-AttachTagIdTagAssociation -TagId $tagID -TaggingTagAssociationAttachRequestBody $TaggingTagAssociationAttachRequestBody
You can now see the
Hello World
 folder with the tag and category in the vSphere Client.

Content feedback and comments