【CVAD/DaaS】Citrix Directorの[傾向]データをMonitor Service APIで取得する

Citrix Directorには、[傾向]画面のデータを手動でエクスポートできる機能が標準で用意されていますが、定期的に自動でデータを取得したい場合や特定の項目だけを効率よく取り出したい場合には、Citrixが提供している Monitor Service API を活用することで手作業を減らすことができます。

本記事では、Monitor Service API から取得できる具体的なパラメータと、それらが Citrix Director のどの画面情報に対応しているのかを整理しながら、PowerShell を使った取得例や出力結果も交えて解説します。

PowerShell やスクリプトによる自動化を検討されている方や、Citrix 環境の運用をより効率化したい方はぜひ参考にしてください。

1. Citrix Monitor Service APIとは？

Citrix Monitor Service API は、Citrix Virtual Apps and Desktops (CVAD) や Citrix DaaS 環境の監視データを取得できるREST形式のAPIです。 Directorの画面で確認できるようなセッション数や接続状況、ログオン時間などの情報を、ODataプロトコルを通じて外部ツールやスクリプトから取得できます。

1.1：Citrix Monitor Service APIのアーキテクチャの違い

CVAD

Monitor Service API は OData v4 に準拠しており、HTTP 経由でクエリを送信して
Citrix環境の監視データを取得できます。

DaaS

DaaS環境では、地域ごとに異なる API エンドポイントが用意されています。

1.2：データアクセス手順 (PowerShell)

公式ドキュメントには、CVAD/DaaS環境で PowerShell を使用してCitrix Monitor Service データにアクセスする方法 (JSON 形式での出力)が記載されており、今回の手順もこちらのサイトを参考にしています。

◆参考： developer-docs.citrix.com

なお、CVAD 環境と DaaS 環境では、 API の認証方式やアクセス方法が異なりますが、基本的なデータ構造は共通しています。ただ、利用できるデータセットの数や項目が一部異なり、DaaS 環境の方がより詳細な情報が含まれます。

2. Director「傾向」画面のデータをMonitor Service APIから取得する

Citrix Directorの「傾向」画面は、 Citrix環境の利用状況やパフォーマンスの変化を把握するためによく使われます。本章では、その画面で確認できる情報と同等のデータをMonitor Service APIを使って取得する方法を紹介します。

2.1：同時セッション数

Directorの「傾向」画面内の監視項目について、Citrixから提供されているAPIエンドポイントから必要なデータを抽出する方法についてまとめていきます。

同時セッション数は、Directorの「傾向」画面一番左の [セッション] タブから確認できます。この画面ではユーザーのセッション状況が時系列で確認でき、画面中央に同時セッション数の推移グラフが表示されます。

グラフには以下の情報が表示されます。

同時セッション数
接続セッション数
切断セッション数

※ [デリバリーグループ] [期間]フィルターを適用して、デフォルトの表示範囲から変更できます

■ グラフデータのエクスポート

画面右上の「エクスポート」機能からファイル形式をCSVに指定し、グラフを選択すると、Director画面に表示されていたグラフの情報 (同時セッション数・接続セッション数・切断セッション数) を表形式でCSVファイルとして出力できます。

※手順、出力形式はCVAD/DaaS共通です

・DirectorからCSV出力した[同時セッション]データ ([期間]：過去7日間で指定した場合)

運用していく上で、このように定期的にDirectorを起動して、手動でCSVを出力する作業は手間がかかるため、Citrix DaaSの Monitor Service API を使ってPowerShellで必要なデータを抽出しCSV化する方法を解説します。

※定期実行については、各自の環境に応じてタスクスケジューラなどをご利用ください。

■ 使用するデータセット：SessionActivitySummaries

Monitor Data API の SessionActivitySummaries というデータセットを使用することで、Citrix Director でエクスポートされる「同時セッション数」のデータとほぼ同等の内容を含んだデータが取得できます。

CVAD：http://{MonitorServiceHost} /Citrix/Monitor/Odata/v4/Data/SessionActivitySummaries
DaaS：https://api.cloud.com/monitorodata/SessionActivitySummaries
※Citrix Cloud Japan利用の場合：https://api.citrixcloud.jp/monitorodata

このAPI を呼び出すと、以下のような JSON データが返されます(例)。

"value": [
{
"Id": 0,
"SummaryDate": "2025-07-13T22:50:30.307Z",
"DesktopGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ConnectedSessionCount": 0,
"DisconnectedSessionCount": 0,
"ConcurrentSessionCount": 0,
"TotalLogOnDuration": 0,
"TotalLogOnCount": 0,
"Granularity": 0,
"CreatedDate": "2025-07-13T22:50:30.307Z",
"ModifiedDate": "2025-07-13T22:50:30.307Z“ {
"Id":1,

◆引用： developer-docs.citrix.com

今回取得対象としている「同時セッション数」に関連するフィールドは以下の通りです。
・SummaryDate (集計日)
・ConcurrentSessionCount (同時セッション数)
・ConnectedSessionCount (接続中セッション数)
・DisconnectedSessionCount (切断されたセッション数)

■ SessionActivitySummaries 注意点

SessionActivitySummariesでは、以下フィールドのフィルターを適切に設定しないと不要なデータも出力されてしまうことがあります。

・Granularity (データの粒度)

⇒1(分), 60(時間), 1440(日) など複数の粒度のデータが存在しているため、取得するデータに合わせて必要な粒度を指定して抽出する必要があります。

　※粒度は1, 60, 1440で固定されており、他の値には変更できません。

・DesktopGroupId (デリバリーグループのGUID)

⇒SessionActivitySummaries にはデリバリーグループ名が含まれていないため、別のエンドポイント「DesktopGroups」を使用して「DesktopGroupId」とグループ名を紐付ける必要があります。

このようにURLにクエリパラメータを追加して必要な情報だけを取得するのがポイントになります。

$baseUrl = “http://$monitorServiceHost/Citrix/Monitor/OData/v4/Data/SessionActivitySummaries?`$filter=SummaryDate ge $startDate and SummaryDate le $endDate and DesktopGroupId eq $desktopGroupId and Granularity eq 60&`$select=SummaryDate,ConcurrentSessionCount,ConnectedSessionCount,DisconnectedSessionCount“

　※$select=で指定するフィールドについては適宜調整ください

また、データの粒度（Granularity）が細かくなるほど、保持期間が短くなる点にも注意が必要です。

たとえば、過去1か月分の情報を取得したい場合、粒度が「1分単位」のデータでは保持期間を超えてしまい、そもそも取得できない可能性があります。そのため、必要な期間のデータを取得する際は、粒度と保持期間を確認したうえで選択するようにしてください。

なお、以下の粒度別の保持期間は、実機環境で検証した結果に基づく目安です。

・粒度 1（分単位）：3日＋13時間
・粒度 60（時間単位）：32日＋11時間
・粒度 1440（日単位） ：365日＋11時間

※ 実際の保持期間は環境構成やDBの設定によって異なる場合があります。

■ Powershell スクリプト例 (CVADの場合)

このスクリプトでは、指定したデリバリーグループの過去1週間分（取得日を含む）の日単位の同時セッション数を取得できます。

# 認証情報
$userName = "domain\username"　　　#ドメイン名\ユーザー名
$userPassword = "password"　　　　　　#パスワード
$secStringPassword = ConvertTo-SecureString $userPassword -AsPlainText -Force
$credObject = New-Object System.Management.Automation.PSCredential ($userName, $secStringPassword)

# 環境に応じて設定
$monitorServiceHost = "xx.xx.xx.xx"　　　　　　　　　#Citrix Directorのホスト名またはIP
$deliveryGroupName = "DeliveryGroupName"　　　#対象のデリバリーグループ名
$csvPath = "{filepath}\{filename}.csv"　　　　　　　　　#出力先ファイルパス

# 日付範囲 (取得当日から過去7日間) *1
$endDate = (Get-Date).ToUniversalTime().ToString("yyyy-MM-dd")
$startDate = (Get-Date).AddDays(-6).ToUniversalTime().ToString("yyyy-MM-dd")

# DesktopGroupsからID取得 *2
$dgUrl = "http://$monitorServiceHost/Citrix/Monitor/OData/v4/Data/DesktopGroups"
$response = Invoke-WebRequest -Uri $dgUrl -Method GET -Credential $credObject
$dgData = $response.Content | ConvertFrom-Json
$desktopGroupId = ($dgData.value | Where-Object { $_.Name -eq $deliveryGroupName }).Id

# API URLの作成（デリバリーグループと日付範囲でフィルター、表示フィールド絞り）
$baseUrl = "http://$monitorServiceHost/Citrix/Monitor/OData/v4/Data/SessionActivitySummaries?`$filter=SummaryDate ge $startDate and SummaryDate le $endDate and DesktopGroupId eq $desktopGroupId and Granularity eq 60&`$select=SummaryDate,ConcurrentSessionCount,ConnectedSessionCount,DisconnectedSessionCount"

# JST変換関数 (UTC→JST) *3
Function Convert-UTCToJST {
param ([string]$utcTime)
([datetime]::Parse($utcTime).ToUniversalTime()).AddHours(9)
}
# API呼び出し
$response = Invoke-WebRequest –Uri $baseUrl –Method GET –Credential $credObject
$data = $response.Content | ConvertFrom-Json
$allData = $data.value

# ページネーション対応 (@odata.nextLink がある限り繰り返す) *4
While ($data."@odata.nextLink") {
$nextUrl = $data."@odata.nextLink"
$response = Invoke-WebRequest –Uri $nextUrl –Method GET –Credential $credObject
$data = $response.Content | ConvertFrom-Json
$allData += $data.value
}
# UTC→JST変換 *3
$sessionList = $allData | ForEach-Object {
$_.SummaryDate = Convert-UTCToJST $_.SummaryDate
$_
}
# CSV出力 (日付昇順でソート) *5
$sessionList | Sort-Object { [datetime]::Parse($_.SummaryDate) } |
Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8

スクリプト内の下線部分はご利用の環境や目的に応じて適宜変更してください。

また、APIから取得した形式そのままでは扱いづらいため、本スクリプトではDirectorのエクスポート形式に近づけるため以下の加工を行っています。

1. 日付範囲の指定
⇒取得日から過去1週間分を取得
2. デリバリーグループ名→DesktopIdへの変換
⇒DesktopGroupsエンドポイントを使用してGUIDと対応させる
3. UTC → JST への変換
⇒APIから返される日時は UTC のため、日本時間(JST)に変換
4. ページネーション対応
　 ⇒APIの仕様上、取得するデータ量が多いと自動的にページ分割されます。一部のデータしか取得されないのを防ぐため、@odata.nextLink を使って全件取得しています。
5. 日付順に並べ替え
⇒API の出力は Id 順のため、SummaryDate を基準に昇順で並べ替え

■ Powershell スクリプト例 (DaaSの場合)

DaaS環境でも、CVADと同様に Monitor API を活用して、同時セッション数データを取得できます。

※赤字はCVADスクリプトをDaaS向けに調整した箇所です。

# 認証情報
$customerId = "xxxxxxxx"　#顧客ID
$clientId = "xxxxxxxx"　　　#クライアントID
$clientSecret = "xxxxxxxx"　#クライアントシークレット

# 環境に応じて設定
$deliveryGroupName = "DeliveryGroupName"　　#対象のデリバリーグループ名
$csvPath = "{filepath}\{filename}.csv"　　　　　　#出力先ファイルパス

#bearerToken生成関数
Function Get-BearerToken {
param (
[string]$clientId,
[string]$clientSecret
)
$body = @{
'grant_type' = 'client_credentials'
'client_id' = $clientId
'client_secret' = $clientSecret
}
$response = Invoke-RestMethod -Uri 'https://api.cloud.com/cctrustoauth2/root/tokens/clients' -Method POST -Body $body
return "CWSAuth bearer=$($response.access_token)"
}
$bearerToken = Get-BearerToken -clientId $clientId -clientSecret $clientSecret
$headers = @{
'Citrix-CustomerId' = $customerId
'Authorization' = $bearerToken
}
# 日付範囲 (取得当日から過去7日間)
$endDate = (Get-Date).ToUniversalTime().ToString("yyyy-MM-dd")
$startDate = (Get-Date).AddDays(-6).ToUniversalTime().ToString("yyyy-MM-dd")

# DesktopGroupsからID取得 *2
$dgUrl = "https://api.cloud.com/monitorodata/DesktopGroups"
$dgData = Invoke-RestMethod -Uri $dgUrl -Headers $headers
$desktopGroupId = ($dgData.value | Where-Object { $_.Name -eq $deliveryGroupName }).Id

# API URLの作成（デリバリーグループと日付範囲でフィルター、表示フィールド絞り）
$baseUrl = "https://api.cloud.com/monitorodata/SessionActivitySummaries?`$filter=SummaryDate ge $startDate and SummaryDate le $endDate and DesktopGroupId eq $desktopGroupId and Granularity eq 60&`$select=SummaryDate,ConcurrentSessionCount,ConnectedSessionCount,DisconnectedSessionCount“

# JST変換関数 (UTC→JST)
Function Convert-UTCToJST {
param ([string]$utcTime)
([datetime]::Parse($utcTime).ToUniversalTime()).AddHours(9)
}
# API呼び出し
$response = Invoke-RestMethod -Uri $baseUrl -Headers $headers
$allData = $response.value

# ページネーション対応 (@odata.nextLink がある限り繰り返す)
While ($data."@odata.nextLink") {
$nextUrl = $data."@odata.nextLink"
$response = Invoke-WebRequest –Uri $nextUrl –Method GET –Credential $credObject
$data = $response.Content | ConvertFrom-Json
$allData += $data.value
}
# UTC→JST変換
$sessionList = $allData | ForEach-Object {
$_.SummaryDate = Convert-UTCToJST $_.SummaryDate
$_
}
# CSV出力 (日付昇順でソート)
$sessionList | Sort-Object { [datetime]::Parse($_.SummaryDate) } | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8

基本的な処理の流れは CVAD 環境とほぼ同じですが、クラウド環境ではAPIアクセスに必要な情報が異なります。CVADでは認証にドメイン、ユーザー名、パスワードを使用していましたが、DaaSではテナントIDやクライアントシークレットなどの認証情報が必要になります。

① サービスプリンシパルの作成(クライアントID、シークレット)
CVADでは Windows 認証を使用しますが、DaaSでは Citrix Cloud の OAuth2 認証を使用します。
Bearer Token を取得して、 クライアントID と シークレットでトークンを取得し、
APIリクエストにヘッダーとして付けます。

Citrix Cloudコンソールで、左上隅にあるメニューをクリック
[Identity and Access Management] > [API アクセス] > [サービスプリンシパル] > [サービスプリンシパルの作成] を選択し、手順に従って完了

◆参考： developer-docs.citrix.com

② 顧客ID（Customer Id）
Citrix Cloud にログイン後、以下いずれかの場所で確認できます。

画面右上のユーザー名の下に「CCID：」として表示
「IDおよびアクセス管理」>「API Access」 >「サービスプリンシパル」ページ内

③ API エンドポイント
CVADでは Director サーバーの OData エンドポイントに直接アクセスしますが、
DaaSでは地域ごとに異なるAPI Gateway エンドポイントを使用します。

US/EU/AP-Sリージョン ：https://api.cloud.com/monitorodata
日本リージョン ：https://api.citrixcloud.jp/monitorodata

■ スクリプトでの出力結果

本スクリプトで出力したCSVファイルは以下のようになります。(CVAD、DaaSどちらでやっても形式は同じです)

2.2：ログオンパフォーマンス

次に「傾向」画面の［ログオンパフォーマンス］タブです。ここは主にログオン処理の遅延を把握・分析するために活用されます。

画面中央のグラフには、以下のログオン統計情報が表示されます。

平均ログオン期間
指定した期間の平均
ログオン数

■ グラフデータのエクスポート

同時セッションと同様に、画面右上の「エクスポート」機能から「ファイル形式：CSV」、「対象：グラフ」でそのまま出力した結果です。

・DirectorからCSV出力した[ログオンパフォーマンス]データ ([期間]：過去7日間で指定した場合)

こちらも同じようにAPIで出力して確認します。

■ 使用するデータセット：SessionActivitySummaries

Directorのようにログオン時間の平均値は取得できませんが、同時セッション数と同様にSessionActivitySummariesから以下の情報を取得していきます。

・SummaryDate (集計日)
・TotalLogOnDuration (Citrix環境でのユーザーのログオン処理全体にかかった時間 (ミリ秒単位))
・TotalLogOnCount (総ログオン数)

"value": [
{
"Id": 0,
"SummaryDate": "2025-07-13T22:50:30.307Z",
"DesktopGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ConnectedSessionCount": 0,
"DisconnectedSessionCount": 0,
"ConcurrentSessionCount": 0,
"TotalLogOnDuration": 0,
"TotalLogOnCount": 0,
"Granularity": 0,
"CreatedDate": "2025-07-13T22:50:30.307Z",
"ModifiedDate": "2025-07-13T22:50:30.307Z“
{
"Id":1,

■ スクリプト例、出力結果 (CVAD・DaaS)

前章で使用したスクリプトのURL部分を変えて出力しました。（$selectで指定するフィールドを変更）

・CVADの場合：

$baseUrl = "http://$monitorServiceHost/Citrix/Monitor/OData/v4/Data/SessionActivitySummaries?`$filter=SummaryDate ge $startDate and SummaryDate le $endDate and DesktopGroupId eq $desktopGroupId and Granularity eq 60&`$select=SummaryDate,TotalLogOnDuration,TotalLogOnCount“

・DaaSの場合：

$baseUrl = "https://api.cloud.com/monitorodata/SessionActivitySummaries?`$filter=SummaryDate ge $startDate and SummaryDate le $endDate and DesktopGroupId eq $desktopGroupId and Granularity eq 60&`$select=SummaryDate,TotalLogOnDuration,TotalLogOnCount“

・Powershell でCSV出力した[ログオンパフォーマンス]データ(例)

検証環境のためデータは少ないのですが、Directorでエクスポートした[ログオンパフォーマンス]グラフと同様に、時間帯ごとのログオン数とそのログオンにかかった時間が確認できます。なお、ログオン処理時間のデータには以下条件がありすべての接続が対象になるわけではありません。

・ログオン処理時間は、HDXを使用するデスクトップまたはアプリに初めて接続する場合のみ測定されます。このデータには、リモートデスクトッププロトコルを使用して接続しようとするユーザーや、切断されたセッションから再接続するユーザーは含まれません。

◆引用： docs.citrix.com

2.3：その他監視項目とAPI対応一覧

そのほか「傾向」画面から確認できる項目について、Citrix が公開している API エンドポイントとの対応表を作成しました。
必要なデータ取得の参考になればと思います。

Director [傾向]-監視項目	APIエンドポイント	URL
リソース使用率	ResourceUtilizationSummary	Citrix Monitor Service API
失敗 (接続の)	ConnectionFailureLogs (Raw)	Citrix Monitor Service API Citrix Monitor Service API ◆列挙型とエラーコードの説明： Descriptions for enums and error codes \| Citrix Monitor Service API
負荷評価基準インデックス	LoadIndexSummaries	Citrix Monitor Service API
容量管理	ApplicationActivitySummaries	Citrix Monitor Service API
マシン使用率	MachineSummaries	Citrix Monitor Service API
アプリケーション障害	ApplicationFaults (アプリケーション障害) ApplicationErrors (アプリケーションエラー)	https://developer-docs.citrix.com/en-us/monitor-service-odata-api/apis/#/ApplicationFaults/ApplicationFaults https://developer-docs.citrix.com/en-us/monitor-service-odata-api/apis/#/ApplicationErrors/ApplicationErrors
カスタムレポート
ネットワーク

3. Monitor Dataの保持期間について

Citrix環境で収集されるMonitor Dataには保持期間の制限があります。この保持期間は、データの取得間隔（Granularity）、データの種類、ライセンスの種類など、複数の要素によって決まります。本章では、CVADおよびDaaSのデータ表示/保持期間の違いと、保持期間を延長する方法について解説します。

■ CVADのMonitor Data 表示期間/保持期間

CVAD環境では、Directorで表示可能なデータの期間と、実際にMonitor DBに保持される期間は異なります。
Directorの画面上では最大365日分までしかデータを参照できませんが、Premiumライセンス環境の場合、PowerShellで設定を変更することで、Monitor DB自体には最大1000日分までデータを保持することが可能です（CVADのみ）。

	Standard	Advanced	Premium
Directorで表示可能な期間	7日	31日	365日
Monitor DB 保持期間	7日	31日	最大1000日 (推奨365日)

※保持期間を延長すると、Monitor DBサイズの増加によりパフォーマンスに影響を与える可能性があります。環境のリソース状況を考慮して設定してください。

■ DaaSのMonitor Data 表示期間/保持期間

DaaS環境では、Directorで表示可能な期間はすべてのエディションで最大90日間に制限されています。
ただし、Monitor APIを使用することで、一部のデータは365日まで取得可能です。
※DaaSでは保持期間の変更はできません。

■ CVADでの保持期間変更方法

Premiumライセンス環境では、以下の PowerShell コマンドを Delivery Controller 上で実行することで、 Monitor Service の保持期間を変更できます。設定変更後は、すべてのDelivery Controllerで「Citrix Monitor Service」を再起動してください。

　#Citrix の PowerShell Snap-inを読み込むコマンド (Add-PSSnapin の略)
　asnp Citrix.*
　#現在の Monitor Service の設定を取得するコマンド
　Get-MonitorConfiguration
　#Monitor Service の設定を変更するコマンドに変更したい設定項目 (例：DataRetentionDays) を指定しに新しい値を入力
　Set-MonitorConfiguration -

◆参考：
CVAD: docs.citrix.com docs.citrix.com

DaaS: docs.citrix.com

■Monitor Data 保持設定の変更例

実際に「GroomSessionsRetentiondays」の保持期間を変更してみました。
デフォルトは90日でしたが、1000日に変更した例となります。
※パラメータによって、上限の保持日数が異なるためご注意ください。

・変更前

・変更後

4. まとめ

本記事では、Citrix Monitor Service API を活用して Director の「傾向」画面に表示される各種監視データを取得する方法について、CVAD と DaaS の違いを踏まえながら紹介しました。
API を使えば、CVAD環境、DaaS 環境に限らず、DirectorのUI に近いデータを効率よく取得できるので、運用監視にとても便利です。
また、CVAD と DaaS では使えるAPI や保持期間に違いがあるので、環境に合わせてうまく使い分けるのがポイントです。
ぜひご利用の環境に合わせて試してみてください。