Usar o proxy de desenvolvimento em cenários de CI/CD

Visão geral
Objetivo: Integrar o Proxy de Desenvolvimento em CI/CD
Tempo: 30 minutos
Plugins: Vários
Pré-requisitos:Configurar o Proxy de Desenvolvimento

Usar o Proxy de Desenvolvimento em cenários de CI/CD é uma ótima maneira de testar seus aplicativos em um ambiente controlado. Ao combinar o Proxy de Desenvolvimento com testes que geram solicitações de API em seu aplicativo, você pode abranger uma ampla gama de cenários: desde garantir que seu aplicativo não use APIs de sombra ou não de produção até verificar se ele usa permissões mínimas do Microsoft Graph. Embora as etapas exatas de configuração variem dependendo do seu sistema de CI/CD, aqui estão alguns princípios gerais que você deve seguir.

Na maioria dos casos, o executor não tem o Proxy de Desenvolvimento instalado. Portanto, antes de usar o Proxy de Desenvolvimento, você precisa instalá-lo. As etapas de instalação dependem do sistema operacional usado pelo executor.

Ao instalar o Proxy de Desenvolvimento em uma configuração de CI/CD, você normalmente deseja fixar a versão do Proxy de Desenvolvimento que você instala. Fixar a versão garante que o pipeline use a mesma versão do Proxy de Desenvolvimento sempre que você executá-la. As etapas exatas para fixar uma versão dependem do sistema operacional do executor. Aqui está um exemplo de como você pode fixar a versão do Dev Proxy em um runner baseado em Linux:

# install Dev Proxy v1.0.0
bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)" -- v1.0.0

Flags de CI recomendados

Em um pipeline de CI/CD, inicie o Dev Proxy com o mesmo conjunto de opções sempre, para que ele seja executado em segundo plano, não altere a configuração do executor e não aguarde a entrada do usuário. Recomendamos as seguintes opções:

Além disso, antes de iniciar o Dev Proxy, defina a variável de ambiente DEV_PROXY_API_TOKEN como um token gerado. Dessa forma, você sabe o token de que precisa para chamar a API do Dev Proxy sem precisar recuperá-lo do Dev Proxy. O token deve ter pelo menos 32 caracteres. Para obter os requisitos completos, consulte a API de Proxy.

# generate an API token for this run
export DEV_PROXY_API_TOKEN=$(openssl rand -hex 32)

Os exemplos neste artigo utilizam estas opções e a variável de ambiente DEV_PROXY_API_TOKEN.

Obter uma configuração para gravar chamadas à API

Se você quiser gravar quais APIs seu aplicativo chama durante uma execução de CI, não será necessário criar uma configuração do zero. Baixe a api-inventory predefinição da galeria de exemplos do Dev Proxy usando o config get comando:

./devproxy/devproxy config get api-inventory

A predefinição combina UrlDiscoveryPlugin e ExecutionSummaryPlugin com repórteres e não registra o Dev Proxy como o proxy do sistema. Ao iniciar o Dev Proxy, passe o arquivo de configuração da predefinição, substitua as URLs para observar com as APIs que seu aplicativo chama e use os sinalizadores de CI recomendados:

./devproxy/devproxy --config-file "~dataFolder/configs/api-inventory/.devproxy/devproxyrc.json" --urls-to-watch "https://api.contoso.com/*" --detach --as-system-proxy false --install-cert false --no-first-run --no-watch

Para obter mais informações sobre predefinições, consulte Usar configurações predefinidas.

Iniciar Proxy de Desenvolvimento

Depois de instalar o Proxy de Desenvolvimento, você precisa iniciá-lo. Ao iniciar o Dev Proxy em um pipeline de CI/CD, é importante executá-lo em segundo plano. Caso contrário, o pipeline será bloqueado até que você interrompa o Proxy de Desenvolvimento.

Inicie o Proxy de Desenvolvimento em segundo plano usando os sinalizadores de CI recomendados:

# start Dev Proxy in detached mode
./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch

O Proxy de Desenvolvimento imprime informações de inicialização, incluindo a ID do processo (PID), a URL do Proxy, a URL da API e o caminho do arquivo de log:

Dev Proxy started in background.

  PID:       6456
  Proxy URL: http://127.0.0.1:8000
  API URL:   http://127.0.0.1:8897
  Log file:  /home/runner/.local/dev-proxy/logs/devproxy-6456-2026-03-05.log

Para saída legível pelo computador, use --output json para obter JSONL:

./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch --output json

{"type":"result","data":{"pid":6456,"proxyUrl":"http://127.0.0.1:8000","apiUrl":"http://127.0.0.1:8897","logFile":"/home/runner/.local/dev-proxy/logs/devproxy-6456-2026-03-05.log"},"timestamp":"2026-03-05T14:22:42.0000000Z"}

Como alternativa, se estiver usando um executor baseado em Linux, você poderá iniciar o Dev Proxy em segundo plano usando o controle de trabalho do shell.

# start Dev Proxy in the background
./devproxy/devproxy --as-system-proxy false --install-cert false --no-first-run --no-watch > devproxy.log 2>&1 &

Aguardar até que o Proxy de Desenvolvimento seja iniciado

Quando você inicia o Dev Proxy em segundo plano, o script continua imediatamente. No entanto, o Proxy de Desenvolvimento precisa de algum tempo para começar. Para garantir que o Dev Proxy esteja pronto antes de iniciar a emissão de solicitações, aguarde até que sua API responda a uma solicitação GET /proxy:

api_url=http://127.0.0.1:8897

echo "Waiting for Dev Proxy to start..."
until curl -sf -o /dev/null "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"; do
  sleep 1
done

# the rest of your script

A sondagem da API funciona independentemente da porta em que o Proxy de Desenvolvimento escuta, inclusive quando você usa --port 0.

Confiar no certificado raiz do Proxy de Desenvolvimento

Depois que o Dev Proxy for iniciado, você precisará confiar no certificado raiz do Dev Proxy antes de enviar solicitações, pois o Dev Proxy usa um certificado raiz autoassinado.

Dependendo de suas permissões, talvez seja necessário criar a pasta ~/.config/dev-proxy/rootCert, na qual o Dev Proxy armazena seu certificado raiz, antes de iniciar o Dev Proxy:

# ensure the rootCert folder
echo "Ensuring the Dev Proxy rootCert folder"
mkdir -p ~/.config/dev-proxy/rootCert

Para obter a chave pública do certificado raiz, baixe-a usando a Dev Proxy API. Se você estiver usando um executor baseado em Linux, poderá instalar o certificado copiando-o para o repositório de certificados de AC confiáveis do sistema:

# download the Dev Proxy's Root Certificate
echo "Downloading the Dev Proxy's Root Certificate"
curl -sf -o dev-proxy-ca.crt "$api_url/proxy/rootCertificate?format=crt" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"

# install root certificate
echo "Installing the Dev Proxy's Root Certificate"
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/

# update CA certificates
echo "Updating the CA certificates"
sudo update-ca-certificates

Configurar variáveis de ambiente de proxy

Muitos aplicativos e bibliotecas usam as http_proxy variáveis de ambiente e https_proxy de ambiente para determinar o servidor proxy a ser usado para solicitações HTTP e HTTPS. Como você inicia o Dev Proxy com --as-system-proxy false, é necessário definir essas variáveis de ambiente para apontar para a instância do Dev Proxy para garantir que seu aplicativo use o Dev Proxy.

export http_proxy=http://127.0.0.1:8000
export https_proxy=http://127.0.0.1:8000

Controlar o Proxy de Desenvolvimento

Quando você executa o Proxy de Desenvolvimento em um pipeline de CI/CD, não é possível controlá-lo interativamente. Em vez disso, você pode controlá-lo enviando solicitações para a API de Proxy de Desenvolvimento.

Todas as solicitações da API de Proxy de Desenvolvimento exigem um token Bearer no cabeçalho Authorization. Se você definir a variável de DEV_PROXY_API_TOKEN ambiente conforme recomendado, use seu valor. Caso contrário, como o Proxy de Desenvolvimento não imprime o token na inicialização quando a variável de ambiente CI estiver definida, recupere-o usando o comando api token:

export DEV_PROXY_API_TOKEN=$(./devproxy/devproxy api token)

Se você quiser analisar as solicitações de API emitidas pelo seu aplicativo, poderá enviar uma POST solicitação ao /proxy ponto de extremidade para iniciar a gravação:

curl -sf -X POST "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN" -H "Content-Type: application/json" -d '{"recording": true}'

Para interromper a gravação, envie uma POST solicitação para o /proxy endpoint com recording definido como false:

curl -sf -X POST "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN" -H "Content-Type: application/json" -d '{"recording": false}'

Para interromper o Dev Proxy, você pode enviar uma POST solicitação para o /proxy/stopproxy endpoint:

curl -sf -X POST "$api_url/proxy/stopproxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"

Depois que você interrompe o processo do Proxy de Desenvolvimento, talvez sejam necessários alguns instantes para que ele seja totalmente fechado. Para garantir que o Dev Proxy tenha terminado, aguarde que seu arquivo de log, que o Dev Proxy imprime quando ele começa no modo desacoplado, contenha uma das mensagens de conclusão, por exemplo:

echo "Waiting for Dev Proxy to complete..."
while true; do
  if grep -q -e "DONE" -e "No requests to process" -e "An error occurred in a plugin" "$log_file"; then
    break
  fi
  sleep 1
done

Quando todos os plug-ins de gravação terminam de ser executados, o Dev Proxy imprime a mensagem DONE na saída. Se não houver solicitações para processar, o Proxy de Desenvolvimento imprimirá a mensagem No requests to process. Se ocorreu um erro em um plug-in, o Proxy de Desenvolvimento imprime a mensagem An error occurred in a plugin. Ao ver qualquer uma dessas mensagens, você pode ter certeza de que o Proxy de Desenvolvimento terminou de processar as solicitações gravadas.

Exemplo de script de início

Aqui está um exemplo de um script bash que você pode usar para iniciar o Dev Proxy em um pipeline de CI/CD. O script usa os sinalizadores de CI recomendados, lê a URL do proxy, a URL da API e o caminho do arquivo de log da saída JSON, aguarda até que a API do Dev Proxy responda e confia no certificado raiz baixado da API. Ele usa jq para analisar a saída JSON.

echo "Generating the Dev Proxy API token"
export DEV_PROXY_API_TOKEN=$(openssl rand -hex 32)

echo "Ensuring Dev Proxy rootCert folder"
mkdir -p ~/.config/dev-proxy/rootCert

echo "Starting Dev Proxy"
result=$(./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch --output json | jq -c 'select(.type == "result")')
if [ -z "$result" ]; then
  echo "Failed to start Dev Proxy"
  exit 1
fi

proxy_url=$(echo "$result" | jq -r '.data.proxyUrl')
api_url=$(echo "$result" | jq -r '.data.apiUrl')
log_file=$(echo "$result" | jq -r '.data.logFile')

echo "Waiting for Dev Proxy to start..."
until curl -sf -o /dev/null "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"; do
  sleep 1
done

echo "Downloading the Dev Proxy's Root Certificate"
curl -sf -o dev-proxy-ca.crt "$api_url/proxy/rootCertificate?format=crt" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"

echo "Installing the Dev Proxy's Root Certificate"
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/

echo "Updating the CA certificates"
sudo update-ca-certificates

echo "Set proxy variables"
export http_proxy=$proxy_url
export https_proxy=$proxy_url

Consulte também

• Usar o Dev Proxy com o GitHub Actions
• Usar o Proxy de Desenvolvimento com o Azure Pipelines
• API de proxy de desenvolvimento
• Registrar e exportar atividade de proxy
• Usar configurações predefinidas