Proxy API

Important

Como v3.3.1, cada solicitação de API de Proxy de Desenvolvimento requer o Authorization: Bearer <token> cabeçalho; solicitações sem um retorno 401 Unauthorizedde token válido.

O Dev Proxy vem com uma API Web que permite interagir com o proxy programaticamente. A API está disponível no endereço IP e na porta especificadas nas configurações de proxy.

O Proxy de Desenvolvimento gera um token exclusivo para cada instância em execução e o armazena em um arquivo acessível apenas ao usuário que iniciou a instância. Obter o token usando devproxy status ou devproxy api token. Quando a CI variável de ambiente estiver definida, use devproxy api token porque o Proxy de Desenvolvimento omite o token do status e da saída de inicialização.

Para usar um token conhecido em vez de um gerado, por exemplo, quando outra ferramenta iniciar o Proxy de Desenvolvimento e chamar sua API, defina a variável de ambiente antes de iniciar o DEV_PROXY_API_TOKEN Proxy de Desenvolvimento ou passe-o usando a opção --env . O valor deve ter pelo menos 32 caracteres, sem contar o preenchimento à direita = e pode conter apenas letras ASCII, dígitos e os caracteres-, ., , _, ~e+/, opcionalmente, seguidos pelo = preenchimento. O Proxy de Desenvolvimento corta o espaço em branco ao redor. Se o valor não for válido, o Proxy de Desenvolvimento não será iniciado e sairá com um erro. O Proxy de Desenvolvimento ainda armazena o token, portanto devproxy status, devproxy api tokene devproxy stop continua funcionando.

Inclua o token no Authorization cabeçalho:

Authorization: Bearer <token>

Solicitações sem um retorno 401 Unauthorizedde token válido. As solicitações do navegador também devem vir de uma origem listada na apiAllowedOrigins configuração. Outras origens retornam 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 do ProxyInfo Dev Proxy em execução no momento.

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

Solicitação:

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 de um script ou pipeline de CI, consulte Registro de scripts e CI.

Exemplo: iniciar gravação

Solicitação:

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

Solicitação:

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"
}

Parar gravação e gerar relatórios

Parar a gravação faz mais do que parar de capturar solicitações. Quando você envia {"recording": false} enquanto o Proxy de Desenvolvimento está gravando, o Proxy de Desenvolvimento passa as solicitações gravadas para todos os plug-ins habilitados, na ordem em que estão listados no arquivo de configuração. Isso é o mesmo que pressionar s no console em que o Proxy de Desenvolvimento está em execução. Durante esta etapa:

Os plug-ins de relatórios analisam as solicitações gravadas e produzem relatórios.
Os repórteres convertem os relatórios em arquivos. Cada repórter grava um arquivo para cada relatório, nomeado <plugin>_<reporter>.<extension>, por exemplo, ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> é o nome da instância do plug-in que produziu o relatório e <reporter> é o nome da instância do repórter. Se já existir um arquivo com esse nome, o repórter acrescentará um carimbo de data/hora, por exemplo, ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md.
Os plug-ins do gerador, como o OpenApiSpecGeneratorPlugin, gravam os arquivos que geram.

O Proxy de Desenvolvimento grava esses arquivos em seu diretório de trabalho atual, que é o diretório do qual você iniciou o Proxy de Desenvolvimento.

A API responde depois que todos os plug-ins terminam de processar as solicitações registradas. Dependendo dos plug-ins que você usa, por exemplo, plug-ins que chamam um modelo de idioma, essa etapa pode demorar um pouco, portanto, verifique se o cliente HTTP não atingiu o tempo limite muito cedo. Quando a resposta chega, os arquivos de relatório são gravados em disco.

O Proxy de Desenvolvimento também registra o progresso do processamento das solicitações registradas:

Mensagem de log	Meaning
`DONE`	Todos os plug-ins terminaram de processar as solicitações gravadas.
`No requests to process`	Um plug-in não encontrou nenhuma solicitação gravada para analisar.
`An error occurred in a plugin`	Falha no plug-in. O Proxy de Desenvolvimento continua com o próximo plug-in e os logs `DONE` quando todos os plug-ins são concluídos.

Se o Proxy de Desenvolvimento não estiver gravando quando você enviar {"recording": false}, o Proxy de Desenvolvimento não processará nenhuma solicitação, não gravará nenhum arquivo e não registrará em log DONE.

Dica

Se você parar o Proxy de Desenvolvimento usando POST /proxy/stopproxy durante a gravação, o Proxy de Desenvolvimento também processará as solicitações gravadas antes de sair. No entanto, essa API responde imediatamente, portanto, você precisa aguardar a saída do processo de Proxy de Desenvolvimento para saber que os relatórios estão prontos. Para saber exatamente quando os relatórios estão prontos, pare de gravar primeiro, aguarde a resposta e, em seguida, interrompa o Proxy de Desenvolvimento.

Para obter um script completo que inicia o Proxy de Desenvolvimento, controla a gravação por meio da API e aguarda a conclusão do Proxy de Desenvolvimento, consulte Usar Proxy de Desenvolvimento em cenários de CI/CD.

`POST /proxy/jwtToken`

Gera um JWT (Token Web JSON).

Solicitação:

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
}

Observação

As declarações registradas (por exemplo, iss, , sub, aud, exp, nbf, 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`

Retorna a saída do log do Proxy de Desenvolvimento. Equivalente ao logs comando. Esse ponto de extremidade só está disponível quando o Proxy de Desenvolvimento é executado no modo desanexado. Caso contrário, a API retornará 404 Not Found.

Parâmetro de consulta	Descrição	Padrão
`lines`	Número de linhas a serem retornadas do final do log	`50`
`follow`	Quando `true`, transmite novas linhas de log como eventos enviados pelo servidor	`false`
`since`	Retorna apenas as linhas registradas desde a data e hora especificadas. Use uma duração (por exemplo, , , , ) `1d`ou uma data e hora iso 8601 (por exemplo, `2026-01-24T14:00:00` ou `2026-01-24T14:00:00Z`). `1h5m30s` Se o carimbo de data/hora não incluir um deslocamento de fuso horário, o Proxy de Desenvolvimento usará o fuso horário local.	n/a

O since parâmetro filtra as linhas de log pela data e hora completas, tanto ao retornar linhas de log quanto ao transmiti-las. O Proxy de Desenvolvimento filtra cada solicitação quando ela é iniciada, portanto, uma solicitação iniciada antes da hora especificada não é retornada, mesmo que seja concluída posteriormente.

Por padrão, a API retorna as linhas de log como texto sem formatação. Para obter uma matriz JSON de entradas de log, defina o Accept cabeçalho como application/json. Para transmitir linhas de log como eventos enviados pelo servidor, defina o Accept cabeçalho como text/event-stream ou definido follow como true.

Solicitação:

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`

Gera uma solicitação simulada. Equivalente a pressionar w no console em que o Dev Proxy está sendo executado. A API responde após a conclusão da solicitação simulada.

Solicitação:

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 (Email Avançado de Privacidade) que o Proxy de Desenvolvimento 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 com suporte é crt. A API retornará um erro de 400 Solicitações Incorretas se você especificar qualquer outro formato ou não especificar um formato.

Solicitação:

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 normalmente o Dev Proxy. Se o Proxy de Desenvolvimento estiver gravando, ele interromperá a gravação e gerará relatórios antes de sair. A API responde imediatamente, antes que o Proxy de Desenvolvimento termine de desligar.

Solicitação:

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

Resposta:

202 Accepted

O Proxy de Desenvolvimento retorna 202 Accepted assim que ele começa a desligar. A resposta não significa que o Proxy de Desenvolvimento foi encerrado. Durante o desligamento, Proxy de Desenvolvimento:

Para de aceitar novas solicitações de proxy. Se o Proxy de Desenvolvimento for registrado como o proxy do sistema, ele restaurará as configurações de proxy do sistema anteriores. O Proxy de Desenvolvimento aguarda até cinco segundos para que as conexões abertas fechem e feche as conexões restantes.
Interrompe a gravação, se a gravação estiver ativada e executa os plug-ins de relatório nas solicitações gravadas, da mesma forma que quando você para de gravar por conta própria. Quando os plug-ins são concluídos, o Proxy de Desenvolvimento grava os relatórios e os logs DONE.
Remove as informações da instância e, portanto devproxy statusdevproxy stop , não as lista mais.
Sai com o código 0de saída.

O Proxy de Desenvolvimento não remove seu certificado raiz do repositório de certificados confiável no desligamento. Para remover o certificado, use a remoção do certificado.

O desligamento normalmente leva alguns segundos. Pode levar mais tempo quando os plug-ins de relatórios processam uma gravação grande. Depois que o desligamento for iniciado, a API não poderá mais ser acessada, portanto, não faça a sondagem da API para verificar se o Proxy de Desenvolvimento foi encerrado. Em vez disso, use uma destas opções:

Aguarde a ID do processo (PID) que devproxy --detach imprime para sair.
Execute devproxy status --pid <pid> até retornar o código 1de saída, o que significa que a instância não está mais em execução. Para obter mais informações, consulte o status.
Se você estava gravando, verifique o log do Proxy de Desenvolvimento para a DONE mensagem, que o Proxy de Desenvolvimento registra após a conclusão dos plug-ins de relatório. Para obter um exemplo, consulte Usar o Proxy de Desenvolvimento em cenários de CI/CD.

Por exemplo, para aguardar a saída de uma instância de Proxy de Desenvolvimento desanexada no Linux ou no 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 encerrar o processo de Proxy de Desenvolvimento com força, por exemplo, usando kill -9. Quando você encerra o processo dessa forma, o Proxy de Desenvolvimento não libera as configurações de proxy do sistema de gravação ou restauração. Para interromper o Proxy de Desenvolvimento da linha de comando, use stop, que chama essa API e aguarda até 10 segundos para o Proxy de Desenvolvimento sair.

Modelos

`ProxyInfo`

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

Propriedade	Tipo	Descrição
`recording`	`boolean`	Se o proxy está registrando solicitações no momento
`configFile`	`string`	Caminho para o arquivo de configuração que o Dev Proxy está usando (somente leitura)

`JwtOptions`

Opções para gerar um token JWT.

Propriedade	Tipo	Descrição
`name`	`string`	O nome do usuário para o qual criar o token
`audiences`	`string[]`	Os públicos-alvo para os 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 a ser adicionada ao token
`claims`	`KeyValuePair`	Declarações a serem adicionadas ao token
`validFor`	`number`	A duração (em minutos) pela 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	Descrição
`token`	`string`	O token JWT

Consulte também

Comentários

Esta página foi útil?

Última atualização em 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 gravação

Exemplo: parar a gravação

Parar gravação e gerar relatórios

POST /proxy/jwtToken

GET /proxy/logs

POST /proxy/mockrequest

GET /proxy/rootCertificate?format=crt

POST /proxy/stopproxy

Modelos

ProxyInfo

JwtOptions

JwtInfo

Consulte 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`