How to access Citrix Monitor Service data using the OData v4 endpoint in Citrix Cloud

Use the OData version 4 endpoint based on ASP .Net Web API to access the Citrix Monitor Service data. It supports pagination and OData v4 endpoints return a maximum of 1000 records per page with a link to the next 1000 records. You can run aggregation queries on the Citrix Monitor Service data. This feature was not available in OData Version 3 or earlier.

To access the Citrix Monitor Service data, follow the prerequisites, use cases and walkthroughs of OData APIs and Powershell SDKs, and different access methods.

You can make API requests using the MS Excel PowerQuery, C#, PowerShell, or any tool that support invoking the REST API.

Prerequisites to access Citrix Monitor Service data using the OData v4 endpoint in Citrix Cloud

• Know the supported endpoints
• Generate Citrix Cloud bearer token. For more information, see Get started with Citrix Cloud APIs section.

Note:

For maintaining the service quality and preventing abuse, the service enforces a request concurrency limitation. If multiple concurrent requests are issued, new requests may fail with the “429 Too Many Requests” status code. In such a scenario, fine-tune the script, increase the number of retries, extend the interval between queries, or simplify the query.

Supported API Gateway endpoints

Use one of the following endpoints based on the geographical region you selected while accessing the Citrix Monitor Service data:

• US/EU/AP-S region:https://api.cloud.com/monitorodata
• Japan region: https://api.citrixcloud.jp/monitorodata

Note:

• The https://{Customer_Id}.xendesktop.net/Citrix/monitor/odata/v4/data URL is replaced with https://api.cloud.com/monitorodata. The HTTP header “Customer” is now replaced with “Citrix-CustomerId”.
• For Japan, the https://{Customer_Id}.apps.citrixworkspacesapi.jp/Citrix/monitor/odata/v4/data URL is replaced with new Gateway Endpoint https://api.citrixcloud.jp/monitorodata. The HTTP header “Customer” is now replaced with “Citrix-CustomerId”.
• For Government customers, the existing URLs and header name (Customer) remain unchanged.

HTTP error codes

See HTTP error codes to know about the various error codes and their descriptions.

Generate Citrix Cloud bearer token

In this section, a few methods are provided for obtain a Citrix Cloud bearer token.

Note:

The Citrix Cloud bearer tokens expire after 1 hour for security reasons. For scheduled API requests, please plan for a periodic token refresh.

Method 1: Citrix DaaS Remote PowerShell SDK

Generate Citrix Cloud bearer token using Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) PowerShell SDK as follows:

1. Download the Remote PowerShell SDK from the Citrix downloads page.
2. Install the SDK on any computer in your resource location.
3. Open a PowerShell command prompt. (administrator rights are not required)
4. Add the Citrix snap-ins: asnp citrix*.
5. Execute the cmdlet, Get-XDAuthenticationEx, it prompts you for Citrix Cloud authentication.
6. On successful authentication, the bearer token is stored in the current PowerShell session.
7. Execute the cmdlet, Get-Variable to list all the variables in the current PowerShell session.
8. The list contains a variable, Global:XDSerializedNonPersistentMetadata containing bearer token as value.
9. Copy the bearer token value to be used in the OData query.

Method 2: Citrix Cloud API service

You may obtain the bearer token using the Citrix Cloud APIs. For more information on the steps, see getting started section.

Method 3: Using an API tool like Postman

With an API tool like Postman, you can obtain a valid bearer token, by issuing a POST request like the following:

The placeholder variables customer_id, citrix-cloud-client-id and citrix-cloud-client-secret should be replaced with the customer ID and the Citrix Cloud API client ID and secret.
This request is part of a broader Postman collection, available at Monitor Service OData Postman Collection.

Method 4: Using PowerShell and the Citrix Cloud API

Using PowerShell, you can obtain or refresh a bearer token with an implementation like the following:

Function Get-BearerToken {
    param (
        [Parameter(Mandatory=$true)][string]
        $clientId,
        [Parameter(Mandatory=$true)][string]
        $clientSecret
    )
    [string]$bearerToken = $null
    [hashtable]$body = @{
        'grant_type' = 'client_credentials'
        'client_id' = $clientId
        'client_secret' = $clientSecret
    }
    $response = $null
    $response = Invoke-RestMethod -Uri 'https://api.cloud.com/cctrustoauth2/root/tokens/clients' -Method POST -Body $body
    if( $null -ne $response ) {
        $bearerToken = "CWSAuth bearer=$($response | Select-Object -expandproperty access_token)"
    }
    $bearerToken
}
<!--NeedCopy-->

In the above snippet, you can replace the API endpoint based on your region.
The function can be called as follows:

> Get-BearerToken -clientId "CLIENT_ID" -clientSecret "CLIENT_SECRET"
<!--NeedCopy-->

The CLIENT_ID and CLIENT_SECRET values can be obtained following the instructions provided in the getting started section of the Citrix Cloud API documentation.

Method 4: Using a Client Library and the Citrix Cloud API

C#/.NET

Sample code:

namespace ODataTokenGenerator
{
    class Program
    {
        private static readonly HttpClient httpClient = new HttpClient();
        static async Task Main()
        {
            try
            {
                var values = new Dictionary<string, string> {
                    { "grant_type", "client_credentials" },
                    { "client_id", "CLIENT_ID" },
                    { "client_secret", "CLIENT_SECRET" }
                };
                var content = new FormUrlEncodedContent(values);
                var url = "https://api.cloud.com/cctrustoauth2/CUSTOMER_ID/tokens/clients";
                var response = await httpClient.PostAsync(url, content);
                response.EnsureSuccessStatusCode();
                var responseString = await response.Content.ReadAsStringAsync();
                var responseObject = JsonConvert.DeserializeObject<AuthResponse>(responseString);
                Console.WriteLine(responseObject.access_token);
            }
            catch (HttpRequestException e)
            {
                Console.WriteLine("Message :{0} ", e.Message);
            }
        }
    }
}
<!--NeedCopy-->

Replace the placeholder values of CLIENT_ID, CLIENT_SECRET with the Citrix Cloud client details. Same for the CUSTOMER_ID.

Python

Sample code:

import requests
import json

customer_id = "CUSTOMER_ID"
url = f"https://api.cloud.com/cctrustoauth2/{CUSTOMER_ID}/tokens/clients"

payload = {
    "grant_type": "client_credentials",
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET"
}

headers = {
    "Accept": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
response_json = json.loads(response.text)
print(response_json["access_token"])
<!--NeedCopy-->

Replace the placeholder values of CLIENT_ID, CLIENT_SECRET with the Citrix Cloud client details. Same for the CUSTOMER_ID.

Monitor Service API specification

For the details of the Monitor Service schema, see API Exploration.

To determine the values returned by the Monitor Service OData API, see API Exploration.

The list of URLs for available data sets is available at URLs for Available Data Sets.

Use cases and walk-through of OData APIs and PowerShell SDK

Here’s a video explaining the various use cases of OData APIs and PowerShell SDK used in Citrix DaaS.

Different methods to access Citrix Monitor Service data using the OData v4 endpoint in Citrix Cloud

A detailed list of methods for accessing Citrix Monitor Service data using the OData v4 API endpoint can be found under the Data Access Methods page. Several examples of OData queries are also provided under the Examples section.