VEM API licensing and linking jobs to backups

[billcouper]

One of the Veeam-powered services we provide is VeeamBR backup for customers that host VM's in our VMware environment. We have one VeeamBR server, with individual backup jobs for each customer. We bill each customer for licensing individually, as well as for the size of their backup files on disk. Currently using a PowerShell script to generate the billing reports, however we are now going through a migration push to use API for everything possible :/

I have looked at both the VBR API and the VEM API... the Veeam Enterprise Manager API seems to have most of the data that I need... but I am struggling with a couple of things...

1. Linking a 'job' to a 'backup'
How do I link a job to a backup? There is info I need from the job object, as well as the backup object, but then I struggle to link these together... the backup name isn't always the same as the job name and I don't see any links between the two.

2. Objects in a 'job' or 'backup'
How to easily get a list of VMs in a VM Backup job? We target jobs to VM folders and/or resource pools. I need the list of VM's backed up by the job, not the name of the folder targeted. I know I can dig into the task sessions but this seems overly cumbersome to answer such a seemingly simple and I expect common question.

3. Licensed VM list
Once I have a list of VM's for each job/backup I need to identify which VM's are licensed - how many licenses do I charge customer with job "backup job 1" for example.


When getting the size of backup files on disk for a 'backup' I also expose the name of each backup file on disk. Currently I am doing a regex on the backup file name to pull the VM name and the Date, then using that info to build the list of unique VM names per backup and which VM's have restore points <31d old (needs a license). This seems unreliable to say the least and I am sure there is a much better way to get the information I need!

What I'd really like is a way to map backup jobs to companies in the Veeam Service Provider Console, then have it spit out the license/size info I need... but that's a feature request for another forum

[Mildur]

Hi Bill

Let me check the answers for your questions and come back to you when I have them.

What I'd really like is a way to map backup jobs to companies in the Veeam Service Provider Console, then have it spit out the license/size info I need... but that's a feature request for another forum

We have already some request for the VSPC.
Coming from a Service Provider to Veeam, my personal preferences would be leveraging the VSPC to bill customers in a hosted environment.

[Mildur]

Hi Bill

Would it be ok, to use RestAPI from the VSPC to get the information you need? It looks like only two steps are needed to get a list of all protected VMs and their Restore Point Size. And you can use the attribut latestRestorePointDate to calculate if the vm was backed up in the last 31 days to check if it need to be licensed or not.

1) Get a list of all backup Jobs on your Hosted VBR Server (filtered by Backup Server ID):
https://helpcenter.veeam.com/docs/vac/r ... obByServer

• "backupServerUid": "1e40c44a-a023-467b-93c6-b69524ece61d",

• "instanceUid": "784a3a14-b744-4322-a782-10f41d8bd689"

• "name": "srv3iBackupCopyJob"

2) When you have the List of all backup jobs, use the Job instanceUid to get all all backups listed for that job:
https://helpcenter.veeam.com/docs/vac/r ... ineBackups

• "virtualMachineUid": "69765040-af7a-1490-a699-1ce08cfe68e6"

• "jobUid": "784a3a14-b744-4322-a782-10f41d8bd689"

• "backupType": "Backup"

• "totalRestorePointSize": 1634304

• "restorePoints": 1

• "latestRestorePointDate": "2021-08-15T03:54:23.030Z"

[oleg.feoktistov]

Hi Bill,

Regarding EM REST API:

1. Unfortunately, currently there are no other approaches other than implicitly cross-reference them by name. What would make it clearer is if JobUId property existed in backup model. I noted it as an enhancement request.

2. If you need job objects not yet backed up, you can query job includes using GET /jobs/{id}/includes.
If you need vm list in a backup, you could get vm restore points using GET /vmRestorePoints inside each backup's restore point and filter unique VmName properties.

3. That kind of report is not currently available via EM REST API.

Thanks,
Oleg

[billcouper]

Thanks for the responses Mildur and Oleg.

It looks like Mildur's suggestion to filter /protectedWorkloads/virtualMachines by the jobUid is going to work. The request for one of the backup jobs looks like this

Code: Select all

GET https://vemserver:1280/api/v3/protectedWorkloads/virtualMachines?filter=[{"property":"jobUid","operation":"equals","value":"e6015719-68dd-4761-b913-fbcdd99e4a0d"}]

We will do our own calculation for license requirement based on restore points newer than 31 days. Let's say I run my script to pull the data from API at 8am... do I need to calculate the -31 days from current time, or from midnight 8 hours earlier, or something else entirely?

[billcouper]

While working on this I have a strange "issue" perhaps. Protected workloads for backup copy jobs are not displayed correctly when there are multiple copies of the same workloads - it only shows each workload once.

Consider a hosted customer with the following jobs:
* Backup to flash storage (7 days)
* Backup copy to HDD storage (GFS)
* Backup copy to offsite HDD storage (GFS)

When I pull the data from VSPC API, neither of the GFS jobs has a complete view of their protected data - indeed, I have to COMBINE the figures from both to get any semblance of normality. For example, if a customer has 22 VM's backed up to flash storage, and we have two copy jobs that copy everything to the two GFS storage pools using a total of 2200GB space on each pool, one of the jobs might say it protects 2 VM's 200GB and the other says it protects 20VM's 2000GB. In reality both jobs protect the same number of VM's and should have "roughly" the same amount of space used. Of course we can combine the numbers and then double the storage figure... but that won't always work in a case where one job failed and a restore point was missed, or some other scenario where the size can differ.

edit: In the web UI if I browse into Protected Data > Virtual Machines, and I find one of the virtual machines that only appears in one job via the API... It shows 'Backup Copies' as "2" and when I click that it correctly identifies the two jobs, and both show the correct 'Backup Size' value that this VM uses in both storage pools.

[Mildur]

Hi Bill

Thanks, looks unexpected. The values should be the same.
I'll try to have a look at it in my lab.

Thanks.
Fabian

[billcouper]

I've been poking around some more this afternoon and found that if I go about it from the opposite end, I might get the results I need. I will validate the output tomorrow but it looks promising.

First try that produced unusual results: Backup Server Jobs > Protected VMs

Code: Select all

GET https://$vemserver:1280/api/v3/infrastructure/backupServers/$backupServerUid/jobs?filter=[{"operation":"or","items":[{"property":"name","operation":"contains","collation":"ignorecase","value":"Local Copy"},{"property":"name","operation":"contains","collation":"ignorecase","value":"Offsite Copy"}]}]
GET https://$vemserver:1280/api/v3/protectedWorkloads/virtualMachines?filter=[{"property":"jobUid","operation":"equals","value":"$jobUid"}]

Second try that looks promising: Backup Server Protected VMs > VM Backups > Jobs

Code: Select all

GET https://$vemserver:1280/api/v3/protectedWorkloads/virtualMachines?filter=[{"property":"backupServerUid","operation":"equals","value":"$backupServerUid"}]
GET https://$vemserver:1280/api/v3/protectedWorkloads/virtualMachines/$virtualMachineId/backups?filter=[{"property":"backupType","operation":"equals","value":"BackupCopy"}]
GET https://$vemserver:1280/api/v3/infrastructure/backupServers/jobs/$jobUid

[Mildur]

Hi Bill

Can you use the output, everything as expected?
I don't have it tested in my lab yet.

Thanks
Fabian

[billcouper]

Hi Fabian,

Yes, the output looks much better and it looks usable.

[Mildur]

Hi Bill
Perfect. I'm glad you found a way to do it with the VSPC.

Fabian

[afokkema]

1. Linking a 'job' to a 'backup'
How do I link a job to a backup? There is info I need from the job object, as well as the backup object, but then I struggle to link these together... the backup name isn't always the same as the job name and I don't see any links between the two.

We have the same issue and documented our findings here: restful-api-f30/backup-api-job-relation ... 81251.html