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.
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.
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:
Führen Sie das Parallels RAS-Installationsprogramm auf dem RAS Connection Broker oder einem anderen Server aus.
Wählen Sie auf der Seite Installationstyp wählen die Option Benutzerdefiniert.
Wählen Sie auf der nächsten Seite die Option zur Installation der Komponente Parallels RAS Web-Administrationsdienst.
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.
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:
Anmelden bei Parallels RAS und Abrufen eines Sitzungstokens
Abrufen der Informationen über alle verfügbaren RD-Sitzungshosts
Abrufen der Informationen über einen bestimmten RD-Sitzungshost
Ä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.
Antwort: Nach dem Absenden der Anmeldeanforderung erhalten Sie eine Antwort mit dem Sitzungstoken, den Sie in allen nachfolgenden Abfragen verwenden werden:
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).
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:
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“:
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 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.