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\"}"
        }
    ]
}
<!--NeedCopy-->

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
        }
    ]
}
<!--NeedCopy-->

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 
<!--NeedCopy-->

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;
    }
}
<!--NeedCopy-->

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()
<!--NeedCopy-->
Resources
Citrix Virtual Apps and Desktops REST APIs OpenAPI Specification
Copy Download
How to use batch API to add machines to a catalog