Automatisches Sichern von Konfigurationssätzen mithilfe von WEM-APIs und Windows PowerShell
Als Workspace Environment Management (WEM)-Administrator müssen Sie Ihre Konfigurationssätze möglicherweise regelmäßig sichern, um zu verhindern, dass Einstellungen verloren gehen. Möglicherweise möchten Sie die Sicherung beispielsweise alle 12 Stunden auslösen und die Sicherungsdateien lokal und automatisch verwalten. Mithilfe der öffentlichen WEM-APIs und Windows PowerShell können Sie dieses Ziel erreichen.
Ein allgemeiner Arbeitsablauf sieht wie folgt aus:
- Beantragen Sie einen Citrix Cloud API-Client
- Schreiben Sie ein PowerShell-Skript zum Sichern Ihrer Konfigurationssätze
- Konfigurieren einer geplanten Aufgabe zum Ausführen des Skripts
Voraussetzungen
Stellen Sie vor dem Start 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 Accessund suchen Sie Ihre Citrix-Kunden-ID.
Die API-Basis-URLs, einschließlich der Citrix Auth API-Basis-URL und der WEM API-Basis-URL, beziehen sich auf die Region der Citrix Cloud, mit der Sie eine Verbindung herstellen. Die Region wird beim Onboarding bei Citrix Cloud festgelegt. Sie können Ihre Region auch in den Kontoeinstellungenabfragen.
Sie können die API-Basis-URLs finden, indem Sie die folgende Tabelle überprüfen.
| 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 Sie einen Citrix Cloud API-Client
Navigieren Sie zu Identitäts- und Zugriffsverwaltung > API-Zugriff. Geben Sie den Namen Ihres sicheren Clients ein, klicken Sie auf Client erstellenund speichern Sie die sichere Client-ID und das Client-Geheimnis lokal.
Schreiben Sie ein PowerShell-Skript zum Sichern Ihrer Konfigurationssätze
Verwenden Sie das folgende PowerShell-Skript und speichern Sie es als Invoke-WEMConfigSetBackupAPI.ps1. Denken Sie daran, die Variablen am Anfang des Skripts zu 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")
}
<!--NeedCopy-->
Weitere Informationen zu Bearer-Token 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:
Jeder Inhabertoken läuft nach einer Stunde ab. Um ein häufiges Aufrufen der Citrix Cloud-Authentifizierungs-APIs und WEM-APIs zu vermeiden, speichern Sie das Bearer-Token im Cache und verwenden Sie es erneut, wenn die Sicherungsdauer weniger als eine Stunde beträgt.
Wenn der Fehler 504 Gateway Time-outauftritt, 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 dass sich diese APIs 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
}
<!--NeedCopy-->
Konfigurieren einer geplanten Aufgabe zum Ausführen des Skripts
Starten Sie auf einem Computer mit Zugriff auf Citrix Cloud Taskplaner aus dem Windows-Startmenü oder starten Sie taskschd.msc aus der Windows Eingabeaufforderung.
Sie können einen Ordner mit dem Namen WEM geplante Aufgabeerstellen.
Erstellen Sie im Ordner eine Aufgabe mit dem Namen launch Invoke-WEMConfigSetBackupAPI.ps1. Fügen Sie einen neuen Trigger hinzu, der alle 12 Stunden für die Dauer von 1 Tag wiederholt wird, und fügen Sie eine neue Aktion zum Starten des Skripts Invoke-WEMConfigSetBackupAPI.ps1hinzu.
