JS samples were included in the REST SDK to provide an easy example of how to call the vSphere REST API using a common and easy web based language.
To check out the first part in the series where we cover accessing the documentation and using Postman, see the following link: Getting Started with the vSphere Automation SDK for REST
Preparing The Environment
If you haven’t already done any JS work in your current environment, there are a couple preparation steps that are required to get started. While there are many ways to get started with JS, my personal preference is outlined below.
Download NodeJS for your preferred OS and install it, ensuring the “NPM Package Manager” is also installed: https://nodejs.org/en/download/
The reasons I’m using NodeJS and the associated NPM is because NodeJS will allow us to execute JS directly from the command line. NPM (Node Package Manager) will be used to install any of the package dependencies we’ll be needing, as documented in the project.json file.
Lastly, download and install Visual Studio Code which will be used as the IDE (or Integrated Development Environment): https://code.visualstudio.com/Download
However, please note, an IDE is not required to run these samples.
We’ll start by going through the README. There’s a couple important parts in there with regards to getting started, plus it’s always good to get a better understanding of what’s going on with some of these samples.
The beginning portion of the README illustrates a need to download and install some Node modules. These modules are dependencies of the samples and are sourced from the packages.json file in the vcenter directory. We can do this with the following commands at a prompt:
The bottom portion of the README provides a list of all the samples that have been included. Which are as follows:
The last of the first steps is to fill in some of the parameters included as part of the settings.js file. These parameters include some information like which REST endpoint we’re connecting to and which what credentials we’re using to authenticate with. If you recall the Environmental Variables we configured in Part One of this blog series, these parameters work very similarly to those. One item to keep in mind while filling in these parameters is related to the “Host” information, the endpoint will need to have to prepend “https://” to the value. See the example below for a bit more information:
There are several VM examples that are included with this SDK. The easiest and most straight forward of the examples is retrieving details of the VMs associated with the API endpoint by using the vm-details sample. It’s executed by running: npm run vm-details
Another sample is about how to create a VM using defaults. This sample requires the host1 and datastore parameters to be completed within the settings.js file.
If you remember from part 1 of this series, the default settings are made based upon the Guest OS type. This sample creates a VM based on it being a “RHEL_7_64” Guest OS type, which can be seen on line 86 of the create_vm_with_defaults.js script. Another parameter which is set as part of the script is which folder the VM is created in. Referencing line 72 of the same script, we can see it searching for the “Discovered Virtual Machine” folder.
The sample can then be run with the following command: npm run vm-create-defaults
We can see the VM was created with a hardware ID of vm-96. Let’s go back to our first sample and verify that the VM was indeed created.
If we want to perform some actions to that newly created VM, there are a couple samples we can use. However, before we do that, we will need to update the settings.js file to indicate the name of the VM we’re targeting.
The two samples we have access to which can modify the VM are power actions, so powering on or off the system. We can perform the power on action with the following command: npm run vm-power-on
We can see in the above example that the proper VM is found, as referenced by the hardware ID of vm-96. We can then see the status code of 200 meaning the request was successfully received.
Powering off the VM is just as easy as powering it on, and can performed with the following command: npm run vm-power-off
We’re going to switch gears a bit and take a look at some of the host based samples. Since this is an existing environment, I’ll be showing how to disconnect and reconnect a host. Before running the commands, we’ll need to update our settings.js file again to reference the host we’re working with. The host will be designated via the host1 parameter.
If you happen to be adding a host, the hostUsername and hostPassword parameters should be completed as well. They are not needed for the examples below.
In order to disconnect a host, we’ll run the following command: npm run host-disconnect
If we want to reconnect that host, we run the following command: npm run host-connect
When you start creating additional JS scripts, some of the work has already been done for you. Check out the resources directory, it will have multiple individual top level object based scripts that have some of the functions already created. If the function isn’t already created, the vSphere Automation API is really easy to work with so you can easily add your own to the SDK’s samples.
If you’ve missed any of the prior posts, here are the others in the series:
4 comments have been added so far
Thanks for the guide. Really helpful.
Thanks for the blog; it’s been helpful! I have an issue that I’m hoping you can help me with. I’m trying to use the REST API to check on a VM by hostname. I tested using Postman following your instructions.
I’d like filter.names to be case-insensitive and in my tests it doesn’t appear to be so. In the case above, if my VM name is actually TEST-HOST, it returns an empty value. How do I ask it to search in a case-insensitive way?