お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

PowerShellエンジン

Bridgeでは、［PowerShellエンジン］タブを使用して、PowerShellスクリプトによりクライアントのネットワーク内の任意のWindowsマシンで操作を実行できます。

前提条件

認証情報の作成時に、［種類］として ［PowerShell］を選択し、［ユーザー名］と［パスワード］（PowerShellスクリプトを実行するマシンのもの）を入力します。 こちらをクリックして、認証情報の作成方法を確認してください。

PowerShellタスクの設定  

PowerShellリモート処理の有効化  

Bridgeエージェントを使用してWindows環境でPowerShellタスクを実行するには、リモート処理を有効にする必要があります。有効にする方法は2つあります。

• リモートセッション（デフォルト）。

• タスクを正常に実行するには、PowerShellリモート処理がデフォルトで有効になっている必要があります。PowerShellエンジンタスクはローカル（Bridgeがインストールされている）マシンでのみ実行されます。一方、その他のPowerShellタスクステートは、ローカルマシンとリモートマシンの両方で動作します。

• ローカルホストでリモート処理を有効にするには、コマンド Enable-PSRemoting を使用します。 詳細はこちら。

• リモート処理の状態を確認する、または手動で有効にするには、コマンド winrm quickconfig を使用します。詳細については、 こちらをご参照ください。

• リモートセッションなし。

• リモートセッションを使用せずにPowerShellスクリプトを直接実行する場合、この機能はデフォルトでは利用できません。手動で設定する必要があります。

• 手順。

1. Bridgeのインストールフォルダー内の Bridge → config → powershell.properties に移動します。

2. 次のプロパティ bridge.pwsh.script.execute.session=false を追加します。

3. Windowsで、サービスを開き、Qntrl Bridgeを探して、［再起動］をクリックします。

• この設定後、PowerShellタスクは非リモートセッションで実行されます。
  

次のセクションでは、［PowerShellエンジン］タブに関連するタスクと、Bridgeを使用してタスクを実行するための要求データについて説明します。

［PowerShellエンジン］タブを使用してタスクを実行するには、Windowsマシン間で安定したネットワーク接続が必要です。

要求データの共通キー

PowerShell Engine

要求データ  

{ 'task_details': {       'activity_name': 'file',       'execution_path': '<PATH_OF_EXECUTABLE_FILE>',       'host': '<HOST_NAME>',       'script_name': '<SCRIPT_FILE_NAME>' }, 'credential': {       'name': '<CREDENTIAL_NAME>' }, 'task_name': 'pwsh_task' }

WindowsAppのインストール

{ 'task_details': {       'activity_name': 'install_app',       'execution_path': '<PATH OF EXECUTABLE FILE>',       'host': '<HOST_NAME>',       'file_path': '<PATH FOR THE APP TO BE INSTALLED>',       'msi_file_name': '<NAME OF THE MSI FILE>' }, 'credential': {       'name': '<CREDENTIAL_NAME>' }, 'task_name': 'pwsh_task' }

WindowsAppのアンインストール

{ 'task_details': {       'activity_name': 'uninstall_app',       'execution_path': '<PATH OF EXECUTABLE FILE>',       'host': '<HOST_NAME>',       'app_name': '<APPLICATION_NAME>' },    'credential': {       'name': '<CREDENTIAL_NAME>' }, 'task_name': 'pwsh_task' }

サービスの開始

要求データ  

{ 'task_details': {       'activity_name': 'start_service',       'execution_path': '<PATH OF EXECUTABLE FILE>',       'host': '<HOST_NAME>',       'service_name': '<NAME OF THE SERVICE>' }, 'credential': {       'name': '<CREDENTIAL_NAME>' }, 'task_name': 'pwsh_task' }

サービスの停止

{ 'task_details': {       'activity_name': 'stop_service',       'execution_path': '<PATH OF EXECUTABLE FILE>',       'host': '<HOST_NAME>',       'service_name': '<NAME OF THE SERVICE>' }, 'credential': {       'name': '<CREDENTIAL_NAME>' }, 'task_name': 'pwsh_task' 
}  

Windowsサーバーの再起動

{ 'task_details': {       'activity_name': 'restart_server',       'execution_path': '<PATH OF EXECUTABLE FILE>',       'host': '<HOST_NAME>' }, 'credential': {       'name': '<CREDENTIAL_NAME>' }, 'task_name': 'pwsh_task' 
}

再起動タスクは、ログイン中のユーザーがいない場合にのみ実行できます。ログイン中のユーザーがいる場合、再起動は実行できません。

トラブルシューティング

1. WindowsマシンでPowerShellタスクが実行されない理由

• 対象マシンでPowerShell Remotingが有効になっていることを確認します。
• PowerShellで Enable-PSRemoting コマンドを実行します。
• または、winrm quickconfigでリモート処理を確認します。

2. リモートセッションを使用せずにPowerShellスクリプトを実行する方法

• 次の場所に移動します：Bridge/config/powershell.properties

• 次の行を追加します：bridge.pwsh.script.execute.session=false

• その後、Windowsサービスから Qntrl Bridge サービスを再起動します。

3. 認証情報を入力してもPowerShellタスクが失敗する理由

この問題には、一般的にいくつかの原因があります。次の項目を確認してください。

認証情報名は正しいですか？

認証情報名が、要求データで指定した名前と一致していることを確認します。

ユーザー名の形式は正しいですか？

形式は、マシンがドメインに参加しているかどうかによって異なります。

• ドメインを使用していない場合：<hostname>\<username>

• ドメインに参加している場合：<domainname>\<username>

パスワードは有効ですか？

• パスワードが正しいことを確認します。

• パスワードの有効期限が切れておらず、最近変更されていないことを確認します。

PowerShellでの認証情報のテスト  

ユーザー名とパスワードが有効かどうかを手動で確認するには、次のコマンドを実行します。

Enter-PSSession -ComputerName localhost -Credential $cred

• ログインプロンプトが表示されます。

• 認証情報が有効な場合、セッションに接続されます。

• 無効な場合、PowerShellにエラーが表示されます。

4. PowerShellスクリプト実行失敗のデバッグ方法 

• 設定項目execution_pathが、インストール済みのPowerShell実行ファイルを正しく指していることを確認します。

• 設定項目 script_nameが正しく、タスクにアップロードされていることを確認します。

• host（対象マシン）にBridgeをインストールしたマシンから到達できるか確認します。

• 次の場所にあるBridgeログを確認します：<Bridge-Path>/logs/

5. アプリのインストールまたはアンインストール時にPowerShellタスクがエラーを返す理由 

• パラメーターfile_pathと msi_file_nameが正しく、対象マシンからアクセスできることを確認します。

• アンインストールの場合、app_nameがインストール済みアプリケーション名と完全に一致していることを確認します。

6. サーバー再起動タスクが動作しない理由 

• 対象マシンに現在ログインしているユーザーがいる場合、再起動は失敗します。

• マシンがアイドル状態であることを確認してから、 restart_server アクティビティを実行します。

7. サービスが想定どおりに開始または停止しない理由 

• 設定項目 service_nameが実際のサービス名（大文字と小文字を区別）と一致していることを確認します。

• 認証情報のユーザーにWindowsサービスを管理する権限があることを確認します。

8. PowerShell Engineタスク実行中のホストまたは認証情報エラーの解決方法

• パラメーター hostのIP／名前にBridgeサーバーからアクセスできることを確認します。

• Bridgeと対象マシン間のネットワーク接続を確認します。

9. Bridgeが非アクティブに表示される／PowerShellタスクがトリガーされない場合の対応 

• Windowsのサービスまたはコマンドラインから、Qntrl Bridgeサービスを再起動します。

• エラーの有無を確認するため、<Bridge-Path>/logs/のログを確認します。

• PowerShellリモート処理またはセッション設定に誤りがないか確認します。
  

10. ホスト項目にBridgeサーバーとは別のADドメインコントローラーを指定してスクリプトを実行する可否

11. スクリプトで一部の処理が実行されず、結果が空になる場合の修正方法

この問題は、Bridgeサービスが十分な権限を持たないローカルシステムアカウントで実行されている場合に発生することがあります。

この問題を解決するには、ローカルシステムアカウントに必要な権限を付与するか、必要なすべての権限を持つ別のアカウントでBridgeサービスが実行されるように設定します。

手順は次のとおりです。

1. オンプレミスのWindowsマシンで、サービスを開き、Qntrl Bridgeを探します。

2. 対象を右クリックし、［プロパティ］を選択します。

3. ［ログオン］タブで、［このアカウント］を選択し、必要な権限を持つユーザーアカウントを設定します。

                        

12. PowerShellでADコマンドを使用するための追加ツールの要否

はい。AD PowerShellコマンドを実行するには、BridgeマシンにRemote Server Administration Tool（RSAT）をインストールする必要があります。

RSATがない場合、Active Directoryモジュールを読み込めず、AD関連のPowerShellタスクは失敗します。

13. PowerShellでActive Directoryモジュールを使用するためのBridgeサーバーへのADツールのインストールの要否

はい。PowerShellでADコマンドをローカル実行するには、Active Directoryモジュール（RSAT – Remote Server Administration Tools）をインストールする必要があります。RSATは標準ではプリインストールされていないため、Bridgeがインストールされているマシンに追加してください。