Kaspersky Security for Virtualization 5.2 Light Agent
5.2
日本語‪(日本)

目次

マルチテナンシーのシナリオでの Integration Server REST API の使用

Integration Server REST API との対話は、リクエストとレスポンスに基づいており、multitenancyアカウントの元で HTTPS プロトコルを使用して実行されます。

アカウントのパラメータ（次の文字列の形式：{ユーザー名}:{パスワード}）は、Authorization リクエストヘッダーでのメソッドの呼び出しごとに、Base64 方式にエンコードされて渡されます。認証には、基本認証の方式が使用されます。

Integration Server REST API へのリクエストのアドレスは次の要素で構成されています：

https://{Integration Server のアドレス}:{Integration Server のポート}/{メソッド}?{パラメータ}

各パラメータの説明：

  • {Integration Server のアドレス} – Integration Server の IP アドレス、または完全修飾ドメイン名（FQDN）。
  • {Integration Server のポート} – Integration Server への接続用ポート（既定では 7271 ポート）。
  • {メソッド} – 呼び出すメソッド。
  • {パラメータ} – メソッドのパラメータ（存在する場合）。

時間がかかり、非同期で実行されるリクエストの処理に、タスクが使用されます。このタスクは、クエリの中間結果として作成されます。

このセクションの内容：

テナントで使用するメソッド

レポートで使用するメソッド

タスクで使用するメソッド
ページのトップに戻る
[Topic 199331]

テナントで使用するメソッド

Integration Server REST API を使用して、テナントおよびテナントの仮想マシンの使用時に次の操作を実行できます：

  • テナント情報の取得
  • テナントのリストの取得
  • テナントの仮想マシンのリストの取得
  • 新しいテナントとその保護インフラストラクチャの作成、または既存のテナントの登録
  • テナントの削除
  • テナントのアクティブ化と非アクティブ化
  • テナントの仮想マシンの登録および登録解除

一部の REST API リクエストの結果として実行される一連の動作は、Integration Server データベースにテナントの情報を登録する時に指定したテナントタイプに応じて異なります。Integration Server REST API を使用したテナントの保護インフラストラクチャの導入および削除は、複合的なテナントタイプで可能です。単純なテナントタイプの場合、レポートの受信機能のみが自動化されます。

このセクションの内容：

テナント情報の取得

テナントのリストの取得

テナントの仮想マシンのリストの取得

テナントの新規作成

テナントのアクティブ化

テナントの非アクティブ化

テナントの仮想マシンの登録

仮想マシンの登録解除

テナントの削除
ページのトップに戻る
[Topic 199333]

テナント情報の取得

テナントの仮想マシンの情報が 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 データベース内に、指定した識別子のテナントが見つかりません。
ページのトップに戻る
[Topic 199648]

テナントのリストの取得

全テナントのリスト、Integration Server データベースに保存されている情報、各テナントの情報を取得できます。

メソッド：

GET /api/2.0/virtualization/tenants

リターンコード：

  • 200 (OK) – リクエストが正常に完了しました。レスポンスが、全テナントの情報をリストとして返します。
  • 403 (Forbidden) – リソースへのアクセスが拒否されました。
ページのトップに戻る
[Topic 199332]

テナントの仮想マシンのリストの取得

登録されたテナントの全仮想マシンのリストを取得できます。

メソッド：

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 データベース内に、指定した識別子のテナントが見つかりません。
ページのトップに戻る
[Topic 199649]

テナントの新規作成

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 に存在します。
ページのトップに戻る
[Topic 199650]

テナントのアクティブ化

テナントタイプに応じて、次の動作が実行されます：

  • 複合的なテナントタイプの場合：
    • テナントのステータスを「アクティブ」に変更します。
    • 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 接続設定が指定されていません。
ページのトップに戻る
[Topic 199651]

テナントの非アクティブ化

テナントタイプに応じて、次の動作が実行されます：

  • 複合的なテナントタイプの場合：
    • テナントのステータスを「非アクティブ」に変更します。
    • 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 接続設定が指定されていません。
ページのトップに戻る
[Topic 199652]

テナントの仮想マシンの登録

テナントの仮想マシンの情報を 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 データベースに登録されています。
ページのトップに戻る
[Topic 199653]

仮想マシンの登録解除

テナントの仮想マシンの情報が 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 データベース内に、指定した識別子の仮想マシンが見つかりません。
ページのトップに戻る
[Topic 199654]

テナントの削除

テナントタイプと指定するパラメータに応じて、次の動作が実行されます：

  • 複合的なテナントタイプの場合：
    • テナントとテナントの仮想マシンに関する情報を 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 接続設定が指定されていません。
ページのトップに戻る
[Topic 199655]

レポートで使用するメソッド

Integration Server REST API を使用して、テナントおよびテナントの保護レポートの使用時に次の操作を実行できます：

  • レポートの生成
  • レポートのアップロード

このセクションの内容：

レポートの生成

レポートのアップロード
ページのトップに戻る
[Topic 199638]

レポートの生成

Integration Server データベースに保存されたデータに基づいたレポートを、指定したレポート設定に従って生成できます。レポートの生成対象とする保護対象のテナント、およびデータを受け取る間隔を指定できます。

Accept リクエストのヘッダーに、データの出力フォーマットを指定します：Accept:application/csv

メソッド：

POST /api/2.0/virtualization/reports/tenants?tenantId={テナント ID}&from={日時}&to={日時}

各パラメータの説明：

  • tenantId={テナント ID} - Integration Server 定義データベース内のテナントの識別子。テナントが指定されている場合、このテナントの仮想マシンを保護している期間の情報のみがレポートに含まれます。テナントが指定されていない場合、指定期間内に保護されていた全仮想マシンのデータがレポートに含まれます。
  • from={日時} - レポート対象期間の開始日時。形式：YYYY-MM-DDThh:mm:ss。値が指定されていない場合、Integration Server データベース内の最も初期の日付が使用されます。
  • to={日時} - レポート対象期間の終了日時。形式：YYYY-MM-DDThh:mm:ss。この値を指定しない場合、現在の日付が使用されます。

このリクエストは非同期で実行され、REST API は CreateTenantReport タスクの識別子を返します。このタスクを使用して、レポートの生成処理の進捗を監視できます。タスクの実行が完了すると、［result］フィールドにレポートの識別子またはエラーメッセージが表示されます。

リターンコード：

  • 202 (Accepted) – リクエストの実行が受諾されました。レスポンスは、CreateTenantReport タスクの識別子を返します。
  • 403 (Forbidden) – リソースへのアクセスが拒否されました。
  • 404 (Not Found) – Integration Server データベース内に、指定した識別子のテナントが見つかりません。
ページのトップに戻る
[Topic 199657]

レポートのアップロード

以前に生成したレポートをアップロードします。

Accept リクエストのヘッダーに、データの出力形式を指定します：Accept: application/csv

複数に分割してレポートをアップロードできます。データ範囲を Range リクエストヘッダーで指定できます。例：

Range: bytes=0-1023

このヘッダーを持つリクエストへのレスポンスで、REST API は 206 (Partial content) の結果と、データ先頭のキロバイトを返します。このレスポンスには、 Content-Range ヘッダーと Content-Length ヘッダーが含まれています。

例：

Content-Range: bytes=0-1023/123456

Content-Length: 1024

メソッド：

GET /api/2.0/virtualization/reports/tenants/{レポート ID}

各パラメータの説明：

{レポート ID} - レポートの識別子。CreateTenantReport タスクが成功した結果として取得されます（必須パラメータ）。

リターンコード：

  • 200 (OK) – リクエストが正常に完了しました。レスポンスは、Accept ヘッダーで指定した形式でレポートデータを返します。
  • 206 (Partial content) – リクエストが正常に完了しました。レスポンスは、Range ヘッダーで指定されたレポート部分を返します。
  • 403 (Forbidden) – リソースへのアクセスが拒否されました。
  • 404 (Not Found) – 指定した識別子のレポートが見つかりません。
  • 415 (Unsupported Media Type) – リクエストしたしたデータ形式がサポートされていません（Accept リクエストヘッダーに、誤った形式が渡されました）。
ページのトップに戻る
[Topic 199658]

タスクで使用するメソッド

時間がかかり、非同期で実行されるリクエストの処理に、これらのタスクが使用されます。タスクのステータスにより、リクエストで指定した動作の進行状況を監視できます。

タスクのステータスは次のいずれかです：

  • Created – タスクが作成済みだが開始されていません。
  • Starting – タスクが開始プロセスの途中です。
  • Running – タスクが実行中です。このステータスのタスクは、実行の進捗がパーセンテージで表示されます。
  • Completed – タスクが正常に完了しました。このステータスのタスクは、タスクの実行結果が表示されます。結果にはタスク固有のデータが含まれます。たとえば、CreateTenant タスクの場合は、新しいテナントの識別子が含まれます。
  • Stopping – タスクが完了の準備を進めています。タスクを停止すると、Canceled ステータスに切り替わる前にこのステータスになる場合があります。
  • Failed – タスクが失敗しました。このステータスのタスクは、エラーの詳細情報が表示されます。
  • Canceled – ユーザーまたはシステムによってタスクが終了されました。このステータスのタスクは、エラーの詳細情報が表示されます。
  • Queued – タスクはキューに入り、実行開始を待機している状態です。

Integration Server REST APIを使用して、次のタスクを実行できます：

  • タスクのリストの取得
  • 特定のタスクに関する情報の取得
  • 特定のタスクの実行のキャンセル

このセクションの内容：

タスク情報の取得

タスクのリストの取得

タスクのキャンセル
ページのトップに戻る
[Topic 199637]

タスク情報の取得

タスクに関する情報を識別子で取得します。

メソッド：

GET /api/2.0/virtualization/tasks/{ID}

各パラメータの説明：

{ID} - タスクの識別子（必須パラメータ）。

このリクエストが正常に完了すると、REST API はタスクに関する次の情報を返します：

<task id="{ID}" created="{日時}" stateChanged="{日時}" changed="{日時}">

<state>{ステータス}</state>

<type>{種別}</type>

<stage>{ステージ}</stage>

<progress>{実行の進捗}</progress>

<result>{結果}</result>

<!-- タスクの実行が失敗した場合、エラーメッセージが結果の代わりに表示されます。

<error>{エラーメッセージ}</error>

</task>

各パラメータの説明：

  • {ID} – タスク ID。
  • created="{日時}" - タスクの作成日時。形式：YYYY-MM-DDThh:mm:ss。
  • stateChanged="{日時}" – タスクの変更日時。形式：YYYY-MM-DDThh:mm:ss。
  • changed="{日時}" - タスクの変更日時。形式：YYYY-MM-DDThh:mm:ss。
  • {ステータス} - タスクのステータス。
  • {種別} - タスクの種別。例：
  • {名前} - タスク名。
  • {ステージ} - タスク実行のステージ。
  • {実行の進捗} – タスクの進捗状況をパーセンテージで示します。
  • {結果} - タスクの実行結果。例：作成したテナントの情報またはレポートの識別子など。
  • {エラーメッセージ} - タスクの実行中にエラーが発生すると、エラーメッセージが表示されます。

リターンコード：

  • 200 (OK) – リクエストが正常に完了しました。
  • 403 (Forbidden) – リソースへのアクセスが拒否されました。
  • 404 (Not Found) – Integration Server データベース内に、指定した識別子のタスクが見つかりません。
ページのトップに戻る
[Topic 199646]

タスクのリストの取得

既存の全タスクのリストと、各タスクに関する情報を取得できます。

メソッド：

GET /api/2.0/virtualization/tasks?createdFrom={日時}&state={ステータス}&type={種別}

各パラメータの説明：

  • createdFrom={日時} - YYYY-MM-DDThh:mm:ss 形式の日時（任意のパラメータ）。このパラメータを指定すると、指定した日時以降に作成されたタスクがリストに表示されます。
  • state={ステータス} - タスクのステータス（任意のパラメータ）。このパラメータを指定すると、指定したステータスのタスクのみがリストに表示されます。
  • type={種別} - タスクの種別（任意のパラメータ）。このパラメータを指定すると、指定した種別のタスクのみがリストに表示されます。

リターンコード：

  • 200 (OK) – リクエストが正常に完了しました。レスポンスが、タスクのリストを返します。
  • 403 (Forbidden) – リソースへのアクセスが拒否されました。
ページのトップに戻る
[Topic 199645]

タスクのキャンセル

実行中のタスクを中断します。一部のタスクはすぐに完了させることができません。この場合、202 (Accepted) コードが返され、タスクのステータスが停止中に変更されます。

メソッド：

POST /api/2.0/virtualization/tasks/{ID}/cancel

各パラメータの説明：

{ID} - タスクの識別子（必須パラメータ）。

リターンコード：

  • 200 (OK) – リクエストが正常に完了しました（タスクがキャンセルされます）。
  • 202 (Accepted) – リクエストの実行が受諾されました（タスクのステータスが停止中に変更されます）。
  • 403 (Forbidden) – リソースへのアクセスが拒否されました。
  • 404 (Not Found) – 指定した識別子のタスクが見つかりません。
  • 405 (Method Not Allowed) – 子タスクの場合：親タスクをキャンセルした場合にのみ、子タスクをキャンセルできます。
  • 409 (Conflict) – タスクのステータスが既に次のいずれかになっています：Cancelled、Failed、Stopped。
ページのトップに戻る
[Topic 199647]