Powershell - Create job through RestAPI

[ksl28]

Hi,

Im are trying to create an series of new jobs, through the new RestAPI in V11.
I got the authorization part figured out, and are able to pull job settings, start jobs, etc - but i cant seem to find a way, to create an new job properly.

This is my code so far:

Code: Select all

$GlobalHeaders = @{
    'x-api-version' = '1.0-rev1'
    'Authorization' = "Bearer $accesstoken"
}
$JobNameBody = @{
    "name" = $NewTagName
    "description" = "Backup Job"
    "type" = "Backup"
    "isHighPriority" = $false
    "virtualMachines.includes.hostname" = "vcenter.domain.com"
    "virtualMachines.includes.type" = "tag"
    "virtualMachines.includes.name" = "Backup_Job1_tag"
    "storage.backupRepositoryId" = "1a2872d4-5924-4851-8b65-007336dd142d"
    "storage.backupProxies.AutoSelection" = $true
    "storage.retentionPolicy.type" = "Days"
    "storage.retentionPolicy.quantity" = 14
    "guestProcessing.appAwareProcessing.isEnabled" = $true
    "guestProcessing.guestFSIndexing.isEnabled" = $true
    "schedule.runAutomatically" = $false
  } | ConvertTo-Json
  Invoke-RestMethod -Method Post -Uri "https://dkvbr:9419/api/v1/jobs" -Headers $GlobalHeaders -ContentType "application/json" -Body $JobNameBody

The output is:

Code: Select all

Invoke-RestMethod : {"errorCode":"UnknownError","message":"Object reference not set to an instance of an object.","resourceId":null}

Any suggestions?

[veremin]

I don't have a console handy at the moment, so cannot double check the provided example, but you can open Swagger UI (like described here), expand POST method on job entity and see a full description of available parameters and an automatically generated example - this should help you to understand the correct syntax.

Thanks!

[ksl28]

Hi veremin,

The only Swagger UI i can find, is the one installed with VBR v11, that gives me this example:
https://ibb.co/cxnGv2b

Code: Select all

{
  "name": "string",
  "description": "string",
  "type": "Backup"
}

Executing that also fails, and its dosent come close to all the parameters, that is required in the online documentation.
https://www.veeam.com/test-api-vbr11.ht ... /CreateJob

So where is the Swagger UI you mentioned located?

[jhoughes]

Details for the Swagger UI can be found within the documentation here: https://helpcenter.veeam.com/docs/backu ... ml?ver=110

It'll be this (port will be 9419 unless you changed it from the default):
https://<hostname>:<port>/swagger/ui/index.html

The full REST API reference guide will also show you the syntax for the JSON for creating a VBR job: https://helpcenter.veeam.com/docs/backu ... /CreateJob

[ksl28]

Hi jhoughes,

Thanks for the reply.
In my previous post, i linked at picture to the Swagger UI that seems very limited.
The last link you posted returns an 404, but i assume its this one: https://www.veeam.com/test-api-vbr11.ht ... /CreateJob

I have triple checked both links now, and i still cant seem to figure out, why my example dont work.

[jhoughes]

Go to this page and hit the documentation link at the bottom of the page for the API reference:

https://helpcenter.veeam.com/docs/backu ... ml?ver=110

Also, if you cannot see the documentation for some reason, just use the GET method for jobs first and you will see the format of an existing full object that you need to use.

[ksl28]

Hi,

Not to be an pain in the arse, but ive already tried that.
Im able to use the documentation for most of the other HTTP calls, but creating an job fails, and it appears its my virtualMachines section.

I cant seem to figure out, and way to do this.

[chris.arceneaux]

Hi Kristian,

Have you tried Joe's last suggestion?

...just use the GET method for jobs first and you will see the format of an existing full object that you need to use.

To do this, create a job manually in the VBR console with the settings that you desire. Then, retrieve the Job settings using the API:

GET - /api/v1/jobs/{id}

[ksl28]

Hi,

Yup - and all values are presented nicely.
But when i look over my JSON object with all the required parameters defined, i cant seem to figure out why, its not working.

Btw - Thanks for the help so far! Much appreciated!

[chris.arceneaux]

Just attempted in my lab and it appears that creating a Backup Job with vSphere Tags is not supported in this version of the API. See the error I received below:

Code: Select all

{
    "errorCode": "UnknownError",
    "message": "Type Tag is not supported",
    "resourceId": null
}

I've submitted a request for our API documentation to be updated to make this known.

To help you or others having issues creating Backup Jobs using the VBR API in the future, here's detailed steps to get a sample job configuration from an already existing Backup Job and how to use it to create a net new job with an identical configuration:

1. Create Backup Job using VBR console
2. Retrieve Job setting using Veeam API
3. Remove excess response data keeping just the job payload information. If you're unsure which is which, compare with our documentation.
4. Remove the id field
5. Restructure the "virtualMachines"."includes" statement:
   • From this:

     Code: Select all

     "includes": [
         {
             "inventoryObject": {
                 "type": "Folder",
                 "hostName": "vc.arsano.lab",
                 "name": "vmware",
                 "objectId": "group-v42"
             },
             "size": "31.3 GB"
         }
     ],
     

     To this:

     Code: Select all

     "includes": [
         {
             "type": "Folder",
             "hostName": "vc.arsano.lab",
             "name": "vmware",
             "objectId": "group-v42"
         }
     ],
     

6. Do the same thing as the previous step for "virtualMachines"."excludes" statement
7. Update the name and description for the job
8. Use the altered payload to create a Backup Job

This might seem like a lot of steps but, in JSON, a job configuration can be a few hundred lines of code. It's SUPER easy in comparison and demonstrates the power of the VBR API.

[jhoughes]

The limitation on object type is documented at the top of the Jobs section of the REST API documentation, we even requested an edit to make the language a bit more clear:

NOTE
In the current version, the REST API supports only jobs of the Backup type that include only VMware vSphere objects.

[ksl28]

Thanks alot!!!!! I really appreciate the effort!
My issue is that we dont have any existing jobs on the VBR servers, so we need to define all the settings in the JSON statement / Powershell script, and built the logic there.

So do you perhaps have an PS example, of how you normally create the jobs?

[oleg.feoktistov]

Hi Kristian,

Have you checked what $JobNameBody variable holds as soon as the hashtable is converted to json?
I assume that the main reason why the request fails is due to the hashtable not being formatted correctly.
If you want to include nested objects, you need to nest hashtables accordingly, not just specify properties by dots.
Here is the example of a formatted hashtable:

Code: Select all

$include = @{
      "type" = "tag"
      "hostName" = "vcenter.domain.com"
      "name" = "Backup_Job1_tag"
    }
$virtualMachines = @{
    "includes" = @($include)
}
$storage = @{
  "backupRepositoryId" = "1a2872d4-5924-4851-8b65-007336dd142d"
  "backupProxies" = @{
    "autoSelection" = $true
  }
  "retentionPolicy" = @{
    "type" = "Days"
    "quantity" = 14
  }
}

$vss = @{
  "appAwareProcessing" = @{
    "isEnabled" = $false
  }
  "guestFSIndexing" = @{
    "isEnabled" = $false
  }
}
$schedule = @{
  "runAutomatically" = $false
}

$JobNameBody = @{
    "name" = "Test Job"
    "description" = "Backup Job"
    "type" = "Backup"
    "isHighPriority" = $false
    "virtualMachines" = $virtualMachines
    "storage" = $storage
    "guestProcessing" = $vss
    "schedule" = $schedule
  } | ConvertTo-Json -Depth 3 

Make sure to use ConvertTo-Json with -Depth parameter to have your nested hashtables converted correctly.
Depth value would depend on how deep hashtables are nested.
Also, if you enable guestProcessing options, guestCredentials property becomes required.

Thanks,
Oleg

[ksl28]

Hi Oleg,
Thanks a million times! You just saved me from loosing all my - thanks!

Your example makes perfect sense, and the job is created with success!
My only issue now, is that even that the $JobNameBody looks like this:

Code: Select all

$JobNameBody
{
    "storage":  {
                    "backupProxies":  {
                                          "autoSelection":  true
                                      },
                    "retentionPolicy":  {
                                            "quantity":  14,
                                            "type":  "Days"
                                        },
                    "backupRepositoryId":  "1a2872d4-5924-4851-8b65-007336dd142d"
                },
    "name":  "Test Job",
    "type":  "Backup",
    "description":  "Backup Job",
    "schedule":  {
                     "runAutomatically":  false
                 },
    "isHighPriority":  false,
    "virtualMachines":  {
                            "includes":  [
                                             {
                                                 "name":  "KRLE_TEST1",
                                                 "hostName":  "vcenter.domain.com",
                                                 "type":  "VirtualMachine"
                                             }
                                         ]
                        },
    "guestProcessing":  {
                            "guestFSIndexing":  {
                                                    "isEnabled":  false
                                                },
                            "appAwareProcessing":  {
                                                       "isEnabled":  false
                                                   }
                        }
}

The job is then created with an Folder type and Datacenters as name (ive doublechecked the JobID is correct):

Code: Select all

$(Invoke-RestMethod -Method Get -Uri "https://dkhovbr:9419/api/v1/jobs/1bf4baa9-5356-4d44-928b-0c7391cab9ef" -Headers $GlobalHeaders -ContentType "application/json").virtualMachines.includes.inventoryObject | Select-Object type,name
type   name
----   ----
Folder Datacenters

I will try to figure out why - but thanks again!

[jhoughes]

Each object sent in under the virtual machine hashtable needs to have the ID added, not just the name.

If you don't have the MoRef IDs already, you should really run the GET method for the virtual machine objects first, to make sure you are using the correct inventory details that Veeam is aware of.

[oleg.feoktistov]

@chris.arceneaux, we amended the note on the supported job object types as per your feedback. Anyone wondering whether adding tags as job objects works in v11, please, see the link I shared. Tags are not yet supported, but we are planning to add it in vNext. Thanks!

[Joydip]

Case #05202840

Hello,

Kindly Open a discussion thread "Ability to Create Backup Job using Rest API".
Is there any Rest API for the above?

Please help and advise.

Thanks,
Joydip

[Natalia Lupacheva]

Hi Joydip,

First, speaking of Technical support, I see you don't have Case administrator rights, so please follow the instructions you've received from your Support engineer.
As for the REST API, have you tried with this method?

I think you might also be interested in the posts from this thread, could be a good thing to start with.

Thanks!

[Joydip]

To create backup job using RestAPI, I need to have a "access-token" using the HTTP POST request with the /api/oauth2/token.
If I use https://<server>:9398/api/oauth2/token (with proper header and credential) then getting 404 error.
What will be the base url for the above operation (access-token)?

[oleg.feoktistov]

The base url you are using is correct, but the port for VBR REST is 9419. Port 9398 is for EM REST. Thanks!

[Joydip]

I have created a backup job from client Veeam B&R console as a Server Agent. The job executed successfully and visible under Cloud Connect section (Last24 Hours) on Backup server's Veeam B&R. I used VBR Rest API Url "https://<server>:9419/api/v1/jobs" to get all jobs but the response is
{
"data": [],
"pagination": {
"total": 0,
"count": 0,
"skip": 0,
"limit": 200
}
}
Also did not get result from Veeam B&R Enterprise url.
Is it not possible to get result using the above VBR Rest API?

[oleg.feoktistov]

For starters, agent backup jobs are not supported in VBR REST API yet. In fact, the only supported type is VMware backup jobs. If none of these exist in your environment, makes sense that GET /jobs call returns response body with nothing in data property.
As for the cloud connect, if you are asking about tenant backup sessions reflected on SP's side, that's also yet to be covered in VBR REST. Thanks!

[Joydip]

If we use VBR Rest API then it only supported type is VMWare backup jobs.
Otherwise how we can create a backup job using Rest API like we can do from Veeam B&R console as a Server Agent, Workstation Agent, VM Agent?

[oleg.feoktistov]

Currently, the only way is via our Powershell module. If applicable in your case, have a look at this section. Thanks!