O Apidog permite que você execute programas externos (scripts, JARs, binários) a partir do seu ambiente Javascript. Isso permite que você aproveite código existente em linguagens como Java, Python, PHP, Go, Shell etc.Programas externos são executados fora do sandbox do Apidog e têm acesso total ao seu sistema. Certifique-se de confiar no código que você está executando.
Linguagens Compatíveis#
O Apidog infere o comando de execução com base nas extensões dos arquivos:| Linguagem | Extensão | Prefixo do Comando |
|---|
| Java | .jar | java -jar |
| Python | .py | python |
| Node.js | .js | node |
| PHP | .php | php |
| Go | .go | go run |
| Shell | .sh | sh |
| Ruby | .rb | ruby |
| Lua | .lua | lua |
Como Chamar Programas Externos#
1.
Abrir o Diretório de Programas Externos: Clique no ícone de pasta no editor de scripts para abrir o diretório onde seus scripts externos devem ser colocados. 2.
Executar via Script: Use pm.executeAsync para chamar o programa. Referência da API#
pm.executeAsync#
filePath string Caminho do programa externo
args string[] Parâmetros. Ao chamar métodos especificados em um pacote jar, JSON.stringify será usado para conversão. Exceto nesse caso, tipos não string serão convertidos implicitamente para string.
command string O comando de execução do programa externo; a primeira parte do "prefixo do comando" é o comando de execução. Opcional, o valor padrão é inferido automaticamente (consulte a tabela de "prefixo do comando" acima), pode ser personalizado para qualquer programa.
cwd string Diretório de trabalho do subprocesso. Opcional, o padrão é "Diretório de Programas Externos".
env Record<string, string> Variáveis de ambiente do subprocesso. Opcional, o padrão é {}.
windowsEncoding string Codificação usada no sistema Windows. Opcional, o padrão é "cp936".
className string Especifique o nome da classe a ser chamada no pacote jar, por exemplo, "com.apidog.Utils".
method string Especifique o nome do método a ser chamado no pacote jar, por exemplo, "add".
paramTypes string[] Especifique os tipos de parâmetro do método a ser chamado no pacote jar, por exemplo, ["int", "int"].
Por padrão, o Apidog usa python para executar arquivos .py. Se python3 já estiver instalado no computador, command poderá ser especificado como python3. pm.execute#
Recomenda-se usar pm.executeAsync em vez disso.
pm.execute(filePath, args, options)filePath string Caminho do programa externo
args string[] Parâmetros. Ao chamar métodos especificados em um pacote jar, JSON.stringify será usado para conversão. Exceto nesse caso, tipos não string serão convertidos implicitamente para string.
windowsEncoding string Codificação usada no sistema Windows. Opcional, o padrão é "cp936".
className string Especifique o nome da classe a ser chamada no pacote jar, por exemplo, "com.apidog.Utils".
method string Especifique o nome do método a ser chamado no pacote jar, por exemplo, "add".
paramTypes string[] Especifique os tipos de parâmetro do método a ser chamado no pacote jar, por exemplo, ["int", "int"].
Execução e Logs#
Ao executar um programa, o comando executado será impresso no console (somente para referência). Se o resultado não atender às expectativas, você poderá copiar o comando e colá-lo em Shell/CMD para depurar.O console também imprimirá a "saída padrão (stdout)" e a "saída de erro padrão (stderr)" do processo executado. O conteúdo de stdout (excluindo o caractere de nova linha final) será o resultado final da execução.Por motivos históricos, pm.execute trata a execução como falha quando há conteúdo em stderr. Isso faz com que alguns programas falhem ao gerar avisos ou mensagens de erro. pm.executeAsync passa a usar o código de saída do processo para determinar se a execução falhou.
Entrada e Saída de Programas Externos#
Parâmetros#
Como o programa externo especificado é executado pela linha de comando, ele só pode obter os parâmetros passados por meio de argumentos da linha de comando.Por exemplo, no script pm.executeAsync('add.js', [2, 3]), o comando realmente executado é node add.js 2 3. Para obter os parâmetros no script externo add.js:1.
Diferentes linguagens de programação têm diferentes formas de obter argumentos da linha de comando; consulte a documentação da linguagem correspondente.
2.
O tipo dos argumentos da linha de comando é sempre string; é necessário converter com base nos tipos reais.
Valor de Retorno#
Como mencionado acima, o Apidog usa o conteúdo de stdout como o resultado da execução do programa. Portanto, imprimir conteúdo em stdout pode retornar resultados.Por exemplo, no script const result = await pm.executeAsync('add.js', [2, 3]), o resultado pode ser retornado por:1.
Diferentes linguagens de programação têm diferentes formas de imprimir em stdout; consulte a documentação da linguagem correspondente.
2.
O tipo de retorno é string; é necessário converter com base nos tipos reais.
3.
O caractere de nova linha final do resultado será removido.
4.
Ao chamar métodos especificados em pacotes jar, o valor de retorno do método chamado será usado como o valor de retorno final.
Lançando Erros#
Lançar erros pode fazer a tarefa atual falhar e interromper a execução. Por exemplo:1.
Diferentes linguagens de programação têm diferentes formas de lançar erros; consulte a documentação correspondente.
2.
Em JavaScript, console.error('Error') apenas imprime em stderr, em vez de lançar um erro. Considere isso também ao usar outras linguagens.
Como pm.executeAsync usa o código de saída em vez de stderr para determinar o sucesso, stderr pode ser usado para imprimir informações de depuração sem afetar a execução.1.
Somente pm.executeAsync oferece suporte a essa forma de imprimir informações de depuração.
2.
Diferentes linguagens de programação têm diferentes formas de imprimir em stderr; consulte a documentação correspondente.
Migrar de pm.execute para pm.executeAsync#
Como o valor de retorno de pm.executeAsync é do tipo Promise, execute não pode ser alterado diretamente para executeAsync. Mas você pode usar async/await para migrar com alterações mínimas.O Apidog versão 2.3.24 ou posterior (CLI versão 1.2.38 ou posterior) oferece suporte a top-level await.
1.
Altere execute para executeAsync
2.
Adicione await antes da chamada da função
Chamar Métodos Especificados em Pacotes .jar#
Este recurso requer que a versão do Apidog seja 2.1.39 ou posterior. Ele oferece suporte apenas à chamada de jars com reflection, não a jars como Spring Boot que usam reflection interna em tempo de execução.
Por padrão, chamar um jar invocará o método main na classe Main. Se options.className for especificado, ele substituirá o comportamento padrão e chamará o método especificado no jar em vez disso.Chamar métodos especificados em jars é diferente de outros programas externos. O Apidog usará um executor integrado para encontrar o método no jar por reflection e chamá-lo. Se o método chamado tiver um valor de retorno, ele será usado como o valor de retorno final após a conversão para string. Caso contrário, funcionará da mesma forma que outras chamadas, usando o conteúdo de stdout como valor de retorno.O comando realmente executado é:Onde <app-dist>/assets/JarExecuter-1.1.0-jar-with-dependencies.jar é o executor integrado, responsável por encontrar o método com.apidog.Test.combine(String,String) no programa do usuário ./scripts/jar-1.0-SNAPSHOT.jar por meio de reflection, e chamá-lo com os parâmetros (string JSON) "hello" e "world".paramTypes é opcional. Se não for especificado, os tipos serão inferidos automaticamente com base nos parâmetros. Inteiros são inferidos como "int", floats como "double", booleanos como "boolean", strings como "String", arrays são inferidos com base no primeiro elemento, por exemplo, [3] é inferido como "int[]", [3.14] como "double[]" etc.
Se os tipos inferidos não corresponderem aos tipos de parâmetro reais do método chamado, paramTypes precisará ser especificado manualmente.
Valores compatíveis no array 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[]"Portanto, o paramTypes no exemplo acima pode ser omitido:Exemplos#
1. Programa PHP#
2. Programa Jar#
Problemas Comuns#
1. Alguns programas exigem arquivos de configuração de projeto e gerarão erro se eles estiverem ausentes#
could not find `Cargo.toml` in `<...>/ExternalPrograms` or any parent directory
go.mod file not found in current directory or any parent directory; see 'go help modules'
Solução: Use pm.executeAsync e especifique cwd.2. MacOS tem Python 3 integrado, mas não Python 2#
Use pm.executeAsync e defina command como "python3".3. Command xxx not found#
Instale o programa correspondente e adicione os diretórios necessários ao PATH do sistema. Consulte a documentação para a instalação do Java.4. Chamar scripts externos imprime caracteres ilegíveis em alguns sistemas Windows#
Defina windowsEncoding como 'utf-8'