Dieser Abschnitt gibt Ihnen eine Einführung in die RAS REST API. Lesen Sie es, um mehr über Systemanforderungen, Installation, Konfiguration und Grundlagen des Betriebs zu erfahren.

Parallels RAS wird mit APIs geliefert, die eine Anbindung benutzerdefinierter Anwendungen ermöglichen. Dazu gehören die RAS PowerShell-API und die RAS REST-API.

Darüber hinaus ermöglichen Ihnen die RAS Web Client-API und das Parallels Client-URL-Schema die Integration mit dem Parallels Client für Windows/macOS/Linux/iOS/Android und dem RAS Web Client.

Um auf eine der RAS REST-Ressourcen zugreifen zu können, muss der Benutzer, der eine Anforderung ausführt, über ausreichende Rechte verfügen, um auf eine bestimmte Ressource zugreifen zu können. Dies sind im Wesentlichen die gleichen Rechte, die ein RAS-Administrator in der Parallels RAS-Konsole hat. So kann beispielsweise ein Root-Administrator auf jede der RAS REST-Ressourcen zugreifen. Andererseits kann ein Power-Administrator, der nicht über die Berechtigung verfügt, die Site-Einstellungen zu ändern (als Beispiel), nicht auf eine entsprechende REST-Ressource zugreifen. Ebenso kann ein benutzerdefinierter Administrator, der beispielsweise nur über die Berechtigung zum Anzeigen und Ändern von RD-Sitzungshosts verfügt, auf genau diese REST-Ressource zugreifen und auf keine andere.

RAS Web Client-API und Parallels Client-URL-Schema ermöglichen die Integration mit Parallels-Clients.

Mit der RAS Web Client-API oder dem URL-Schema können Sie eine Inhouse-Lösung, wie beispielsweise einen Hub für Anwendungen oder ein Webportal, zur Authentifizierung von Benutzern und zum Starten von Remote-Anwendungen, Desktops und anderen veröffentlichten Ressourcen implementieren. Eine solche Implementierung ist möglich, indem eine benutzerdefinierte Lösung mit Parallels Clients integriert wird, einschließlich Parallels Clients für unterstützte Plattformen (Windows, macOS, Linux, iOS, Android) und RAS Web Client.

Im Folgenden finden Sie eine kurze Zusammenfassung der API und des URL-Schemas:

• RAS Web Client-API – bietet Verbindungs-, Benutzerauthentifizierungs- und Ressourcenstartmethoden, die von einem Webbrowser über das RAS Web Client aufgerufen werden.

• Parallels Client-URL-Schema – ist ein benutzerdefiniertes URL-Schema, mit dem Sie Aktionen in einem Parallels Client ausführen können, der auf einem Benutzergerät installiert ist. Zu den Aktionen gehören das Konfigurieren einer Verbindung, das Authentifizieren eines Benutzers und das Starten von veröffentlichten Ressourcen.

Die Web Client-API und das Parallels Client-URL-Schema sind im Handbuch Integrating with Parallels Clients ausführlich beschrieben, das auf der Parallels-Website unter folgender Adresse zum Herunterladen zur Verfügung steht: https://www.parallels.com/de/products/ras/resources/.

Dieser Abschnitt enthält ein Beispiel für die Verwendung der RAS REST-API, das Ihnen helfen kann, schnell loszulegen. Das Beispiel zeigt folgende Vorgänge:

1. Anmelden bei Parallels RAS und Abrufen eines Sitzungstokens

2. Abrufen der Informationen über alle verfügbaren RD-Sitzungshosts

3. Abrufen der Informationen über einen bestimmten RD-Sitzungshost

4. Ändern der Eigenschaften des RD-Sitzungshosts.

Anmelden bei Parallels RAS und Abrufen eines Sitzungstokens

Bevor Sie auf eine der Ressourcen zugreifen können, müssen Sie sich mit Administrator-Anmeldeinformationen bei Parallels RAS anmelden und ein Sitzungstoken erhalten. Dies geschieht durch das Absenden der folgenden Anfrage:

POST https://<API-host>/api/session/logon

Abfrage-Header: Die Anmeldeabfrage darf nur den Abfrage-Header „Content-Type“ enthalten. Nachfolgende Abfragen müssen zusätzlich den auth_token-Header enthalten, wie Sie in den folgenden Beispielen sehen werden.

Content-Type: application/json; api-version=1.0

Abfrage-Hauptteil: Der Abfrage-Hauptteil muss den Benutzernamen und das Passwort des RAS-Administrators enthalten.

{
"username": "USER",
"password": "PASSWORD"
}

Antwort: Nach dem Absenden der Anmeldeanforderung erhalten Sie eine Antwort mit dem Sitzungstoken, den Sie in allen nachfolgenden Abfragen verwenden werden:

{
"authToke n": "Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq"
}

Abrufen von Informationen über RD-Sitzungshosts

Nachdem Sie den Sitzungstoken haben, können Sie Abfragen senden, um auf verschiedene Ressourcen zuzugreifen. In diesem Beispiel erhalten Sie zunächst die Informationen über alle verfügbaren RD-Sitzungshosts. Im folgenden Beispiel erhalten Sie die Informationen über einen bestimmten RD-Sitzungshost.

Um die Informationen zum RD-Sitzungshost abzurufen, senden Sie die folgende Anfrage:

GET https://<API-host>/api/RDS

Abfrage-Header: Diesmal muss auch der Header der auth_token-Abfrage enthalten sein und den Sitzungstoken enthalten, den wir zuvor erhalten haben.

Content-Type: application/json; api-version=1.0

auth_token: Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq

Antwort: Die Antwort sieht wie folgt aus (bei mehreren RD-Sitzungshosts in der Farm enthält jeder Block der Ergebnismenge die Informationen über einen einzelnen Server).

[
{
"directAddress": "IP_ADDR",
"rasTemplateId": 0,
"inheritDefaultAgentSettings": true,
"inheritDefaultPrinterSettings": true,
"inheritDefaultUPDSettings": true,
"inheritDefaultDesktopAccessSettings": true,
"port": 3389,
…
"restrictDesktopAccess": false,
"restrictedUsers": [],
"server": "IP_ADDR",
"enabled": true,
"description": "",
"siteId": 1,
"id": 2
}
]

Abrufen der Informationen über einen bestimmten RD-Sitzungshost

Um die Informationen über einen bestimmten Server abzurufen, verwenden wir die gleiche Anfrage wie oben, fügen aber am Ende die Server-ID hinzu:

GET https://<API-host>/api/RDS/2/

Die Antwort wird ebenfalls dem obigen Beispiel ähnlich sein und die Informationen nur für den angegebenen Server enthalten.

Ändern der Eigenschaften des RD-Sitzungshosts

In diesem Beispiel ändern Sie eine Eigenschaft des RD-Sitzungshosts, die wir zuvor abgerufen haben. Der Einfachheit halber ändern Sie das Feld „description“.

Die Anforderung, die Eigenschaften eines RD-Sitzungshosts zu ändern, hat folgende Syntax:

PUT https://<API-host>/api/RDS/2/

Beachten Sie die „2“ am Ende der Abfrage, die die ID des RD-Sitzungshosts angibt, den wir ändern möchten.

Abfrage-Header:

• Content-Type: application/json; api-version=1.0

• auth_token: Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq

Abfrage-Hauptteil:

{
"description": "description was updated!"
}

Antwort: Wenn die PUT-Anfrage erfolgreich war, erhalten Sie eine leere Antwort mit dem Code „204: Kein Inhalt“. Um zu überprüfen, ob das Feld „description“ tatsächlich geändert wurde, verwenden Sie die gleiche GET-Anfrage, die Sie zuvor verwendet haben: GET https://<API-host>/api/RDS/2/

Wie Sie sehen, enthält das Ergebnis nun das aktualisierte Feld „description“:

[
{
"directAddress": "IP_ADDR",
"rasTemplateId": 0,
"inheritDefaultAgentSettings": true,
…
"server": "IP_ADDR",
"enabled": true,
"description": "description was updated!",
"siteId": 1,
"id": 2
}
]

Die Parallels RAS REST-API wird mit dem Parallels RAS REST API Guide geliefert. Der Leitfaden enthält weitere Beispiele und die vollständige Ressourcen- und Schema-Referenz. Um diese Anleitung anzusehen und herunterzuladen, besuchen Sie https://www.parallels.com/de/products/ras/resources/.

Um die RAS REST API in einer RAS-Serverfarm zu aktivieren, müssen Sie den RAS Web-Administrationsdienst installieren. Er kann auf dem RAS Connection Broker-Server oder einem beliebigen anderen Server installiert werden. Wenn Sie den Dienst auf einem separaten Server installieren, müssen Sie dessen Konfiguration (nach der Installation) so ändern, dass er auf den RAS Connection Broker verweist. Standardmäßig verweist die Konfiguration auf „localhost“.

Hinweis: Wenn Sie das Parallels RAS-Verwaltungsportal bereits konfiguriert haben und verwenden, können Sie diesen Schritt überspringen, da Sie den RAS Web-Administrationsdienst bereits installiert haben sollten.

So installieren Sie den RAS Web-Administrationsdienst:

1. Führen Sie das Parallels RAS-Installationsprogramm auf dem RAS Connection Broker oder einem anderen Server aus.

2. Wählen Sie auf der Seite Installationstyp wählen die Option Benutzerdefiniert.

3. Wählen Sie auf der nächsten Seite die Option zur Installation der Komponente Parallels RAS Web-Administrationsdienst.

4. Klicken Sie auf Weiter und folgen Sie den Anweisungen auf dem Bildschirm.

RAS Web-Administrationsdienst konfigurieren

Wenn der RAS Web-Administrationsdienst auf einem separaten Server installiert wurde, müssen Sie die Dienstkonfiguration ändern und die RAS Connection Broker-Serveradresse angeben. Sie können auch die Portnummer und die Zertifikatsinformationen in derselben Konfigurationsdatei ändern. Informationen zur Konfiguration des RAS Web-Administrationsdienstes finden Sie im KB-Artikel https://kb.parallels.com/en/124701.

Beachten Sie beim Ändern der Dienstkonfiguration Folgendes:

• In der JSON-Konfigurationsdatei wird die Adresse des RAS Connection Broker über den Parameter „LicenseServer“ angegeben.

• Die Standardeinstellung für die HTTPS-Portnummer ist Port 20443. Diese Nummer ist so gewählt, dass sie nicht mit den Ports des RAS Secure Gateway kollidiert. Sie können sie auf 443 ändern (wenn möglich), damit Sie beim Öffnen des Portals den Port nicht in der URL angeben müssen.

Die RAS PowerShell-API ist für RAS-Administratoren gedacht, die ihre RAS-Verwaltung automatisieren möchten. Die API enthält Befehle zur Ausführung der meisten RAS-Verwaltungsaufgaben.

Anforderungen für Parallels RAS

Die Parallels RAS PowerShell-API-Version muss mit der Version des RAS Connection Broker übereinstimmen, mit dem sie kommuniziert. Da die beiden Komponenten getrennt installiert werden können, müssen Sie sicherstellen, dass ihre Versionen übereinstimmen.

Anforderungen an Microsoft Windows-Komponenten

Die folgenden Komponenten müssen auf dem Computer installiert sein, auf dem Sie Parallels RAS PowerShell-Cmdlets ausführen:

• Windows PowerShell 3.0 oder höher

• Microsoft.NET Framework 4.5.2 oder höher

Installation

Um Parallels RAS PowerShell zu installieren, führen Sie den standardmäßigen Parallels RAS-Installer aus, wählen Sie Benutzerdefinierte Installation und dann die Option zur Installation der Parallels RAS PowerShell-Komponente. Befolgen Sie die Anweisungen auf dem Bildschirm, um die Komponente zu installieren.

RAS PowerShell-API-Versionen

Die RAS PowerShell-API wurde in Parallels RAS 18 wie folgt geändert:

• Der Name des RAS PowerShell-Moduls wurde von PSAdmin in RASAdmin geändert.

• Die meisten Befehle haben jetzt das Präfix „RAS“, z. B. RASGW oder RASApply.

• API-Versionen: Version 2.0 (neueste) und Version 1.0 werden aus Gründen der Abwärtskompatibilität unterstützt.

Beachten Sie, dass die API-Version 1.0 im aktuellen RAS PowerShell-Modul noch verfügbar ist. Wenn Sie vorhandene Skripte haben, die die älteren Modul- und Befehlsnamen verwenden, müssen Sie diese nur minimal ändern, um sie verwenden zu können. Dazu müssen Sie die API-Version 1.0 laden, wenn Sie das RAS PowerShell-Modul importieren. Weitere Informationen zu den API-Versionen finden Sie unten.

Version 2.0

Hierbei handelt es sich um die Version, die standardmäßig vom System geladen wird oder wenn der Parameter -RequiredVersion beim Importieren des Moduls nicht angegeben wird. Beispiele finden Sie unter RAS PowerShell-API-Konzepte.

Version 1.0

Diese Version bleibt abwärtskompatibel mit dem alten PSAdmin-Modul, damit Administratoren vorhandene Skripte mit geringfügigen Änderungen verwenden können. Diese Version enthält:

• Cmdlet-Aliase

• Parameteraliase

• Gibt alte und neue Eigenschaften zurück

RAS PowerShell-API-Konzepte

Um schnell mit RAS PowerShell zu beginnen, gehen Sie wie folgt vor:

1. Öffnen Sie die Windows PowerShell-Konsole.

2. Importieren Sie das Parallels RAS PowerShell-Modul mit einem der folgenden Befehle:

   • Import-Modul RASAdmin – Lädt die aktuelle API (Version 2.0).

   • Import-Module RASAdmin -RequiredVersion 1.0 – Lädt die API-Version 1.0.

3. Erstellen Sie eine Parallels RAS-Sitzung, indem Sie das Cmdlet New-RASSession ausführen (siehe Beispiel unten). Ersetzen Sie den Servernamen (in Anführungszeichen) durch den Namen oder die IP-Adresse Ihres Parallels RAS-Lizenzservers. Geben Sie Ihren RAS-Administrator-Benutzernamen und Ihr Passwort ein, wenn Sie dazu aufgefordert werden:

   New-RASSession -Server "server.company.dom"

4. Führen Sie das folgende Cmdlet aus, um die Liste der Cmdlets anzuzeigen, die im Parallels RAS PowerShell-Modul enthalten sind:

   Get-Command -Module RASAdmin

5. Führen Sie andere Cmdlets aus. Versuchen Sie beispielsweise, das Cmdlet Get-RASW auszuführen, um Informationen über RAS Secure Gateway(s) abzurufen. Das folgende Beispiel gibt Informationen über alle RAS Secure Gateways zurück, die auf der RAS Licensing Server-Seite verfügbar sind:

   Get-RASGW

6. Um die Hilfe für ein Cmdlet anzuzeigen, führen Sie Get-Help aus, indem Sie einen Cmdlet-Namen übergeben:

   Get-Help Get-RASGW

7. Um Änderungen, die Sie an der Farm-Konfiguration vorgenommen haben, anzuwenden, verwenden Sie das Cmdlet Invoke-RASApply (dies führt die gleiche Aktion aus wie die Schaltfläche Übernehmen in der RAS-Konsole):

   Invoke-RASApply

8. Um eine Parallels RAS-Lizenz zu aktivieren, verwenden Sie das Cmdlet Invoke-RASLicenseActivate:

   Invoke-RASLicenseActivate

   Wenn Sie das obige Cmdlet ausführen, werden Sie aufgefordert, Ihre E-Mail-Adresse und Ihr Passwort für das Parallels-Konto einzugeben. Sie können einen optionalen -Key-Parameter hinzufügen und einen Parallels RAS-Lizenzschlüssel angeben. Ohne diese Angabe (wie im obigen Beispiel) wird Parallels RAS als Testversion aktiviert.

Parallels RAS PowerShell-Anleitung

Um den neuen Parallels RAS PowerShell Guide Version 2.0 anzuzeigen und herunterzuladen, besuchen Sie die Parallels-Website unter https://www.parallels.com/de/products/ras/resources.

Anwendungen kommunizieren mit Parallels RAS, indem sie HTTP- oder HTTPS-Anfragen senden. Parallels RAS antwortet mit einer JSON-Datei als Antwort auf jede HTTP-Anfrage.

Alle HTTP-Anfragen, die Sie zum Abrufen und Verwalten von Parallels RAS-Ressourcen verwenden, haben die folgende Grundstruktur:

https://<API-host>/api/<URI>

Die Parameter in der obigen URL sind:

• <API-Host> ist die IP-Adresse oder FQDN des Servers, auf dem der RAS Web-Administrationsdienst installiert ist.

• <URI> ist ein Pfad zu einer REST-Ressource, mit der Sie arbeiten möchten.