Citrix Virtual Apps and Desktops REST APIs

How to use batch API to add machines to a catalog

The following how-to article describes the prerequisites and REST examples to add machines to a catalog using batch API.

Prerequisites to use batch API to add machines to a catalog

  • Read the Learning journey for Citrix Virtual Apps and Desktops APIs section to ensure that you have the bearer token.
  • Get siteid from How to get site id API.
  • Make sure your domain controller is connected to the DDC, and have unallocated machines.
  • The Body item in batch request body should be convert to a json format string.
  • Invoke the API described in this document from a client host or from the API exploration tab to add machines to a machine catalog.

Add machines to a catalog using any REST API tool

The following example illustrates how to add machines to a catalog using batch API.

Request

POST https://[DdcServerAddress]/cvad/manage/$batch HTTP/1.1 Accept: application/json Content-Type: application/json; charset=utf-8 Authorization: CWSAuth bearer=<token-from-prerequisites> Citrix-CustomerId: loy6oujtu6a4 Citrix-InstanceId: 22ded57c-0306-47e4-b6e8-fed6252759e1 { "Items": [ { "Reference": 0, "Method": "POST", "RelativeUrl": "/MachineCatalogs/CVAD_APIs_Physical_MC/Machines", "Body": "{\"MachineName\":\"ORCHPERFS2\\\\Ops2Machine-0002\"}" }, { "Reference": 1, "Method": "POST", "RelativeUrl": "/MachineCatalogs/CVAD_APIs_Physical_MC/Machines", "Body": "{\"MachineName\":\"ORCHPERFS2\\\\Ops2Machine-0003\"}" } ] }

Response

HTTP/1.1 200 OK citrix-transactionid: bba3ffc1... content-Length: 720 content-Type: application/json; charset=utf-8 date: "Thu, 17 Sep 2020 07:24:00 GMT" { "Items": [ { "Reference": "0", "Code": 202, "Headers": [ { "Name": "Location", "Value": "https://[DdcServerAddress]/cvad/manage/Jobs/3a5be100..." } ], "Body": null }, { "Reference": "1", "Code": 202, "Headers": [ { "Name": "Location", "Value": "https://[DdcServerAddress]/cvad/manage/Jobs/3a5be100..." } ], "Body": null } ] }

Add machines to a catalog using PowerShell

The following example illustrates how to add machines to a catalog using batch API.

function DoBatchRequest { param ( [Parameter(Mandatory=$true)] [string] $customerid, [Parameter(Mandatory=$true)] [string] $siteid, [Parameter(Mandatory=$true)] [string] $bearerToken, [Parameter(Mandatory=$true)] [string] $body ) $requestUri = "https://[DdcServerAddress]/cvad/manage/`$batch" $headers = @{ "Accept" = "application/json"; "Authorization" = "CWSAuth Bearer=$bearerToken"; "Citrix-CustomerId" = $customerid; "Citrix-InstanceId" = $siteid; } $response = Invoke-RestMethod -Uri $requestUri -Method POST -Headers $headers -Body $body return $response } $customerId = "customer1" $siteId = "61603f15-cdf9-4c7f-99ff-91636601a795" $bearerToken = "ey1.." $body = @" { "Items": [ { "Reference": 0, "Method": "POST", "RelativeUrl": "/MachineCatalogs/CVAD_APIs_Physical_MC/Machines", "Body": "{\"MachineName\":\"ORCHPERFS2\\\\Ops2Machine-0002\"}" }, { "Reference": 1, "Method": "POST", "RelativeUrl": "/MachineCatalogs/CVAD_APIs_Physical_MC/Machines", "Body": "{\"MachineName\":\"ORCHPERFS2\\\\Ops2Machine-0003\"}" } ] } "@ $response = DoBatchRequest $customerid $siteid $bearerToken $body

Add machines to a catalog using C# code

The following example illustrates how to add machines to a catalog using batch API.

public static async Task<string> DoBatchRequest( string customerid, string bearerToken, string siteid, BatchRequestModel model) { var requestUri = "https://[DdcServerAddress]/cvad/manage/$batch"; using (var client = new HttpClient()) { client.DefaultRequestHeaders.Accept.ParseAdd("application/json"); client.DefaultRequestHeaders.Add("Citrix-CustomerId", customerid); client.DefaultRequestHeaders.Add("Citrix-InstanceId", siteid); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("CWSAuth Bearer=" + bearerToken); var jsonBody = JsonConvert.SerializeObject(model, new JsonSerializerSettings { Converters = new JsonConverter[] { new StringEnumConverter() } }); var response = await client.PostAsync(requestUri, new StringContent(jsonBody, Encoding.UTF8, "application/json")); if (response != null) { var content = await response.Content.ReadAsStringAsync(); return content; } return null; } }

Add machines to a catalog using Python

The following example illustrates how to add machines to a catalog using batch API.

import requests def do_batch_request(bearerToken, customerid, siteid): request_uri = "https://[DdcServerAddress]/cvad/manage/$batch" headers = { 'Authorization': 'CWSAuth Bearer=%s' % bearerToken, 'Citrix-CustomerId': customerid, 'Citrix-InstanceId': siteid, 'Content-Type': 'application/json', 'Accept': 'application/json' } payload = json.dumps({ "Items": [ { "Reference": 0, "Method": "POST", "RelativeUrl": "/MachineCatalogs/CVAD_APIs_Physical_MC/Machines", "Body": "{\"MachineName\":\"ORCHPERFS2\\\\Ops2Machine-0002\"}" }, { "Reference": 1, "Method": "POST", "RelativeUrl": "/MachineCatalogs/CVAD_APIs_Physical_MC/Machines", "Body": "{\"MachineName\":\"ORCHPERFS2\\\\Ops2Machine-0003\"}" } ] }) response = requests.post(request_uri, headers = headers, verify = False, data = payload) return response.json()
Resources
Citrix Virtual Apps and Desktops REST APIs OpenAPI Specification
Copy Download
How to use batch API to add machines to a catalog