Developer Documentation

Citrix Virtual Apps and Desktops REST APIs

How to use paging to query many objects through multiple API calls

July 19, 2024

Contributed by:

Y C

Use REST APIs to query many objects that exceed the MaxRecordCount limit using paging.

Follow the prerequisites and examples to get started with this API.

You can make API requests using the PowerShell code, C# code, Python, or any tool that supports invoking the REST API.

Prerequisites to use paging to query many objects

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.
Invoke the API described in this document from a client host.

Query many objects using any REST API tool

The following example describes how to query many machines which exceed the MaxRecordCount limit using paging. The maximum record count of the allowed is 1000 machines. For other types of site objects, apply this loop on a different request API.

If a query did not fully return the results due to a limit, the response includes a ContinuationToken string.

To obtain more results from the query, pass the ContinuationToken query parameter back into the same query to get the next batch of results. Repeat this step until the ContinuationToken value in response is null, indicating there’re no more unreturned results.

The continuationToken parameter is supported for all APIs that perform query or search on a large quantity of objects.

Request 1

GET https://[DdcServerAddress]/cvad/manage/Machines?limit=1000 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
<!--NeedCopy-->

Response 1

HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 7230586
content-Type: application/json; charset=utf-8
date: "Mon, 08 Nov 2021 14:48:51 GMT"
Server: Citrix Systems, Inc.

{
    "Items": [
        {
            "Id": "cf8582de-61dd-4c61-9649-636004c89907",
            "Uid": 1,
            ...
            "Name": "DEVPORTAL\\OrchVM-000001",
            ...
        },
        {
            "Id": "8bd7c72f-1a4c-4e00-ae4f-bf2eb34457f9",
            "Uid": 2,
            ...
            "Name": "DEVPORTAL\\OrchVM-000002",
            ...
        },
        ...
        {
            "Id": "f017d4ff-fdca-4e0d-bb55-9f72f000a3be",
            "Uid": 1000,
            ...
            "Name": "DEVPORTAL\\OrchVM-001000",
            ...
        }
    ],
    "ContinuationToken": "T7UhcehawR8PBTpc-tszgA=="
}
<!--NeedCopy-->

Request 2

GET https://[DdcServerAddress]/cvad/manage/Machines?limit=1000&continuationtoken=T7UhcehawR8PBTpc-tszgA%3d%3d 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
<!--NeedCopy-->

Response 2

HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 7219243
content-Type: application/json; charset=utf-8
date: "Mon, 08 Nov 2021 14:49:13 GMT"
Server: Citrix Systems, Inc.

{
    "Items": [
        {
            "Id": "0bc13b4d-e82e-4e07-ae31-fe180ad91cb7",
            "Uid": 1001,
            ...
            "Name": "DEVPORTAL\\OrchVM-001001",
            ...
        },
        {
            "Id": "5e68b873-0fda-4045-80f4-fb79d7a320ab",
            "Uid": 1002,
            ...
            "Name": "DEVPORTAL\\OrchVM-001002",
            ...
        },
        ...
        {
            "Id": "cf314e6e-0ec6-47ba-aa77-88b63d4827bb",
            "Uid": 2000,
            ...
            "Name": "DEVPORTAL\\OrchVM-02000",
            ...
        }
    ],
    "ContinuationToken": "3EOYomxNlavb8GhMCzr7wg=="
}
<!--NeedCopy-->

Request 3

GET https://[DdcServerAddress]/cvad/manage/Machines?limit=1000&continuationtoken=3EOYomxNlavb8GhMCzr7wg%3d%3d 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
<!--NeedCopy-->

Response 3

HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 2830950
content-Type: application/json; charset=utf-8
date: "Mon, 08 Nov 2021 14:53:57 GMT"
Server: Citrix Systems, Inc.

{
    "Items": [
        {
            "Id": "a829c80b-6b5b-461f-85f6-1f2c0aacf39f",
            "Uid": 2001,
            ...
            "Name": "DEVPORTAL\\OrchVM-002001",
            ...
        },
        {
            "Id": "d8d676be-34a2-4d39-9467-12b65599e730",
            "Uid": 2002,
            ...
            "Name": "DEVPORTAL\\OrchVM-002002",
            ...
        },
        ...
        {
            "Id": "af3fef40-d8a3-450c-a8ab-61f25a0ea520",
            "Uid": 2385,
            ...
            "Name": "DEVPORTAL\\OrchVM-02385",
            ...
        }
    ],
    "ContinuationToken": null
}
<!--NeedCopy-->

Query many objects using PowerShell

Learn from the following example to query many objects using any PowerShell code.

function GetMachinesInSiteWithPaging {
    param (
        [Parameter(Mandatory=$true)]
        [string] $customerid,
        [Parameter(Mandatory=$true)]
        [string] $siteid,
        [Parameter(Mandatory=$true)]
        [string] $bearerToken
    )
    $requestUri = "https://[DdcServerAddress]/cvad/manage/Machines?limit=1000"
    $headers = @{
        "Accept" = "application/json";
        "Authorization" = "CWSAuth Bearer=$bearerToken";
        "Citrix-CustomerId" = $customerid;
        "Citrix-InstanceId" = $siteid;
    }

    $response = Invoke-RestMethod -Uri $requestUri -Method GET -Headers $headers

    while ($response.ContinuationToken -ne $null)
    {
        $requestUriContinue = $requestUri + "&continuationtoken=" + $response.ContinuationToken
        $responsePage = Invoke-RestMethod -Uri $requestUriContinue -Method GET -Headers $headers
        $response.Items += $responsePage.Items
        $response.ContinuationToken = $responsePage.ContinuationToken
    }

    return $response
}

$customerid = "customer1"
$siteid = "61603f15-cdf9-4c7f-99ff-91636601a795"
$bearerToken = "ey1.."
$response = GetMachinesInSiteWithPaging $customerid $siteid $bearerToken
<!--NeedCopy-->

Query many objects using C#

Learn from the following example to query many objects using any C# code.

public static async Task<MachineResponseModelCollection> GetMachinesInSiteWithPaging(
    string customerid,
    string siteid,
    string bearerToken)
{
    var requestUri = "https://[DdcServerAddress]/cvad/manage/Machines?limit=1000";
    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 response = await client.GetAsync(requestUri);

        if (response != null)
        {
            var content = await response.Content.ReadAsStringAsync();
            MachineResponseModelCollection machines = JsonConvert.DeserializeObject(content);
            var continuationToken = machines.ContinuationToken;
            
            while (machines.continuationToken != null)
            {
                var requestUriContinue = requestUri + "&continuationtoken=" + continuationToken;
                response = await client.GetAsync(requestUriContinue);
                content = await response.Content.ReadAsStringAsync();
                MachineResponseModelCollection machinePage = JsonConvert.DeserializeObject(content);
                machines.Items.Addrange(machinePage.Items);
                machines.continuationToken = machinePage.ContinuationToken;
            }
            
            return machines;
        }

        return null;
    }
}
<!--NeedCopy-->

Query many objects using Python

Learn from the following example to query many objects using any Python code.

import requests

def get_machines_in_site(bearerToken, customerid, siteid):
    request_uri = "https://[DdcServerAddress]/cvad/manage/Machines"
    headers = {
                'Authorization': 'CWSAuth Bearer=%s' % bearerToken,
                'Citrix-CustomerId': customerid,
                'Citrix-InstanceId': siteid,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
              }

    response = requests.get(request_uri, headers = headers).json()
    while response.ContinuationToken is not None:
        request_uri_page = request_uri + "&continuationtoken=" + continuation_token
        response_page = requests.get(request_uri_page, headers = headers).json()
        response.Items += response_page.Items
        response.ContinuationToken = response_page.ContinuationToken

    return response.json()
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

Citrix Virtual Apps and Desktops REST APIs OpenAPI Specification

Copy Download

How to use paging to query many objects through multiple API calls

July 19, 2024

Contributed by:

Y C

July 19, 2024

Contributed by:

Y C

How to use paging to query many objects through multiple API calls

Prerequisites to use paging to query many objects

Query many objects using any REST API tool

Request 1

Response 1

Request 2

Response 2

Request 3

Response 3

Query many objects using PowerShell

Query many objects using C#

Query many objects using Python

Resources

Citrix Virtual Apps and Desktops REST APIs OpenAPI Specification

In this article

Resources

Citrix Virtual Apps and Desktops REST APIs OpenAPI Specification