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.
Note:
Accessing Citrix Monitor Service data using the OData v4 endpoint in Citrix Cloud is currently under preview.
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 withhttps://{ApiGatewayEndpoint}
. 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 Endpointhttps://api.citrixcloud.jp
. 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
You can obtain the bearer token using either of the following methods:
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:
- Download the Remote PowerShell SDK from here.
- Install the SDK on any computer in your resource location.
- Open a PowerShell command prompt. (administrator rights are not required)
- Add the Citrix snap-ins:
asnp citrix*
. - Execute the cmdlet,
Get-XdAuthentication
, it prompts you for Citrix Cloud authentication. - On successful authentication, the bearer token is stored in the current PowerShell session.
- Execute the cmdlet,
Get-Variable
to list all the variables in the current PowerShell session. - The list contains a variable,
GLOBAL:XDAuthToken
containing bearer token as value. - 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.
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. Replace http://{dc-host}/Citrix/Monitor/OData/v4/Data
with https://{ApiGatewayEndpoint}
.
Use cases and walk-through of OData APIs ands 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
Access Citrix Monitor Service data using MS Excel PowerQuery
Learn from the following example to access the Citrix Monitor Service data using MS Excel PowerQuery.
-
Open Excel (Excel 2016 has PowerQuery inbuilt. If you are using earlier versions of Excel, install PowerQuery. For more information, see Microsoft documentation.
-
In Excel 2016, go to Data menu > Get & Transform group > New Query > From Other Sources > click Blank Query
-
In the Query Editor window, go to Home menu > Query group > click Advanced Editor.
-
In the Advanced Editor window, type the following query:
let Source = OData.Feed ( "https://{ApiGatewayEndpoint}/Machines", null, [ Headers = [ #"Authorization" = "<YourToken>", #"Citrix-CustomerId" = "<YourCustomerId" ] ] ) in Source <!--NeedCopy-->
Replace
<YourCustomerId>
and<YourToken>
with the values of CustomerID and bearer token you obtained as described in the Generate the Citrix Cloud bearer token section. Make sure that the<YourToken>
is in the format,CWSAuth bearer= <bearer token>
. Once the No Syntax errors have been detected is displayed in the bottom of the window, click Done. -
In case of first login, a specify how to connect message is displayed. Click Edit Credentials, the Access an OData feed window appears. Make sure that the Anonymous tab and the base URL are selected and click Connect.
-
Upon successful authentication, the results are displayed as a table. In this example, the table lists all the Machines of the CustomerId. If the authentication fails, either the bearer token or the CustomerId might be invalid. Verify the same and try again.
Access Citrix Monitor Service data using C# client library
Learn from the following example to access the Citrix Monitor Service data using C#.
Steps to access Citrix Monitor Service data using C#:
- Create a C# client for an OData v4 endpoint using a Simple.OData.Client. For information about installation of its Nuget Package, see Github documenetation.
-
Install the package using the Nuget Package Manager:
Install-Package Simple.OData.Client <!--NeedCopy-->
-
After installation, use the package with the following command:
using Simple.OData.Client; <!--NeedCopy-->
-
As the OData query in the Cloud requires the Citrix Cloud authentication, the OData clients must pass the bearer token (as documented in the Generate the Citrix Cloud bearer token section) and the CustomerId. Set up the headers as follows, before creating the OData query:
ODataClientSettings settings = new ODataClientSettings(); settings.BeforeRequest += request => { request.Headers.Add("Authorization", "<BearerToken>"); request.Headers.Add("Citrix-CustomerId", "<customerId>"); }; settings.BaseUri = new Uri("https://{ApiGatewayEndpoint}"); client = new ODataClient(settings); <!--NeedCopy-->
-
Use async methods to retrieve data. The following example lists all machines from Citrix DaaS site.
public static async void GetMachines() { var machines = await client.FindEntriesAsync("Machines"); foreach(var machine in machines) { Console.WriteLine(machine["Id"]); } } <!--NeedCopy-->
Access Citrix Monitor Service data using PowerShell
Learn from the following example to access the Citrix Monitor Service data using PowerShell. This is a sample OData query triggered from PowerShell with the headers initialized and the Raw XML output redirected to a file:
```powershell
PS C:\> $headers = @{"Authorization" = "<BearerToken>”; "Citrix-CustomerId" = "<Your Customer Id>"}
PS C:\> $url = https://{ApiGatewayEndpoint}/Users
PS C:\> $result = Invoke-WebRequest -Uri $url -Headers $headers
PS C:\> $result.Content > <Path-to-Output-File>
<!--NeedCopy--> ```
Access Citrix Monitor Service data using any REST API tool
Learn from the following example to access the Citrix Monitor Service data using any REST API tool, for example Postman Chrome Ext.
- Install Postman from Chrome extensions. See https://chrome.google.com/webstore.
- Launch the application.
- Select GET in the dropdown and type in the URL to request.
- Insert headers with your token and customerId. Click Send.
- If authentication is successful, response data is seen in the Response section of Postman.
Use OData V4 aggregation queries in Citrix Monitor Service data
Aggregation queries were not supported in OData Version 3 and earlier. It is supported in OData Version 4. As per OData documentation, aggregation can be done using the $apply=aggregate()
field. The following are few examples that show data aggregation. Use them after https://{ApiGatewayEndpoint}/<TableName>
?$apply=aggregate
([column to aggregate] with [aggregation type] as [column to aggregate])
Aggregation Types:
-
Count :
Machines?$count=true
This gives the total number of machines.
-
Sum :
Sessions?$apply=aggregate(SessionType with sum as SessionType)
This gives the sum of session types in Sessions.
-
Min :
Machines?$apply=aggregate(LifecycleState with min as LifecycleState)
This gives the minimum of all the life cycle states.# Use OData pagination in Citrix Monitor Service data
Citrix Monitor supports OData pagination. All OData v4 endpoints return a maximum of 1000 records per page with a link to the next 1000 records. The following PowerShell script fetches applications in batches of 1000 records using Citrix Cloud authentication following the @odata.nextLink property in the response.
```powershell
$customerId = "[customerid]"
$api = "https://{ApiGatewayEndpoint}"
$endpoint = "$api/Applications"
$bearer = "CWSAuth bearer=[token]"
$headers = @{'Citrix-CustomerId'=$customerId;'Authorization'=$bearer}
$results = Invoke-RestMethod $endpoint -Headers $headers -Verbose
Write-Host “Number of items returned in the first call : ”, $results.value.Count
while($results.'@odata.nextLink' -ne $null)
{
$results = Invoke-RestMethod $results.'@odata.nextLink' -Headers $headers -Verbose
Write-Host "Number of items returned in next call : ", $results.value.Count
}
<!--NeedCopy--> ```
In this article
- Prerequisites to access Citrix Monitor Service data using the OData v4 endpoint in Citrix Cloud
- Supported API Gateway endpoints
- HTTP error codes
- Generate Citrix Cloud bearer token
- Different methods to access Citrix Monitor Service data using the OData v4 endpoint in Citrix Cloud
- Use OData V4 aggregation queries in Citrix Monitor Service data