目次
テナントで使用するメソッド
Integration Server REST API を使用して、テナントおよびテナントの仮想マシンの使用時に次の操作を実行できます:
- テナント情報の取得
- テナントのリストの取得
- テナントの仮想マシンのリストの取得
- 新しいテナントとその保護インフラストラクチャの作成、または既存のテナントの登録
- テナントの削除
- テナントのアクティブ化と非アクティブ化
- テナントの仮想マシンの登録および登録解除
一部の REST API リクエストの結果として実行される一連の動作は、Integration Server データベースにテナントの情報を登録する時に指定したテナントタイプに応じて異なります。Integration Server REST API を使用したテナントの保護インフラストラクチャの導入および削除は、複合的なテナントタイプで可能です。単純なテナントタイプの場合、レポートの受信機能のみが自動化されます。
テナント情報の取得
テナントの仮想マシンの情報が Integration Server データベースから取得されます。
メソッド:
GET /api/2.0/virtualization/tenants/{テナント ID
}
各パラメータの説明:
{テナント ID}
– Integration Server データベース内のテナントの識別子(必須パラメータ)。
このリクエストが正常に完了すると、REST API はテナントに関する次の情報を返します:
<tenant id="{ID
}" created="{日時
}" updated="{日時
}">
<name>{名前
}</name>
<description>{説明
}</description>
<userData><![CDATA[{詳細情報
}]]></userData>
<!-- vKsc セクションのデータは、複合的なテナントタイプのみ指定可能です -->
<vKsc id="{ID
}">
<user>
<name>{管理者
}</name>
</user>
</vKsc>
<status>{ステータス
}</status>
<type>{テナントタイプ
}</type>
</tenant>
各パラメータの説明:
tenant id="{
ID
}"
– Integration Server 定義データベース内のテナントの識別子。created="{
日時
}"
– Integration Server 定義データベースにテナントが登録された日時。形式:YYYY-MM-DDThh:mm:ss。updated="{
日時
}"
– Integration Server 定義データベースでテナントデータがアップデートされた日時。形式:YYYY-MM-DDThh:mm:ss。{
名前
}
– テナントの作成時に指定されたテナント名。{
説明
}
– テナントの説明。{
詳細情報
}
– Integration Server 定義データベースに保存されたテナントに関する詳細情報。vKsc id="{
ID
}"
- Kaspersky Security Center のテナント仮想管理サーバーに割り当てられた識別子。{
管理者名
}
- テナントの仮想管理サーバーの管理者名。{
ステータス
}
- テナントの現在のステータス:Active
またはInactive
。{
テナントタイプ
}
- テナントタイプ:Complete
(複合的なテナントタイプ)またはSimple
(単純なテナントタイプ)。
リターンコード:
200 (OK)
– リクエストが正常に完了しました。レスポンスが、テナントの情報を返します。403 (Forbidden)
– リソースへのアクセスが拒否されました。404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子のテナントが見つかりません。
テナントのリストの取得
全テナントのリスト、Integration Server データベースに保存されている情報、各テナントの情報を取得できます。
メソッド:
GET /api/2.0/virtualization/tenants
リターンコード:
200 (OK)
– リクエストが正常に完了しました。レスポンスが、全テナントの情報をリストとして返します。403 (Forbidden)
– リソースへのアクセスが拒否されました。
テナントの仮想マシンのリストの取得
登録されたテナントの全仮想マシンのリストを取得できます。
メソッド:
GET /api/2.0/virtualization/tenants/{テナント ID
}/vms
各パラメータの説明:
{
テナント ID
}
- Integration Server 定義データベース内のテナントの識別子(必須パラメータ)。
リクエストが正常に成功すると、REST API が仮想マシン のリストとテナントの仮想マシンに関する次の情報を返します:
<vm id="{
定義データベース内の ID
}" biosId={
BIOS ID} created="{
日時
}" updated="{
日時
}">
<name>{
名前
}</name>
<userData><![CDATA[{
詳細情報
}]]></userData>
</vm>
各パラメータの説明:
{
定義データベース内の ID
}
- Integration Server 定義データベース内の仮想マシンに割り当てられた識別子。{
BIOS ID}
- 仮想マシンの識別子(BIOS ID)(UUID 形式)。created="{
日時
}"
- Integration Server 定義データベースに仮想マシンが登録された日時。形式:YYYY-MM-DDThh:mm:ss。updated="{
日時
}"
– 仮想マシンのデータが Integration Server 定義データベースでアップデートされた日時。形式:YYYY-MM-DDThh:mm:ss。{
名前
}
– 仮想マシン名。{
詳細情報
}
– Integration Server 定義データベースに保存された仮想マシンに関する詳細情報。
リターンコード:
200 (OK)
– リクエストが正常に完了しました。レスポンスが、テナントの仮想マシンのリストを返します。403 (Forbidden)
– リソースへのアクセスが拒否されました。404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子のテナントが見つかりません。
テナントの新規作成
REST API メソッドの呼び出し時に指定するテナントタイプに応じて、次の動作が実行されます:
- 複合的なテナントタイプの場合:
- Integration Server データベースにテナントデータを追加します。
- Kaspersky Security Center で、テナントの保護インフラストラクチャを作成します(仮想管理サーバー、仮想管理サーバーへの接続用アカウント、フォルダーと管理グループの構造、)。
- Kaspersky Security for Virtualization 5.1 Light Agent がインストールされている仮想マシンの保護を有効化または無効化するポリシーを、[Multitenancy KSV LA – <テナント名>]フォルダーに作成します。
保護を有効または無効にするポリシーは、Kaspersky Security for Virtualization 5.1 Light Agent がテナントの仮想インフラストラクチャにインストールされている場合にのみ適用されます。
- テナントの仮想サーバーの情報を Integration Server データベースへ追加します。
- 単純なテナントタイプの場合:Integration Server データベースにテナントデータを追加します。
メソッド:
POST /api/2.0/virtualization/tenants
リクエスト本文に次のパラメータを指定する必要があります:
<tenant>
<name>{名前
}</name>
<description>{説明
}</description>
<userData><![CDATA[{詳細情報
}]]></userData>
<preferredViisAddress>{IP アドレス
}</preferredViisAddress>
<type>{テナントタイプ
}</type>
<!-- vKsc セクションのデータは、複合的なテナントタイプのみ指定可能です -->
</vKsc>
<user>
<name>{管理者名
}</name>
<password>{管理者パスワード
}</password>
</user>
</vKsc>
</tenant>
各パラメータの説明:
{
日時
}
– テナント名(必須パラメータ)。{
説明
}
– テナントの説明(任意のパラメータ)。{
詳細情報
}
– テナントに関する詳細情報(任意のパラメータ)。{
IP アドレス
}
– テナントの仮想マシンにインストールされた Light Agent が接続する Integration Server の IP アドレス(任意のパラメータ)。指定したアドレスが既定値として、Light Agent ポリシーの作成時に使用されます。パラメータが指定されていない場合、ポリシーは Integration Server の IP アドレスを REST API へのリクエストから使用します。{
テナントタイプ
}
– テナントタイプ:Complete
またはSimple
なテナントタイプ(オプションパラメータ)。{
管理者名
}
– テナントの仮想化管理サーバーへの接続に使用される管理者アカウントの名前(複合的なテナントタイプの作成時に必要)。アカウントは処理中に自動的に作成されます。{
管理者パスワード
}
- 管理者アカウントのパスワード。Base64 方式にエンコードされています(複合的なテナントタイプの作成時に必要)。
このリクエストは非同期で実行され、REST API は CreateTenant タスクの識別子を返します。このタスクを使用して、テナントの作成処理の進捗を監視できます。タスクの実行が完了すると、[result]フィールドに作成されたテナントの識別子を含むテナントの情報、またはエラーメッセージが表示されます。処理のどこかのステップでエラーが発生すると、変更がすべて元に戻されます。
リターンコード:
202 (Accepted)
– リクエストの実行が受諾されました。レスポンスは、CreateTenant タスクの識別子を返します。400 (Bad request) VIRMT_MandatoryParameterIsNotSpecified
– 必須パラメータのうち 1 つがリクエスト本文で指定されていません(例:テナント名)。400 (Bad request) VIRMT_InvalidTenantType
– 無効なテナントタイプがリクエスト本文で指定されており、指定されたテナントタイプが存在しません。400 (Bad request) VIRMT_VKscCredentialsNotSpecified
– Kaspersky Security Center の仮想管理サーバーの管理者アカウント名またはパスワードが指定されていません(複合的なテナントタイプの作成時)。400 (Bad request) VIRMT_InvalidViisAddressFormat
– Integration Server の IP アドレスの形式が無効です。403 (Forbidden)
– リソースへのアクセスが拒否されました。
タスクで発生する可能性があるエラーコード:
KSC_ServiceNotConfigured
– Kaspersky Security Center 接続設定が指定されていません。VIRMT_TenantGroupAlreadyExists
– 指定したテナント名に対応する名前のフォルダーが Kaspersky Security Center に既に存在します。VIRMT_TenantWithSpecifiedNameAlreadyExists
– Integration Server データベース内に、指定した名前のテナントが見つかりません。VIRMT_PasswordNotComplyPolicy
– Kaspersky Security Center 仮想管理サーバーの管理者アカウントを作成できませんでした:指定したパスワードが Kaspersky Security Center のパスワード要件を満たしていません。VIRMT_UserWithSpecifiedNameAlreadyExists
– Kaspersky Security Center 仮想管理サーバーの管理者アカウントを作成できませんでした:指定した名前のユーザーが既に Kaspersky Security Center に存在します。
テナントのアクティブ化
テナントタイプに応じて、次の動作が実行されます:
- 複合的なテナントタイプの場合:
- テナントのステータスを「アクティブ」に変更します。
- Kaspersky Security for Virtualization 5.1 Light Agent がインストールされている仮想マシンの保護を有効化するポリシーのステータスを変更します。
保護を有効にするポリシーは、Kaspersky Security for Virtualization 5.1 Light Agent がテナントの仮想インフラストラクチャにインストールされている場合にのみ適用されます。テナントの保護を有効化するポリシーがない場合、自動的に作成されます。
- 単純なテナントタイプの場合:テナントのステータスを「アクティブ」に変更するだけです。
メソッド:
POST /api/2.0/virtualization/tenants/{テナント ID
}/activate
各パラメータの説明:
{
テナント ID
}
- Integration Server 定義データベース内のテナントの識別子(必須パラメータ)。
このリクエストは非同期で実行され、REST API は ChangeTenantActivation タスクの識別子を返します。このタスクを使用して、テナントのステータスの変更処理の進捗を監視できます。タスクの実行が完了すると、[result]フィールドにテナントのステータス変更を確認する値(「true
」)、またはエラーメッセージが表示されます。
リターンコード:
202 (Accepted)
– リクエストの実行が受諾されました。レスポンスは、ChangeTenantActivation タスクの識別子を返します。403 (Forbidden)
– リソースへのアクセスが拒否されました。
タスクのエラーコード:
VIRMT_TenantWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子のテナントが見つかりません。KSC_ServiceNotConfigured
– Kaspersky Security Center 接続設定が指定されていません。
テナントの非アクティブ化
テナントタイプに応じて、次の動作が実行されます:
- 複合的なテナントタイプの場合:
- テナントのステータスを「非アクティブ」に変更します。
- Kaspersky Security for Virtualization 5.1 Light Agent がインストールされている仮想マシンの保護を無効化するのポリシーのステータスを変更します。
保護を無効にするポリシーは、Kaspersky Security for Virtualization 5.1 Light Agent がテナントの仮想インフラストラクチャにインストールされている場合にのみ適用されます。テナントの保護を無効化するポリシーがない場合、自動的に作成されます。
- 単純なテナントタイプの場合:テナントのステータスを「非アクティブ」に変更するだけです。
メソッド:
POST /api/2.0/virtualization/tenants/{テナント ID
}/deactivate
各パラメータの説明:
{
テナント ID
}
- Integration Server 定義データベース内のテナントの識別子(必須パラメータ)。
このリクエストは非同期で実行され、REST API は ChangeTenantActivation タスクの識別子を返します。このタスクを使用して、テナントのステータスの変更処理の進捗を監視できます。タスクの実行が完了すると、[result]フィールドにテナントのステータス変更を確認する値(「true
」)、またはエラーメッセージが表示されます。
リターンコード:
202 (Accepted)
– リクエストの実行が受諾されました。レスポンスは、ChangeTenantActivation タスクの識別子を返します。403 (Forbidden)
– リソースへのアクセスが拒否されました。
タスクのエラーコード:
VIRMT_TenantWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子のテナントが見つかりません。KSC_ServiceNotConfigured
– Kaspersky Security Center 接続設定が指定されていません。
テナントの仮想マシンの登録
テナントの仮想マシンの情報を Integration Server データベースへ追加します。
メソッド:
POST /api/2.0/virtualization/tenants/{テナント ID
}/vms/register
各パラメータの説明:
{
テナント ID
}
- Integration Server 定義データベース内のテナントの識別子(必須パラメータ)。
リクエスト本文に次のパラメータを指定する必要があります:
<vm biosId="{BIOS ID
}">
<name>{名前
}</name>
<userData><![CDATA[{詳細情報
}]]></userData>
</vm>
各パラメータの説明:
{
BIOS ID}
- 仮想マシンの一意の識別子(BIOS ID)(必須パラメータ)。{
日時
}
- 仮想マシン名(任意のパラメータ)。{
詳細情報
}
- 仮想マシンに関する詳細情報(任意のパラメータ)。
リターンコード:
200 (OK)
– リクエストが正常に完了しました(仮想マシンに関する情報が Integration Server データベースに追加されます)。403 (Forbidden)
– リソースへのアクセスが拒否されました。404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子のテナントが見つかりません。409 (Conflict) VIRMT_VmWithSpecifiedBiosIdAlreadyExists
– 指定した識別子の仮想マシンが既に Integration Server データベースに登録されています。
仮想マシンの登録解除
テナントの仮想マシンの情報が Integration Server データベースから削除されます。
登録を解除してもテナントの仮想マシンの保護は無効化されません。複合的なテナントタイプのテナントの仮想マシンの保護を、仮想マシンを保護対象インフラストラクチャから削除するステップをすべて実行することで無効にできます。
メソッド:
POST /api/2.0/virtualization/tenants/{テナント ID}/vms/unregister?biosId={ID}
または
POST /api/2.0/virtualization/tenants/{テナント ID}/vms/unregister?vmId={ID}
各パラメータの説明:
{テナント ID}
– Integration Server データベース内のテナントの識別子(必須パラメータ)。biosId={ID}
– 仮想マシンの識別子(BIOS ID)(UUID 形式)(必須パラメータ)。vmId={ID}
– Integration Server データベース内の仮想マシンの識別子(UUID 形式)(必須パラメータ)。
リターンコード:
200 (OK)
– リクエストが正常に完了しました(仮想マシンに関する情報が Integration Server データベースから削除されます)。403 (Forbidden)
– リソースへのアクセスが拒否されました。404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子のテナントが見つかりません。404 (Not Found) VIRMT_VmWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子の仮想マシンが見つかりません。
テナントの削除
テナントタイプと指定するパラメータに応じて、次の動作が実行されます:
- 複合的なテナントタイプの場合:
- テナントとテナントの仮想マシンに関する情報を Integration Server データベースから削除します。
- Kaspersky Security Center から導入されたテナントの保護インフラストラクチャを削除します(仮想管理サーバー、仮想管理サーバーへの接続用アカウント、フォルダーと管理グループの構造、ポリシー、タスク、インストールパッケージ)。別のテナントが存在しない場合、[Multitenancy KSV LA]フォルダーも削除されます。
- テナントの仮想サーバーの情報を Integration Server データベースから削除します。
テナントの削除メソッドを呼び出すことで、テナントの仮想マシンの保護が無効になることはありません。保護を無効にするには、テナントの削除処理のステップをすべて実行します。このステップには、仮想マシンからの Light Agent for Windows、Light Agent for Linux、Kaspersky Security Center ネットワークエージェントの削除も含まれます。複合的なテナントタイプの仮想マシンを保護を一時停止するには、テナントを非アクティブにするメソッドを使用します。
- 単純なテナントタイプの場合:Integration Server データベースからテナントを削除します。
メソッド:
DELETE /api/2.0/virtualization/tenants/{テナント ID
}?removeTenantArtifacts={true|false}
各パラメータの説明:
{
テナント ID
}
- Integration Server 定義データベース内のテナントの識別子(必須パラメータ)。removeTenantArtifacts={true|false}
– 任意のパラメータ。Integration Server データベースからテナントを削除する時、テナントの保護インフラストラクチャを削除するかどうかを決定します。取り得る値の一覧:true
– テナントの削除時に、次の動作が実行されます:- テナント仮想管理サーバーを削除します。
- テナント仮想管理サーバーの管理者アカウントを削除します。
- [Multitenancy KSV LA]→[<テナント名>]フォルダーとその内容を削除します。
- 他のテナントがない場合は、Multitenancy KSV LA フォルダーを削除してください。
false
– テナントのみが Integration Server データベースから削除され、テナントの保護インフラストラクチャは削除されません。
このリクエストは非同期で実行され、REST API は DeleteTenant タスクの識別子を返します。このタスクを使用して、テナントの削除処理の進捗を監視できます。タスクの実行が完了すると、[結果]フィールドに削除されたテナントの情報またはエラーメッセージが表示されます。
処理のどこかのステップでエラーが発生すると、変更がすべて元に戻されます。
リターンコード:
202 (Accepted)
– リクエストの実行が受諾されました。レスポンスは、DeleteTenant タスクの識別子を返します。403 (Forbidden)
– リソースへのアクセスが拒否されました。
タスクのエラーコード:
VIRMT_TenantWithSpecifiedIdNotFound
– Integration Server データベース内に、指定した識別子のテナントが見つかりません。KSC_ServiceNotConfigured
– Kaspersky Security Center 接続設定が指定されていません。