任意の RAS REST リソースにアクセスするには、リクエストを実行しているユーザーが、特定のリソースにアクセスできる十分な権限を持つ必要があります。これは、基本的に、RAS 管理者が Parallels RAS Console で持っているのと同じ権限です。たとえば、root 管理者は任意の RAS REST リソースにアクセスできます。一方、（一例として）サイト設定を変更する権限を持たない上級管理者は、対応する REST リソースにアクセスできません。同様に、たとえば、RD セッションホストの表示および変更の権限のみを持つカスタム管理者は、特定の REST リソースのみにアクセスでき、それ以外にはアクセスできません。
アプリケーションは、HTTP または HTTPS リクエストを送信することで、Parallels RAS と通信します。Parallels RAS は、あらゆる HTTP リクエストに対して JSON ファイルを使用して応答します。
Parallels RAS リソースの取得および管理に使用されるすべての HTTP リクエストは、次の基本構造を持ちます。
https://<API-host>/api/<URI>
上述の URL の各パラメーターは以下の通りです。
<API-host> は、RAS ウェブ管理サービスがインストールされているサーバーの IP アドレスまたは FQDN です。
<URI> は、扱う REST リソースのパスです。
このセクションでは、RAS REST API を紹介します。このセクションを読んで、システム要件、インストール、構成、基本的な使用方法について学んでください。
Parallels RAS REST API には**「Parallels RAS REST API ガイド」**が付属しています。このガイドには、より多くの例と、リソースおよびスキーマの完全なリファレンスが含まれています。ガイドの閲覧やダウンロードを行うには、https://www.parallels.com/products/ras/resources/ にアクセスしてください。
このセクションでは、手軽に始めるときに役に立つ RAS REST API の使用方法の例を紹介します。例では、次の方法を説明しています。
Parallels RAS にログインしてセッショントークンを取得する。
利用できるすべての RD セッションホストについての情報を取得する。
特定の RD セッションホストについての情報を取得する。
RD セッションホストプロパティを変更する。
Parallels RAS にログインしてセッショントークンを取得する
任意のリソースにアクセスするには、管理者の資格情報を使用して Parallels RAS にログインし、セッショントークンを取得する必要があります。これを実行するには、次のリクエストを送信します。
POST https://<API-host>/api/session/logon
リクエストヘッダー: このログオンリクエストには、Content-Type リクエストヘッダーのみを含める必要があります。この後の例で示されるように、後続のリクエストには、さらに auth_token ヘッダーを含める必要があります。
Content-Type: application/json; api-version=1.0
リクエスト本文: リクエスト本文には、RAS 管理者のユーザー名とパスワードを含める必要があります。
応答: ログオンリクエストの送信後、セッショントークンが含まれる返信を受け取ります。これは、後続のすべてのリクエストで使用します。
RD セッションホストについての情報を取得する
セッショントークンを入手したので、さまざまなリソースにアクセスするためのリクエストを送信できるようになりました。この例では、まず、利用できるすべての RD セッションホストについての情報を取得します。この後の例で、特定の RD セッションホストについての情報を取得します。
RD セッションホスト情報を取得するには、次のリクエストを送信します。
GET https://<API-host>/api/RDS
リクエストヘッダー: 今回は、auth_token リクエストヘッダーも含まれ、ここに、事前に取得したセッショントークンが含まれている必要があります。
Content-Type: application/json; api-version=1.0
auth_token: Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq
応答: 応答は次のようになります（ファーム内の複数の RD セッションホストを使用すると、結果セットの各ブロックに個別のサーバーについての情報が含まれます）。
特定の RD セッションホストについての情報を取得する
特定のサーバーについての情報を取得するには、上述と同じリクエストを使用しますが、末尾にサーバー ID を追加します。
GET https://<API-host>/api/RDS/2/
この応答も上述の例と同様になり、特定のサーバーのみの情報が含まれます。
RD セッションホストプロパティを変更する
この例では、事前に取得した RD セッションホストのプロパティを変更します。わかりやすくするため、[説明] フィールドを変更します。
RD セッションホストのプロパティを変更するリクエストの構文は次のようになります。
PUT https://<API-host>/api/RDS/2/
リクエストの末尾に“2”が付いていますが、これは、変更する RD セッションホストの ID を指定しています。
リクエストヘッダー:
Content-Type: application/json; api-version=1.0
auth_token: Lj+KddoJkANhzvbDRvB=K=DFCroRjXJHeeWGbGlIRKaz-EXplbmhVWvWTiDVqtOq
リクエスト本文:
応答: PUT リクエストが成功すると、空の応答と、コード“204: No Content”を受け取ります。[説明] フィールドが実際に変更されたかどうかを確認するには、以前に使用したのと同じ GET リクエストを使用します。GET https://<API-host>/api/RDS/2/
ご覧のように、結果に更新された [説明] フィールドが含まれるようになりました。
RAS ファームで RAS REST API を有効にするには、RAS ウェブ管理サービスをインストールする必要があります。RAS Connection Broker サーバーまたはその他のサーバーにインストールできます。別のサーバーにサービスをインストールする場合は、（インストール後に）RAS Connection Broker が正しく指定されるように構成を変更する必要があります。デフォルトの構成では、”localhost”に指定されています。
注: Parallels RAS 管理ポータルをすでに構成して使用している場合は、RAS ウェブ管理サービスがすでにインストールされていると考えられますので、この手順をスキップできます。
RAS ウェブ管理サービスをインストールするには、次の操作を実行します。
RAS Connection Broker またはその他のサーバーで、Parallels RAS インストーラーを実行します。
[インストールタイプの選択] ページで、[カスタム] を選択します。
次のページで、Parallels RAS ウェブ管理サービスコンポーネントのインストールを選択します。
[次へ] をクリックし、画面上の指示に従います。
RAS ウェブ管理サービスの構成
RAS ウェブ管理サービスが別のサーバーにインストールされている場合、サービスの構成を変更し、RAS Connection Broker サーバーのアドレスを指定する必要があります。同じ構成ファイルを使用して、ポート番号と証明書情報を変更することもできます。RAS ウェブ管理サービスの構成の詳細については、ナレッジベースの記事（https://kb.parallels.com/en/124701）を参照してください。
サービス構成を変更する場合は、次の点に注意してください。
構成用の JSON ファイルでは、RAS Connection Broker のアドレスが”LicenseServer”パラメーターを使用して指定されます。
デフォルトでは、HTTPS のポート番号は 20443 に設定されています。この番号は、RAS Secure Gateway ポートと競合しないように設定されています。可能な場合は、443 に変更できます。こうすれば、ポータルを開くときに、URL にポート番号を含める必要はありません。