WEM API と Windows PowerShell を使用して構成セットを自動的にバックアップする
Workspace Environment Management (WEM) 管理者は、設定が失われないように、構成セットを定期的にバックアップする必要がある場合があります。 たとえば、12 時間ごとにバックアップをトリガーし、バックアップ ファイルをローカルで自動的に管理したい場合があります。 WEM パブリック API と Windows PowerShell を使用すると、その目標を達成できます。
一般的なワークフローは次のとおりです。
- Citrix Cloud APIクライアントを申請する
- 構成セットをバックアップするための PowerShell スクリプトを作成する
- スクリプトを実行するためのスケジュールされたタスクを構成する
前提条件
開始する前に、Citrix 顧客 ID と関連する API ベース URL を把握しておいてください。
Citrix Cloud にサインインし、 Identity and Access Management > API Accessに移動して、Citrix 顧客 ID を見つけます。
Citrix Auth API ベース URL や WEM API ベース URL などの API ベース URL は、接続先の Citrix Cloud のリージョンに関連しています。 リージョンは、Citrix Cloud にオンボードするときに決定されます。 アカウント設定でも地域を照会できます。
API ベースの URL については、次の表を参照してください。
| 地域 | Citrix Auth API ベース URL | WEM API ベース URL |
|---|---|---|
| アメリカ合衆国 | api-us.cloud.com | api.wem.cloud.com |
| 欧州連合（EU） | api-eu.cloud.com | eu-api.wem.cloud.com |
| アジア太平洋南部（AP-S） | api-ap-s.cloud.com | ウェブマスター向け |
| 日本 (JP) | api.citrixcloud.jp | jp-api.wem.citrixcloud.jp |
API ベース URL の詳細については、「 Citrix Cloud API の使用を開始する 」および「 WEM API の概要」を参照してください。
Citrix Cloud APIクライアントを申請する
ID およびアクセス管理 > API アクセスに移動します。 セキュア クライアントの名前を入力し、[ クライアントの作成] をクリックして、セキュア クライアント ID とクライアント シークレットをローカルに保存します。
構成セットをバックアップするための PowerShell スクリプトを作成する
次の PowerShell スクリプトを使用して、 Invoke-WEMConfigSetBackupAPI.ps1として保存します。 スクリプトの先頭にある変数を必ず置き換えてください。
# replace the variables before running the script
$CitrixCustomerId = 'your-citrix-customer-id'
$CitrixAuthAPIBaseURL = 'api-us.cloud.com'
$CitrixWEMAPIBaseURL = 'api.wem.cloud.com'
$ClientId = 'your-api-client-id'
$ClientSecret = 'your-api-client-secret'
$ConfigSetsToBackUp = @('Default Site', 'MyConfigSet') # leave it empty if you want to back up all configuration sets
$FolderToSaveBackup = 'C:\ProgramData'
# get bearer token
$ErrorActionPreference = 'Stop'
$URL = "https://${CitrixAuthAPIBaseURL}/cctrustoauth2/${CitrixCustomerId}/tokens/clients"
$Body = "grant_type=client_credentials&client_id=${ClientId}&client_secret=${ClientSecret}"
$Response = Invoke-RestMethod -Method 'Post' -Uri $URL -Body $Body -ContentType 'application/x-www-form-urlencoded'
$BearerToken = $Response.access_token
if ([string]::IsNullOrEmpty($BearerToken))
{
throw 'Cannot retrieve bearer token.'
}
Write-Host "Retrieved bearer token successfully."
# back up WEM configuration sets
if (-not (Test-Path -Path $FolderToSaveBackup -PathType 'Container'))
{
throw 'The folder to save backup not exists.'
}
$Headers = @{
'Citrix-CustomerId' = $CitrixCustomerId
'Accept' = 'application/json'
'Authorization' = "CWSAUTH bearer=${BearerToken}"
}
if ($ConfigSetsToBackUp.Count -eq 0 -or $ConfigSetsToBackUp -eq $null)
{
$URL = "https://${CitrixWEMAPIBaseURL}/services/wem/sites"
$Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers $Headers
$ConfigSetsToBackUp = $Response.items |% { $_.name }
}
$ConfigSetsToBackUp | ForEach-Object {
Write-Host "Backing up configuration set ""$_"""
$URL = "https://${CitrixWEMAPIBaseURL}/services/wem/sites/%24export?name=$_"
Write-Host "GET $URL"
$Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers $Headers
$Timestamp = Get-Date -Format "yyyyMMddHHmmss"
$Response | ConvertTo-Json -Depth 10 | Out-File (Join-Path $FolderToSaveBackup "${_}-${Timestamp}.json")
}
<!--NeedCopy-->
ベアラートークンの詳細については、「 Citrix Cloud API の使用を開始する」を参照してください。
WEM API を使用して構成セットをバックアップする方法の詳細については、「 WEM 構成セット API のエクスポート」を参照してください。
注意:
各ベアラートークンは 1 時間後に期限切れになります。 Citrix Cloud 認証 API と WEM API が頻繁に呼び出されないようにするには、ベアラー トークンをキャッシュし、バックアップ期間が 1 時間未満の場合はそれを再利用します。
エラー 504 ゲートウェイ タイムアウトが発生した場合は、構成セットが大きすぎるために、バックアップ時間が 1 分間の API タイムアウトを超えている可能性があります。 このような場合は、代わりに次の PowerShell スクリプトを使用してみてください。 このスクリプトは現在公開されていない API を使用しており、これらの API は将来変更される可能性があることに注意してください。
# replace the variables before running the script
$CitrixCustomerId = 'your-citrix-customer-id'
$CitrixAuthAPIBaseURL = 'api-us.cloud.com'
$CitrixWEMAPIBaseURL = 'api.wem.cloud.com'
$ClientId = 'your-api-client-id'
$ClientSecret = 'your-api-client-secret'
$ConfigSetsToBackUp = @('Default Site', 'MyConfigSet') # leave it empty if you want to back up all configuration sets
$FolderToSaveBackup = 'C:\ProgramData'
# get bearer token
$ErrorActionPreference = 'Stop'
$URL = "https://${CitrixAuthAPIBaseURL}/cctrustoauth2/${CitrixCustomerId}/tokens/clients"
$Body = "grant_type=client_credentials&client_id=${ClientId}&client_secret=${ClientSecret}"
$Response = Invoke-RestMethod -Method 'Post' -Uri $URL -Body $Body -ContentType 'application/x-www-form-urlencoded'
$BearerToken = $Response.access_token
if ([string]::IsNullOrEmpty($BearerToken))
{
throw 'Cannot retrieve bearer token.'
}
Write-Host "Retrieved bearer token successfully."
# back up WEM configuration sets
if (-not (Test-Path -Path $FolderToSaveBackup -PathType 'Container'))
{
throw 'The folder to save backup not exists.'
}
$Headers = @{
'Citrix-CustomerId' = $CitrixCustomerId
'Accept' = 'application/json'
'Authorization' = "CWSAUTH bearer=${BearerToken}"
}
$URL = "https://${CitrixWEMAPIBaseURL}/services/wem/sites"
$Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers $Headers
$Sites = $Response.items
if ($ConfigSetsToBackUp -ne $null -and $ConfigSetsToBackUp.Count -gt 0)
{
$Sites = $Sites | Where-Object { $_.name -in $ConfigSetsToBackUp }
}
$Sites | ForEach-Object {
$Name = $_.name
Write-Host "Backing up configuration set `"$Name`""
$URL = "https://${CitrixWEMAPIBaseURL}/services/wem/export/site?async=true"
$FolderName = "BACKUPFOLDER-" + [Guid]::NewGuid().ToString()
$Body = @{
folderName = $FolderName
id = $_.id
name = $_.name
type = 'Configuration set'
} | ConvertTo-Json
$Response = Invoke-RestMethod -Method 'Post' -Uri $URL -Headers $Headers -Body $Body -ContentType 'application/json; charset=utf-8'
Write-Host "Waiting for the backup job to complete..."
$URL = "https://${CitrixWEMAPIBaseURL}/services/wem/export/site/recentJobs"
do
{
Start-Sleep -Seconds 5
$Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers $Headers
$BackupJob = $Response.backup[0]
$IsOnGoing = $BackupJob.id -eq $_.id -and $BackupJob.status -eq 'Running'
} while ($IsOnGoing)
$URL = "https://${CitrixWEMAPIBaseURL}/services/wem/export/site/contentView?name=${FolderName}"
$Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers $Headers
$Timestamp = Get-Date -Format "yyyyMMddHHmmss"
$Response | ConvertTo-Json -Depth 10 | Out-File (Join-Path $FolderToSaveBackup "${Name}-${Timestamp}.json") -Encoding utf8
$URL = "https://${CitrixWEMAPIBaseURL}/services/wem/export?prefix=site%2F${FolderName}%2F"
$Response = Invoke-RestMethod -Method 'Delete' -Uri $URL -Headers $Headers
}
<!--NeedCopy-->
スクリプトを実行するためのスケジュールされたタスクを構成する
Citrix Cloud にアクセスできるマシンで、 Windows のスタート メニューから タスク スケジューラ を起動するか、 Windows コマンド プロンプトから taskschd.msc を起動します。
WEM スケジュール タスクという名前のフォルダーを作成できます。
フォルダー内に、 launch Invoke-WEMConfigSetBackupAPI.ps1という名前のタスクを作成します。 新しいトリガー を 1 日間にわたって 12 時間ごとに繰り返します 、およびスクリプト Invoke-WEMConfigSetBackupAPI.ps1を開始する新しいアクションを追加します。
