Proxy API

Importante

Desde a v3.3.1, cada pedido de API de Proxy de Desenvolvimento requer o Authorization: Bearer <token> cabeçalho; os pedidos sem token válido retornam 401 Unauthorized.

O Dev Proxy vem com uma API da Web que permite que você interaja com o proxy programaticamente. A API está disponível no endereço IP e na porta especificados nas definições do proxy.

O Dev Proxy gera um token único para cada instância em execução e armazena-o num ficheiro acessível apenas ao utilizador que iniciou a instância. Obtenha o token usando devproxy status ou devproxy api token. Quando a CI variável de ambiente está definida, use devproxy api token porque o Proxy de Desenvolvimento omite o token do estado e da saída de arranque.

Para usar um token conhecido em vez de um gerado, por exemplo, quando outra ferramenta iniciar o Dev Proxy e chamar a sua API, defina a DEV_PROXY_API_TOKEN variável de ambiente antes de iniciar o Dev Proxy ou passe-a usando essa --env opção. O valor deve ter pelo menos 32 caracteres, sem contar com o preenchimento = final, e pode conter apenas letras ASCII, dígitos e os caracteres -, ., _, ~+, , e /, opcionalmente seguidos de = preenchimento (padding). Cortes do Dev Proxy à volta do espaço em branco. Se o valor não for válido, o Dev Proxy não inicia e sai com um erro. O Dev Proxy ainda armazena o token, por isso devproxy status, devproxy api token, e devproxy stop continua a funcionar.

Inclua o token no Authorization cabeçalho:

Authorization: Bearer <token>

Pedidos sem um token válido retornam 401 Unauthorized. Os pedidos do navegador também devem vir de uma origem indicada na apiAllowedOrigins definição. Outras origens regressam 403 Forbidden.

Operações

A lista a seguir mostra as operações de API disponíveis.

`GET /proxy`

Retorna uma instância de com informações sobre a instância de Proxy de ProxyInfo Desenvolvimento em execução no momento.

Exemplo: obter informações sobre a instância do Proxy de Desenvolvimento em execução no momento

Pedido:

GET http://localhost:8897/proxy
Authorization: Bearer <token>

Resposta:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

`POST /proxy`

Controla a instância do Proxy de Desenvolvimento em execução no momento. Para iniciar e parar a gravação a partir de um script ou pipeline de CI, veja Gravar a partir de scripts e CI.

Exemplo: iniciar a gravação

Pedido:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": true
}

Resposta:

200 OK

{
  "recording": true,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Exemplo: parar a gravação

Pedido:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": false
}

Resposta:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Pára de gravar e gera relatórios

Parar a gravação faz mais do que parar de capturar pedidos. Quando envias {"recording": false} enquanto o Proxy de Desenvolvimento está a gravar, o Proxy de Desenvolvimento passa os pedidos gravados para todos os plugins ativados, pela ordem em que estão listados no ficheiro de configuração. Isto é o mesmo que carregar em s na consola onde o Dev Proxy está a correr. Durante este passo:

Os plugins de relatórios analisam os pedidos gravados e produzem relatórios.
Os repórteres convertem os relatórios em ficheiros. Cada repórter escreve um ficheiro para cada relatório, denominado <plugin>_<reporter>.<extension>, por exemplo, ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> é o nome da instância do plugin que produziu o relatório, e <reporter> é o nome da instância repórter. Se já existir um ficheiro com esse nome, o repórter acrescenta um carimbo temporal, por exemplo, ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md.
Plugins geradores, como o OpenApiSpecGeneratorPlugin, escrevem os ficheiros que geram.

O Proxy de Desenvolvimento escreve estes ficheiros no seu diretório de trabalho atual, que é o diretório a partir do qual iniciou o Proxy de Desenvolvimento.

A API responde depois de todos os plugins terminarem de processar os pedidos gravados. Dependendo dos plugins que usares, por exemplo, plugins que chamam um modelo de linguagem, este passo pode demorar algum tempo, por isso certifica-te de que o teu cliente HTTP não expira demasiado cedo. Quando a resposta chega, os ficheiros de relatório são gravados no disco.

Dev Proxy também regista o progresso do processamento dos pedidos registados:

Mensagem de log	Meaning
`DONE`	Todos os plugins terminaram de processar os pedidos gravados.
`No requests to process`	Um plugin não encontrou pedidos gravados para analisar.
`An error occurred in a plugin`	Um plugin falhou. O Dev Proxy continua com o próximo plugin e regista `DONE` quando todos os plugins terminam.

Se o Dev Proxy não estiver a gravar quando envia {"recording": false}, o Dev Proxy não processa pedidos, não escreve ficheiros e não regista DONE.

Tip

Se parares de usar POST /proxy/stopproxy o Dev Proxy enquanto está a gravar, o Dev Proxy também processa os pedidos gravados antes de sair. No entanto, essa API responde imediatamente, por isso tens de esperar que o processo Dev Proxy saia para saberes que os relatórios estão prontos. Para saber exatamente quando os relatórios estão prontos, pare de gravar primeiro, espere pela resposta e depois pare o Dev Proxy.

Para um script completo que inicia o Dev Proxy, controla a gravação através da API e espera que o Dev Proxy termine, veja Usar Dev Proxy em cenários CI/CD.

`POST /proxy/jwtToken`

Gera um JSON Web Token (JWT).

Pedido:

POST http://localhost:8897/proxy/jwtToken
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Dev Proxy",
  "audiences": [
    "https://myserver.com"
  ],
  "issuer": "dev-proxy",
  "roles": [
    "admin"
  ],
  "scopes": [
    "Post.Read",
    "Post.Write"
  ],
  "claims": {
    "claim1": "value",
    "claim2": "value"
  },
  "validFor": 60
}

Nota

As declarações registradas (por exemplo, iss, , sub, aud, expnbf, iat, ) jtisão adicionadas automaticamente ao token. Se você especificar qualquer uma dessas declarações na solicitação, a API ignorará os valores fornecidos.

Resposta:

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}

`GET /proxy/logs`

Devolve a saída do log do Proxy de Desenvolvimento. Equivalente ao logs comando. Este endpoint está disponível apenas quando o Dev Proxy corre em modo destacado. Caso contrário, a API devolve 404 Not Found.

Parâmetro de consulta	Description	Default
`lines`	Número de linhas para regressar do final do tronco	`50`
`follow`	Quando `true`, transmite novas linhas de registo como eventos enviados pelo servidor	`false`
`since`	Apenas devolve linhas registadas desde a data e hora especificadas. Use uma duração (por exemplo, , , , ) ou uma data e hora ISO 8601 (por exemplo, `2026-01-24T14:00:00` ou `2026-01-24T14:00:00Z`). `1d1h5m30s` Se o carimbo temporal não incluir um deslocamento de fuso horário, o Dev Proxy usa o fuso horário local.	n/a

O since parâmetro filtra as linhas logarítmicas pela sua data e hora completas, tanto ao devolver linhas logarítmicas como ao transmiti-las. O Dev Proxy filtra cada pedido pela hora em que começou, por isso um pedido que começou antes do tempo especificado não é devolvido, mesmo que tenha terminado mais tarde.

Por defeito, a API devolve as linhas de registo como texto simples. Para obter um array JSON de entradas de log, defina o Accept cabeçalho para application/json. Para transmitir linhas de registo como eventos enviados pelo servidor, defina o Accept cabeçalho para text/event-stream ou defina follow para true.

Pedido:

GET http://localhost:8897/proxy/logs?lines=10
Authorization: Bearer <token>

Resposta:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

`POST /proxy/mockrequest`

Levanta um pedido simulado. Equivalente a pressionar w no console onde o Dev Proxy está sendo executado. A API responde após a conclusão do pedido simulado.

Pedido:

POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>

Resposta:

204 No Content

`GET /proxy/rootCertificate?format=crt`

Baixa a chave pública do certificado raiz no formato PEM (Privacy Enhanced Mail) que o Dev Proxy usa para descriptografar solicitações HTTPS. Essa API é útil quando você deseja confiar no certificado raiz em seu host enquanto executa o Proxy de Desenvolvimento em um contêiner do Docker.

Neste momento, o único formato suportado é crt. A API retorna um erro 400 Bad Request se você especificar qualquer outro formato ou não especificar um formato.

Pedido:

GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>

Resposta:

content-type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----

`POST /proxy/stopproxy`

Desliga graciosamente o Dev Proxy. Se o Dev Proxy estiver a gravar, para de gravar e gera relatórios antes de sair. A API responde imediatamente, antes do Dev Proxy terminar de ser desligado.

Pedido:

POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>

Resposta:

202 Accepted

Dev Proxy regressa 202 Accepted assim que começa a desligar. A resposta não significa que o Dev Proxy tenha saído. Durante o encerramento, Proxy:

Deixa de aceitar novos pedidos de proxy. Se o Proxy de Desenvolvimento estiver registado como proxy do sistema, restaura as definições anteriores do proxy. O Dev Proxy espera até cinco segundos para que as ligações abertas se fechem, e depois fecha quaisquer ligações restantes.
Para de gravar, se a gravação estiver ativada, e executa os plugins de relatórios nos pedidos gravados, tal como quando deixas de gravar tu próprio. Quando os plugins terminam, o Dev Proxy escreve os relatórios e registos DONE.
Remove a informação da instância, por devproxy stop isso devproxy status deixa de a listar.
Saídas com código 0de saída.

O Dev Proxy não remove o seu certificado raiz da loja de certificados de confiança ao desligar. Para remover o certificado, use o certificado remover.

O desligamento normalmente demora alguns segundos. Pode demorar mais tempo quando plugins de reporte processam uma gravação grande. Depois de iniciar o encerramento, a API já não está acessível, por isso não consultes a API para verificar se o Proxy de Desenvolvimento saiu. Em vez disso, use uma destas opções:

Espere que o ID do processo (PID) que devproxy --detach imprime saia.
Execute devproxy status --pid <pid> até que devolva código 1de saída, o que significa que a instância já não está a correr. Para mais informações, consulte o estado.
Se estivesses a gravar, verifica o registo do Dev Proxy para a DONE mensagem, que o Dev Proxy regista depois de terminarem os plugins de reporte. Para um exemplo, veja Usar Proxy de Desenvolvimento em cenários de CI/CD.

Por exemplo, esperar que uma instância Dev Proxy destacada saia no Linux ou macOS:

# DEVPROXY_PID is the PID that devproxy --detach printed
# TOKEN is the API token from devproxy api token
curl -X POST http://localhost:8897/proxy/stopproxy -H "Authorization: Bearer $TOKEN"

while ./devproxy/devproxy status --pid $DEVPROXY_PID > /dev/null 2>&1; do
  sleep 1
done

Evite terminar o processo Dev Proxy de forma forçada, por exemplo, usando kill -9. Quando terminas o processo desta forma, o Dev Proxy não limpa a gravação nem restaura as definições do proxy do sistema. Para parar o Dev Proxy na linha de comandos, use stop, que chama esta API e espera até 10 segundos para o Dev Proxy sair.

Modelos

`ProxyInfo`

Informações sobre a instância do Dev Proxy em execução no momento.

Propriedade	Tipo	Description
`recording`	`boolean`	Se o proxy está atualmente gravando solicitações
`configFile`	`string`	Caminho para o arquivo de configuração que o Proxy de Desenvolvimento está usando (somente leitura)

`JwtOptions`

Opções para gerar um token JWT.

Propriedade	Tipo	Description
`name`	`string`	O nome do usuário para o qual criar o token
`audiences`	`string[]`	As audiências para as quais criar o token
`issuer`	`string`	O emissor do token
`roles`	`string[]`	Uma declaração de função a ser adicionada ao token
`scopes`	`string[]`	Uma declaração de escopo para adicionar ao token
`claims`	`KeyValuePair`	Declarações para adicionar ao token
`validFor`	`number`	A duração (em minutos) para a qual o token é válido
`signingKey`	`string`	A chave a ser usada para assinar o token. Deve ter pelo menos 32 caracteres. Se não for especificado, usa uma chave gerada aleatoriamente.

`JwtInfo`

Informações sobre um token JWT.

Propriedade	Tipo	Description
`token`	`string`	O token JWT

Ver também

Comentários

Esta página foi útil?

Última atualização a 2026-11-05

Proxy API

Operações

GET /proxy

Exemplo: obter informações sobre a instância do Proxy de Desenvolvimento em execução no momento

POST /proxy

Exemplo: iniciar a gravação

Exemplo: parar a gravação

Pára de gravar e gera relatórios

POST /proxy/jwtToken

GET /proxy/logs

POST /proxy/mockrequest

GET /proxy/rootCertificate?format=crt

POST /proxy/stopproxy

Modelos

ProxyInfo

JwtOptions

JwtInfo

Ver também

Comentários

Recursos adicionais

`GET /proxy`

`POST /proxy`

`POST /proxy/jwtToken`

`GET /proxy/logs`

`POST /proxy/mockrequest`

`GET /proxy/rootCertificate?format=crt`

`POST /proxy/stopproxy`

`ProxyInfo`

`JwtOptions`

`JwtInfo`