So, I built a group of functions and stored them in a script called cohesity-api.ps1. You can download a copy of the library by running the following command in PowerShell:
To use the functions you can simply source, or dot, the script.
This makes the functions available in the current PowerShell session (or in the current script). Let's review some of the basic functions it provides...
The first function authenticates you to a Cohesity cluster.
Notice that I haven't provided a password nor have I been prompted for one. this is because apiauth stores your password (encrypted) for future use, so that scripts can run unattended. The first time you attempt to connect to a cluster, you will be prompted for your password and it will be stored.
If your Cohesity (or Active Directory) password changes, the stored password will need to be updated. This can be done using the -updatepassword switch:
Also note that -domain defaults to 'local', and positional arguments work fine, so to connect as local admin, you can simply type:
Making API Calls
Once you've been authenticated, you can make API calls. You can simply provide the HTTP verb (get, post, put, delete) and the tail of the URL of the API call. for example, to get a list of protection jobs, you can type:
The URL of this API call is actually https://mycluster/irisservices/api/v1/public/protectionJobs. I provided protectionJobs to the api function and it tacked on https://mycluster/irisservices/api/v1/public/ in front of it.
Public vs. Internal API
Cohesity API calls are categorized as either public or internal. All are accessible to the user, but public calls are designed to be easier to use and perhaps less subject to change from version to version. However, there are operations that you just can't do without resorting to some internal APIs. The Internal calls are a bit more complex, but that shouldn't stop us from using them when we have to.
To make an internal API call using our api function, simply prepend a / infront of the URL tail, like so:
Drilling Down on the Data
Let's have a look at some of the data we got back. Let's return to our public protectionJobs call.
Having a look at $jobs shows us the list of jobs we got back.
We can have a closer look at the first one by providing a list index:
and drill down into nested attributes:
We can get properties from each job in the list:
Or, we can enumerate over the list:
The last topic I want to cover in this article, before we move on to other operations like posts and puts, is query strings in get URLs. You can pass along parameters with your get calls like this:
and we can use the ampersand to include multiple parameters:
Whoops! PowerShell interpreted the & as the call operator. We can escape the & with a back tick like this:
and that works fine, but when there are several & and other troublesome characters in the URL, it's easier to simply quote the entire URL:
We can even use spaces:
or using double quotes, we can use variable expansion in our URL:
You may have noticed that everything we've done so far uses the get verb. We've yet to cover posts, puts and deletes, but we'll save those for the next few articles.