任意の RAS REST リソースにアクセスするには、リクエストを実行しているユーザーが、特定のリソースにアクセスできる十分な権限を持つ必要があります。これは、基本的に、RAS 管理者が Parallels RAS Console で持っているのと同じ権限です。たとえば、root 管理者は任意の RAS REST リソースにアクセスできます。一方、（一例として）サイト設定を変更する権限を持たない上級管理者は、対応する REST リソースにアクセスできません。同様に、たとえば、RD セッションホストの表示および変更の権限のみを持つカスタム管理者は、特定の REST リソースのみにアクセスでき、それ以外にはアクセスできません。

このセクションでは、RAS REST API を紹介します。このセクションを読んで、システム要件、インストール、構成、基本的な使用方法について学んでください。

RAS PowerShell API は、RAS 管理業務の自動化を望む RAS 管理者を想定しています。この API には、RAS 管理タスクを実行するための多くのコマンドが含まれます。

Parallels RAS の要件

Parallels RAS PowerShell API のバージョンは、通信対象である RAS Connection Broker のバージョンと一致する必要があります。この 2 つのコンポーネントは別々にインストールできるため、これらのバージョンが一致していることを確認する必要があります。

Microsoft Windows コンポーネントの要件

次のコンポーネントが、Parallels RAS PowerShell コマンドレットを実行するコンピューターにインストールされている必要があります。

• Windows PowerShell 3.0 以降

• Microsoft .NET Framework 4.5.2 以降

インストール

Parallels RAS PowerShell をインストールするには、Parallels RAS の標準インストーラーを実行し、[カスタム] インストールを選択して、[Parallels RAS PowerShell] コンポーネントのインストールを選択します。画面の指示に従い、コンポーネントをインストールします。

RAS PowerShell API のバージョン

Parallels RAS 18 では、RAS PowerShell API が次のように変更されています。

• RAS PowerShell モジュール名が PSAdmin から RASAdmin に変更されました。

• ほとんどのコマンドには、RASGW や RASApply などの”RAS”プレフィックスが付記されるようになりました。

• API のバージョン: バージョン 2.0（最新）とバージョン 1.0 は、下位互換性を確保するためにサポートされています。

現在の RAS PowerShell モジュールでは、API バージョン 1.0 が引き続き使用できることに注意してください。古いモジュール名とコマンド名を使用する既存のスクリプトが存在する場合、最小限の変更でそれらを使用できます。これを行うには、RAS PowerShell モジュールをインポートするときに API バージョン 1.0 を読み込む必要があります。API バージョンの詳細については、以下を参照してください。

バージョン 2.0

このバージョンは、デフォルトでシステムによって読み込まれます。また、モジュールをインポートするときに、-RequiredVersion パラメーターが指定されていない場合も読み込まれます。**「RAS PowerShell API の基本概念」**の例を参照してください。

バージョン 1.0

このバージョンでは、古い PSAdmin モジュールとの下位互換性が維持されており、管理者が小さな変更を加えることで既存のスクリプトを使用できるようにします。このバージョンには次のものが含まれます。

• コマンドレットエイリアス

• エイリアスのパラメーター

• 古いプロパティと新しいプロパティの返還

RAS PowerShell API の概念

RAS PowerShell を手軽に始めるには、次の手順を実行します。

1. Windows PowerShell コンソールを開きます。

2. 次のいずれかのコマンドを使用して、Parallels RAS PowerShell モジュールをインポートします。

   • Import-Module RASAdmin - : 現在の API（バージョン 2.0）を読み込みます。

   • Import-Module RASAdmin -RequiredVersion 1.0 - : API（バージョン 1.0）を読み込みます。

3. New-RASSession コマンドレット（下の例を参照）を実行して Parallels RAS セッションを作成します。サーバー名（引用符内）は、お使いの Parallels RAS ライセンスサーバーの名前または IP アドレスに置き換えてください。入力を求められたら、RAS 管理者のユーザー名とパスワードを入力します。

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

4. 次のコマンドレットを実行して、Parallels RAS PowerShell モジュールに含まれるコマンドレットのリストを確認します。

   Get-Command -Module RASAdmin

5. 他のコマンドレットを実行します。たとえば、Get-GW コマンドレットを実行して RAS Secure Gateway についての情報の取得してみます。下の例は、RAS ライセンスサーバーのサイトで利用できるすべての RAS Secure Gateway についての情報を返します。

   Get-RASGW

6. コマンドレットのヘルプを参照するには、コマンドレット名を渡して Get-Help を実行します。

   Get-Help Get-RASGW

7. ファームの構成に行った変更を適用するには、Invoke-RASApply コマンドレットを使用します（このコマンドレットでは、RAS Console の [適用] ボタンと同じアクションが実行されます）。

   Invoke-RASApply

8. Parallels RAS ライセンスをアクティベートするには、Invoke-RASLicenseActivate コマンドレットを使用します。

   Invoke-RASLicenseActivate

   上述のコマンドレットを実行すると、Parallels アカウントのメールアドレスとパスワードの入力を求められます。オプションの -Key パラメーターを使用して Parallels RAS のライセンスキーを指定することができます。省略した場合は（上の例を参照）、Parallels RAS はトライアル版としてアクティベートされます。

Parallels RAS PowerShell ガイド

新しい 「Parallels RAS PowerShell ガイド」（バージョン 2.0）は、Parallels ウェブサイト（https://www.parallels.com/products/ras/resources）で、確認およびダウンロードしてください。

アプリケーションは、HTTP または HTTPS リクエストを送信することで、Parallels RAS と通信します。Parallels RAS は、あらゆる HTTP リクエストに対して JSON ファイルを使用して応答します。

Parallels RAS リソースの取得および管理に使用されるすべての HTTP リクエストは、次の基本構造を持ちます。

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

上述の URL の各パラメーターは以下の通りです。

• <API-host> は、RAS ウェブ管理サービスがインストールされているサーバーの IP アドレスまたは FQDN です。

• <URI> は、扱う REST リソースのパスです。

Parallels RAS REST API には**「Parallels RAS REST API ガイド」**が付属しています。このガイドには、より多くの例と、リソースおよびスキーマの完全なリファレンスが含まれています。ガイドの閲覧やダウンロードを行うには、 にアクセスしてください。

このセクションでは、手軽に始めるときに役に立つ RAS REST API の使用方法の例を紹介します。例では、次の方法を説明しています。

1. Parallels RAS にログインしてセッショントークンを取得する。

2. 利用できるすべての RD セッションホストについての情報を取得する。

3. 特定の RD セッションホストについての情報を取得する。

4. 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 ウェブ管理サービスをインストールするには、次の操作を実行します。

1. RAS Connection Broker またはその他のサーバーで、Parallels RAS インストーラーを実行します。

2. [インストールタイプの選択] ページで、[カスタム] を選択します。

3. 次のページで、Parallels RAS ウェブ管理サービスコンポーネントのインストールを選択します。

4. [次へ] をクリックし、画面上の指示に従います。

RAS ウェブ管理サービスの構成

RAS ウェブ管理サービスが別のサーバーにインストールされている場合、サービスの構成を変更し、RAS Connection Broker サーバーのアドレスを指定する必要があります。同じ構成ファイルを使用して、ポート番号と証明書情報を変更することもできます。RAS ウェブ管理サービスの構成の詳細については、ナレッジベースの記事（https://kb.parallels.com/en/124701）を参照してください。

サービス構成を変更する場合は、次の点に注意してください。

• 構成用の JSON ファイルでは、RAS Connection Broker のアドレスが”LicenseServer”パラメーターを使用して指定されます。

• デフォルトでは、HTTPS のポート番号は 20443 に設定されています。この番号は、RAS Secure Gateway ポートと競合しないように設定されています。可能な場合は、443 に変更できます。こうすれば、ポータルを開くときに、URL にポート番号を含める必要はありません。

Parallels RAS には複数の API があり、これにより API が統合されたカスタムアプリケーションを開発できます。これには RAS PowerShell API と RAS REST API が含まれます。

さらに、RAS Web Client API および Parallels Client の URL スキームを使用すると、Parallels Client for Windows/macOS/Linux/iOS/Android および Web Client との統合が可能です。

RAS Web Client API および Parallels Client の URL スキームを使用すると、Parallels Client と統合することができます。

RAS Web Client API または URL スキームを使用すると、アプリケーションハブやウェブポータルなどの社内ソリューションを実装して、ユーザーを認証したり、リモートアプリケーション、デスクトップやその他の公開リソースを起動したりすることができます。このような実装は、サポート対象プラットフォーム（Windows、macOS、Linux、iOS、Android）向けの Parallels Client および RAS Web Client を含む Parallels Client とカスタムソリューションを統合することで可能になります。

以下でこの API および URL スキームを簡単に説明します。

• RAS Web Client API - Web Client を介してウェブブラウザーから呼び出す、接続、ユーザー認証、リソース起動の手法を提供しています。

• Parallels Client の URL スキーム - ユーザーデバイスにインストールされている Parallels Client でアクションを実行できるようにするカスタム URL スキームです。アクションには、接続の構成、ユーザーの認証、公開リソースの起動などが含まれます。

RAS Web Client API および Parallels Client の URL スキームの詳細については、**「Parallels Clients との統合」**ガイドに記載されています。このガイドは Parallels ウェブサイトからダウンロードできます: 。