他のプログラミング言語の呼び出し

注記

1. スクリプトを使用して外部プログラムを呼び出すには、Apidog のバージョンが >= 1.0.25 である必要があります。
2. 外部プログラムは「サンドボックス環境」の外で実行され、コンピューター上の他のプログラム、ファイル、およびデータを操作するアクセス権を持ちます。これにより、セキュリティ上のリスクが生じます。ユーザーは、呼び出されたプログラムのセキュリティを確認する必要があります。

外部プログラムは、「外部プログラム ディレクトリ」に保存されるコード ファイルで、Java プログラム アーカイブ ファイル (.jar パッケージ) または他のプログラムのコード ソース ファイルである可能性があります。次のような拡張子のファイルをサポートしています:

• java (.jar)
• python (.py)
• php (.php)
• js (.js)
• BeanShell (.bsh)
• go (.go)
• shell (.sh)
• ruby (.rb)
• lua (.lua)
• .bat (.bat)
• .ps1 (.ps1)

「外部プログラム ディレクトリ」は、次の方法で簡単に開くことができます:

外部プログラムを呼び出すと、Apidog はサブプロセスを開始し、コマンドライン実行を使用して指定された外部プログラムをサブプロセス内で実行します。最後に、サブプロセスの標準出力 (stdout) が呼び出しの結果として返されます。呼び出しプロセス全体において、コアロジックは外部プログラムでユーザーによって実装されますが、Apidog は主に次の 3 つの手順を実行します:

1. 提供されたパラメータに基づいてコマンド文字列を結合する
2. コマンドを実行する
3. 結果を返す

その中で、最初の手順は呼び出しの原則を理解するための鍵となります。Apidog は、コマンドを連結するために「コマンドプレフィックス + プログラムパス + パラメータリスト」という式を使用します。

「コマンドプレフィックス」は、プログラムファイルのファイル拡張子から推測されます。「プログラムパス」と「パラメータリスト」は、呼び出し時にユーザーが提供します。

たとえば、pm.execute('com.apidog.Base64EncodeDemo.jar', ['abc','bcd']) の場合、実際に実行されるコマンドは java -jar "com.apidog.Base64EncodeDemo.jar" "abc" "bcd" です。

プログラム ファイル拡張子とコマンド プレフィックス間のマッピング:

言語	コマンドプレフィックス	ファイル拡張子
Java	java -jar	.jar
Python	python	.py
PHP	php	.php
JavaScript	node	.js
BeanShell	java bsh.Interpreter	.bsh
Go	go run	.go
Shell	sh	.sh
Ruby	ruby	.rb
Lua	lua	.lua
Rust	cargo run	.rs
Python	python	.py
Windows Batch File	cmd /c	.bat
Windows PowerShell Script File	powershell	.ps1

API

pm.executeAsync

• filePath 文字列 外部プログラムパス

• args string[] パラメータ。jarパッケージ内の指定されたメソッドを呼び出す場合、変換には JSON.stringify が使用されます。それ以外の場合、文字列以外の型は暗黙的に文字列に変換されます。

• options Object

  • command 文字列外部プログラムの実行コマンド。「コマンド プレフィックス」の最初の部分が実行コマンドです。オプションで、デフォルト値は自動的に推測されます (上記の「コマンド プレフィックス」の表を参照)。任意のプログラムに合わせてカスタマイズできます。
  • cwd string サブプロセスの作業ディレクトリ。オプション、デフォルトは「外部プログラム ディレクトリ」です。
  • env Record<string, string> サブプロセスの環境変数。 オプション、デフォルトは {}。
  • windowsEncoding string Windows システムで使用されるエンコーディング。オプション、デフォルトは "cp936" です。
  • className 文字列 jar パッケージで呼び出すクラス名を指定します (例: "com.apidog.Utils")。オプション。詳細については、jar パッケージ内の指定されたメソッドを呼び出すを参照してください。
  • method 文字列 jar パッケージで呼び出すメソッド名を指定します (例: "add")。オプション (className に値がある場合は必須)。詳細については、jar パッケージで指定されたメソッドを呼び出す を参照してください。
  • paramTypes string[] jar パッケージで呼び出すメソッドのパラメータ タイプを指定します (例: ["int", "int"])。オプション,デフォルトはパラメータに基づいて自動的に推測されます。詳細については、jar パッケージで指定されたメソッドを呼び出すを参照してください。

• Return: Promise<string>

備考

commandパラメータの使用:

デフォルトでは、Apidog は python を使用して .py ファイルを実行します。コンピューターに python3 がすでにインストールされている場合は、コマンドを python3 として指定できます。

pm.executeAsync('./demo.py', [], { command: 'python3' }).then(res => {
   console.log('result: ', res);
});

pm.execute

ヒント

代わりに pm.executeAsyncを使用することをお勧めします。詳細については、コード移行手順を参照してください。

pm.execute(filePath, args, options)

• filePath string 外部プログラムパス

• args string[] パラメータ。jarパッケージ内の指定されたメソッドを呼び出す場合、変換には JSON.stringify が使用されます。それ以外の場合、文字列以外の型は暗黙的に文字列に変換されます。

• options Object

  • windowsEncoding Windowsシステムで使用される文字列エンコーディング。オプション、デフォルトはcp936です。

  • className 文字列 jarパッケージで呼び出すクラス名を指定します (例: "com.apidog.Utils")。オプション。詳細については、jar パッケージ内の指定されたメソッドを呼び出すを参照してください。

  • method 文字列 jarパッケージで呼び出すメソッド名を指定します (例: "add")。オプション (className に値がある場合は必須)。詳細については、jar パッケージで指定されたメソッドを呼び出すを参照してください。

  • paramTypes string[] jar パッケージで呼び出すメソッドのパラメータ タイプを指定します (例: ["int", "int"])。オプション。デフォルトはパラメータに基づいて自動的に推測されます。詳細については、jar パッケージで指定されたメソッドを呼び出すを参照してください。

• Return: string

実行とログ

プログラムを実行すると、実行されたコマンドがコンソールに表示されます (参照のみ)。結果が期待どおりでない場合は、コマンドをコピーして Shell/CMD に貼り付けてデバッグできます。

コンソールには、実行されたプロセスの「標準出力 (stdout)」と「標準エラー出力 (stderr)」も表示されます。stdout の内容 (末尾の改行文字を除く) が実行の最終結果になります。

ヒント

歴史的な理由から、pm.execute は stderr に内容がある場合、実行が失敗したと見なします。これにより、一部のプログラムは警告やエラーメッセージを出力すると失敗します。pm.executeAsync は、プロセスの終了コードを使用して実行が失敗したかどうかを判断するように変更されました。

外部プログラムの入力と出力

パラメータ

指定された外部プログラムはコマンドライン実行で動作するため、渡されたパラメータはコマンドライン引数を通じてのみ取得できます。

例えば、スクリプト pm.executeAsync('add.js', [2, 3]) では、実際に実行されるコマンドは node add.js 2 3 です。外部スクリプト add.js 内でパラメータを取得するには、次のようにします:

let a = parseInt(process.argv[1]); // 2  
let b = parseInt(process.argv[2]); // 3

ヒント

1. 異なるプログラミング言語にはコマンドライン引数を取得する方法がそれぞれ異なりますので、対応する言語のドキュメントを参照してください。
2. コマンドライン引数の型は常に文字列であり、実際の型に基づいて変換する必要があります。

戻り値

前述の通り、Apidog は標準出力stdoutの内容をプログラム実行の結果として使用します。そのため、標準出力に内容を出力することで結果を返すことができます。

例えば、スクリプト内で const result = await pm.executeAsync('add.js', [2, 3]) の場合、次のようにして結果を返すことができます:

console.log(parseInt(process.argv[1]) + parseInt(process.argv[2]));

ヒント

1. 異なるプログラミング言語には、それぞれ標準出力（stdout）に出力する方法が異なりますので、対応する言語のドキュメントを参照してください。
2. 戻り値の型は 文字列 であり、実際の型に基づいて変換する必要があります。
3. 結果の末尾の改行文字は削除されます。
4. jar パッケージ内の指定されたメソッドを呼び出す場合、呼び出されたメソッドの戻り値が最終的な戻り値として使用されます。

エラーのスロー

エラーをスローすると、現在のタスクが失敗し、実行が停止します。例えば:

throw Error("Execution failed"); 

ヒント

1. 異なるプログラミング言語にはエラーをスローする方法がそれぞれ異なりますので、対応するドキュメントを参照してください。
2. JavaScript では、console.error('Error') はエラーをスローせず、単にstderrに出力するだけです。他の言語を使用する際もこの点を考慮してください。

デバッグ情報

pm.executeAsyncはstderrではなく終了コードを使用して成功かどうかを判断するため、stderrを使用してデバッグ情報を出力しても、実行に影響を与えることはありません。

例えば:

console.warn("debug info");
console.error("error info");

ヒント

1. この方法でデバッグ情報を出力できるのは pm.executeAsync のみです。
2. 異なるプログラミング言語は、それぞれ stderr へ出力する方法が異なりますので、対応するドキュメントを参照してください。

pm.execute から pm.executeAsync への移行

pm.executeAsync の戻り値はPromise型なので、execute を直接 executeAsync に変更することはできません。しかし、async/await を使用して最小限の変更で移行できます。

ヒント

Apidog バージョン >= 2.3.24（CLI バージョン >= 1.2.38）はトップレベル awaitをサポートしています。

手順:

1. execute を executeAsync に変更
2. 関数呼び出しの前に await を追加

// Before
const result = pm.execute("add.js", [3, 4]); 
pm.environment.set("result", result);

const result = await pm.executeAsync("add.js", [3, 4]);
pm.environment.set("result", result);

Jar パッケージ内の指定されたメソッドの呼び出し

ヒント

この機能には Apidog バージョン >= 2.1.39 が必要です。内部ランタイムリフレクションを使用する Spring Boot のような Jar ではなく、リフレクションによって Jar を呼び出すことのみをサポートします。

デフォルトでは、Jar を呼び出すと Main クラスの main メソッドが実行されます。options.classNameが指定されている場合、デフォルトの動作が上書きされ、Jar 内の指定されたメソッドが呼び出されます。

Jar内の指定されたメソッドを呼び出すことは、他の外部プログラムとは異なります。Apidog は組み込みのエグゼキューターを使用して、リフレクションによって Jar 内のメソッドを見つけて呼び出します。呼び出されたメソッドに戻り値がある場合、戻り値は文字列に変換され、最終的な戻り値として使用されます。それ以外の場合、他の呼び出しと同様に標準出力の内容が戻り値として使用されます。

例えば:

await pm.executeAsync('./scripts/jar-1.0-SNAPSHOT.jar', ['hello', 'world'], {
    className: 'com.apidog.Test', 
    method: 'combine',
    paramTypes: ['String', 'String']
})

実際に実行されるコマンドは:

java -jar "<app-dist>/assets/JarExecuter-1.1.0-jar-with-dependencies.jar" ./scripts/jar-1.0-SNAPSHOT.jar "com.apidog.Test.combine(String,String)" "\"hello\"" "\"world\""

<app-dist>/assets/JarExecuter-1.1.0-jar-with-dependencies.jarは組み込みのエグゼキューターであり、リフレクションを通じてユーザープログラム./scripts/jar-1.0-SNAPSHOT.jar内のメソッドcom.apidog.Test.combine(String,String)を見つけ、パラメーター（JSON 文字列）"hello" と "world" を使用して呼び出します。

備考

paramTypesは任意です。指定されていない場合、タイプはパラメーターに基づいて自動的に推測されます。整数は"int"、浮動小数点は "double"、ブール値は "boolean"、文字列は "String" として推測され、配列は最初の要素に基づいて推測されます。例えば、[3] は "int[]"、[3.14] は "double[]" として推測されます。 推測されたタイプが呼び出されるメソッドの実際のパラメータータイプと一致しない場合、paramTypesを手動で指定する必要があります。 paramTypes配列でサポートされている値は次のとおりです："Number"、"int"、"Integer"、"long"、"Long"、"short"、"Short"、"float"、"Float"、"double"、"Double"、"boolean"、"Boolean"、"String"、"Number[]"、"int[]"、"Integer[]"、"long[]"、"Long[]"、"short[]"、"Short[]"、"float[]"、"Float[]"、"double[]"、"Double[]"、"boolean[]"、"Boolean[]"、"String[]"。

したがって、上記の例ではparamTypesを省略することができます:

await pm.executeAsync('./scripts/jar-1.0-SNAPSHOT.jar', ['hello', 'world'], {
    className: 'com.apidog.Test',
    method: 'combine' 
})

例

1. PHP プログラム

Script:

const param1 = { a: 1, b: 2 }
const resultString = await pm.executeAsync('test.php', [JSON.stringify(param1)])
const result = JSON.parse(resultString)
console.log('Result:', result) // Result: { a: 2, b: 4 }

test.php:

<?php
$param = json_decode($argv[1]);
$result = [];
foreach($param as $key=>$value)
{
    $result[$key] = $value * 2;
}
echo json_encode($result);

2. Jar プログラム

Script:

const result = await pm.executeAsync('com.apidog.utils.jar', [3, 5], {
   className: 'com.apidog.utils.Utils',  
   method: 'add',
   paramTypes: ['Integer', 'Integer']
})
console.log('Result:', result) // Result: 8

com.apidog.utils.jar:

package com.apidog.utils;

public class Utils {
    public Integer add(Integer a, Integer b) {
        return a + b;
    }
};

一般的な問題

1. 一部のプログラムはプロジェクトの設定ファイルが必要で、設定ファイルがないとエラーが発生します

Rust と Go:

Rust:

could not find `Cargo.toml` in `<...>/ExternalPrograms` or any parent directory

Go:

go.mod file not found in current directory or any parent directory; see 'go help modules'

解決策： pm.executeAsync を使用し、cwdを指定してください。

2. MacOS には Python 3 が組み込まれていますが、Python 2 はありません

pm.executeAsync を使用し、commandを "python3"に設定します。

3. コマンド xxx が見つかりません

該当プログラムをインストールし、必要なディレクトリをシステムの PATH に追加します。Java のインストールについては docs を参照してください。

4. 一部の Windows システムで外部スクリプトを呼び出すと文字化けが発生する

windowsEncodingを'utf-8'に設定します。

var result = pm.execute(`hello.go`, [], { windowsEncoding: 'utf-8' })