RESTful knowledge exchange
Post Reply
ksl28
Influencer
Posts: 18
Liked: never
Joined: Sep 21, 2016 8:31 am
Full Name: Kristian Leth
Contact:

Powershell - Create job through RestAPI

Post by 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
Product Manager
Posts: 18421
Liked: 1822 times
Joined: Oct 26, 2012 3:28 pm
Full Name: Vladimir Eremin
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Influencer
Posts: 18
Liked: never
Joined: Sep 21, 2016 8:31 am
Full Name: Kristian Leth
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Veeam Software
Posts: 272
Liked: 108 times
Joined: Apr 20, 2017 4:19 pm
Full Name: Joe Houghes
Location: Austin, TX
Contact:

Re: Powershell - Create job through RestAPI

Post by jhoughes » 1 person likes this post

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
Husband, Father, Solutions Architect, Geek Extraordinaire | @AustinVMUG & @ATXPowerShell leader | VMware vExpert | Cisco Champion

ksl28
Influencer
Posts: 18
Liked: never
Joined: Sep 21, 2016 8:31 am
Full Name: Kristian Leth
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Veeam Software
Posts: 272
Liked: 108 times
Joined: Apr 20, 2017 4:19 pm
Full Name: Joe Houghes
Location: Austin, TX
Contact:

Re: Powershell - Create job through RestAPI

Post by 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.
Husband, Father, Solutions Architect, Geek Extraordinaire | @AustinVMUG & @ATXPowerShell leader | VMware vExpert | Cisco Champion

ksl28
Influencer
Posts: 18
Liked: never
Joined: Sep 21, 2016 8:31 am
Full Name: Kristian Leth
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Veeam Software
Posts: 385
Liked: 207 times
Joined: Jun 24, 2019 1:39 pm
Full Name: Chris Arceneaux
Location: Kentucky, USA
Contact:

Re: Powershell - Create job through RestAPI

Post by chris.arceneaux »

Hi Kristian,

Have you tried Joe's last suggestion?
jhoughes wrote: May 04, 2021 4:59 pm ...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
Influencer
Posts: 18
Liked: never
Joined: Sep 21, 2016 8:31 am
Full Name: Kristian Leth
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Veeam Software
Posts: 385
Liked: 207 times
Joined: Jun 24, 2019 1:39 pm
Full Name: Chris Arceneaux
Location: Kentucky, USA
Contact:

Re: Powershell - Create job through RestAPI

Post by 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. :D

jhoughes
Veeam Software
Posts: 272
Liked: 108 times
Joined: Apr 20, 2017 4:19 pm
Full Name: Joe Houghes
Location: Austin, TX
Contact:

Re: Powershell - Create job through RestAPI

Post by 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.
Husband, Father, Solutions Architect, Geek Extraordinaire | @AustinVMUG & @ATXPowerShell leader | VMware vExpert | Cisco Champion

ksl28
Influencer
Posts: 18
Liked: never
Joined: Sep 21, 2016 8:31 am
Full Name: Kristian Leth
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Veeam Software
Posts: 904
Liked: 319 times
Joined: Sep 25, 2019 10:32 am
Full Name: Oleg Feoktistov
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Influencer
Posts: 18
Liked: never
Joined: Sep 21, 2016 8:31 am
Full Name: Kristian Leth
Contact:

Re: Powershell - Create job through RestAPI

Post by 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
Veeam Software
Posts: 272
Liked: 108 times
Joined: Apr 20, 2017 4:19 pm
Full Name: Joe Houghes
Location: Austin, TX
Contact:

Re: Powershell - Create job through RestAPI

Post by 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.
Husband, Father, Solutions Architect, Geek Extraordinaire | @AustinVMUG & @ATXPowerShell leader | VMware vExpert | Cisco Champion

Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest