Documentação para desenvolvedores

Shortcuts e x-callback-url

Automatize verificações de throughput, validação de endpoints e coleta de resultados com ações integradas e endpoints de callback.

Visão Geral

O iPerf3 Client & Server expõe duas camadas de automação:

Ações nativas do Apple Shortcuts (recomendado para a maioria dos usuários)
Endpoints x-callback-url para fluxos de trabalho de app para app programáveis

Esquema de URL Base

Use iperf3cs://x-callback-url/... para automação baseada em callback.

Compatibilidade

Os requisitos atuais da plataforma Apple são iOS/iPadOS 16.6+, macOS 13.5+ e visionOS 1.0+.

Ações Integradas de Shortcuts

Essas ações estão disponíveis diretamente no app Apple Shortcuts:

Executar Teste iPerf

Executa um teste com servidor, protocolo, direção e temporização configuráveis. A duração padrão típica no fluxo de Shortcuts é de 5 segundos.

Obter Último Resultado

Retorna o resultado completo mais recente do histórico local.

Testar Servidor

Verifica a disponibilidade do endpoint antes de uma execução completa.

Listar Servidores

Retorna servidores configurados para automação orientada por menu.

Endpoints x-callback-url

GETiperf3cs://x-callback-url/run-test

Inicia um novo teste e opcionalmente retorna via URLs de callback.

Parâmetro	Tipo	Obrigatório	Descrição
`server`	String	Sim	Nome do host ou IP do endpoint iPerf3.
`protocol`	String	Não	`tcp` (padrão) ou `udp`.
`direction`	String	Não	`download`, `upload` ou `bidirectional`.
`durationSec`	Integer	Não	Duração em segundos. O padrão comum na automação é 5.
`streams`	Integer	Não	Contagem de streams paralelos.
`x-success`	String	Não	URL de callback para payload de sucesso.
`x-error`	String	Não	URL de callback para payload de erro.

GETiperf3cs://x-callback-url/get-last-result

Retorna o resultado local mais recente, útil para fluxos de trabalho de registro periódico.

Parâmetro	Tipo	Obrigatório	Descrição
`x-success`	String	Não	URL de callback para payload de sucesso.
`x-error`	String	Não	URL de callback para erros.

GETiperf3cs://x-callback-url/test-server

Verifica a acessibilidade do endpoint e retorna metadados de status/latência.

Parâmetro	Tipo	Obrigatório	Descrição
`server`	String	Sim	Nome do host ou IP para testar.
`port`	Integer	Não	Valor da porta (padrão 5201).

Exemplos

Executar teste com callbacks

 iperf3cs://x-callback-url/run-test?server=iperf.example.com&protocol=tcp&direction=download&durationSec=8&x-success=shortcuts://run-shortcut?name=StoreResult 

Ler resultado mais recente

 iperf3cs://x-callback-url/get-last-result?x-success=shortcuts://run-shortcut?name=PushSummary 

Iniciar pelo terminal no macOS

 open "iperf3cs://x-callback-url/run-test?server=10.0.1.5&protocol=udp&direction=bidirectional&durationSec=5" 

Campos típicos do payload

 {
  "testId": "A8B3D9",
  "timestamp": "2026-02-26T09:42:10Z",
  "server": "iperf.example.com",
  "protocol": "tcp",
  "downloadMbps": 942.7,
  "uploadMbps": 876.4,
  "status": "completed"
} 

Tratamento de Erros

Quando uma ação falha e x-error está presente, o callback recebe um objeto de erro.

Código	Descrição
ERR_CONNECTION_FAILED	Não foi possível conectar ao endpoint.
ERR_TIMEOUT	Conexão ou teste excedeu o tempo limite.
ERR_INVALID_SERVER	Host malformado ou endereço inacessível.
ERR_NO_RESULTS	Nenhum resultado salvo para a ação solicitada.
ERR_INVALID_PARAMS	Parâmetros obrigatórios ausentes ou inválidos.

 {
  "errorCode": "ERR_CONNECTION_FAILED",
  "errorMessage": "Could not reach iperf.example.com:5201"
} 

FAQ

Por que meu callback não retorna para o Shortcuts?

Certifique-se de que as URLs de callback estejam codificadas em URL e que o esquema seja permitido no seu dispositivo. Evite espaços ou símbolos não escapados em valores de consulta.

Os testes podem ser executados completamente em segundo plano?

Para execução confiável, mantenha o app ativo durante o tempo de execução do teste. Use o agendamento do Shortcuts para acionar execuções em horários específicos.

Qual é o padrão de integração mais seguro?

Use test-server primeiro, depois execute um teste de throughput somente se a verificação do endpoint for bem-sucedida.

Voltar ao Início Baixar App