Konfigurationssätze automatisch mit WEM-APIs und Windows PowerShell sichern
Als Workspace Environment Management™ (WEM)-Administrator müssen Sie Ihre Konfigurationssätze möglicherweise regelmäßig sichern, um den Verlust von Einstellungen zu verhindern. Sie möchten die Sicherung beispielsweise alle 12 Stunden auslösen und die Sicherungsdateien lokal und automatisch verwalten. Mit öffentlichen WEM-APIs und Windows PowerShell können Sie dieses Ziel erreichen.
Ein allgemeiner Workflow ist wie folgt:
-
Beantragen Sie einen Citrix Cloud™ API-Client
-
Schreiben Sie ein PowerShell-Skript, um Ihre Konfigurationssätze zu sichern
-
Konfigurieren Sie eine geplante Aufgabe, um das Skript auszuführen
Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass Sie Ihre Citrix® Kunden-ID und die zugehörigen API-Basis-URLs kennen.
Melden Sie sich bei Citrix Cloud an, navigieren Sie zu Identity and Access Management > API-Zugriff und suchen Sie Ihre Citrix Kunden-ID.
Die API-Basis-URLs, einschließlich Citrix Auth API-Basis-URL und WEM API-Basis-URL, beziehen sich auf die Region von Citrix Cloud, mit der Sie sich verbinden. Die Region wird festgelegt, wenn Sie sich bei Citrix Cloud anmelden. Sie können Ihre Region auch in den Kontoeinstellungen abfragen.
Die API-Basis-URLs finden Sie in der folgenden Tabelle.
| Region | Citrix Auth API Basis-URL | WEM API Basis-URL |
|---|---|---|
| Vereinigte Staaten (US) | api-us.cloud.com | api.wem.cloud.com |
| Europäische Union (EU) | api-eu.cloud.com | eu-api.wem.cloud.com |
| Asien-Pazifik Süd (AP-S) | api-ap-s.cloud.com | aps-api.wem.cloud.com |
| Japan (JP) | api.citrixcloud.jp | jp-api.wem.citrixcloud.jp |
Weitere Informationen zu den API-Basis-URLs finden Sie unter Erste Schritte mit Citrix Cloud APIs und WEM API-Übersicht.
Beantragen eines Citrix Cloud API-Clients
Navigieren Sie zu Identitäts- und Zugriffsverwaltung > API-Zugriff. Geben Sie den Namen Ihres sicheren Clients ein, klicken Sie auf Client erstellen, und speichern Sie die sichere Client-ID und das Client-Geheimnis lokal.
Schreiben Sie ein PowerShell-Skript, um Ihre Konfigurationssätze zu sichern
Verwenden Sie das folgende PowerShell-Skript und speichern Sie es als
Invoke-WEMConfigSetBackupAPI.ps1. Stellen Sie sicher, dass Sie die Variablen am Anfang des Skripts ersetzen.
# 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")
}
Weitere Informationen zu Bearer-Tokens finden Sie unter Erste Schritte mit Citrix Cloud APIs.
Weitere Informationen zur Verwendung der WEM-API zum Sichern von Konfigurationssätzen finden Sie unter Exportieren der WEM-Konfigurationssatz-API.
Hinweis:
Jedes Bearer-Token läuft nach einer Stunde ab. Um häufige Aufrufe der Citrix Cloud Auth-APIs und WEM-APIs zu vermeiden, cachen Sie das Bearer-Token und verwenden Sie es wieder, wenn die Sicherungsdauer weniger als eine Stunde beträgt.
Wenn der Fehler 504 Gateway Time-out auftritt, bedeutet dies wahrscheinlich, dass Ihr Konfigurationssatz zu groß ist, wodurch die Sicherungszeit das 1-minütige API-Timeout überschreitet. Versuchen Sie in solchen Fällen stattdessen das folgende PowerShell-Skript zu verwenden. Beachten Sie, dass dieses Skript APIs verwendet, die derzeit nicht öffentlich sind, und diese APIs sich in Zukunft ändern können.
# 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
}
Konfigurieren Sie eine geplante Aufgabe zum Ausführen des Skripts
Starten Sie auf einem Computer mit Zugriff auf Citrix Cloud
Task Scheduler über das Windows-Startmenü oder starten Sie taskschd.msc über die Windows-Eingabeaufforderung.
Sie können einen Ordner mit dem Namen
WEM scheduled task erstellen.
Erstellen Sie in dem Ordner eine Aufgabe mit dem Namen
launch Invoke-WEMConfigSetBackupAPI.ps1. Fügen Sie einen neuen Trigger alle 12 Stunden für eine Dauer von 1 Tag wiederholen hinzu und fügen Sie eine neue Aktion zum Starten des Skripts Invoke-WEMConfigSetBackupAPI.ps1 hinzu.
