O Que É URL Encoding? Percent-Encoding Explicado
O URL encoding (percent-encoding) substitui caracteres que são inseguros em uma URL por um sinal de porcentagem seguido do valor hex do seu byte.
URLs só podem conter com segurança um conjunto limitado de caracteres, então qualquer coisa fora desse conjunto - espaços, barras, e comerciais, letras não-ASCII - precisa ser escapada. O URL encoding faz isso substituindo cada byte inseguro por um sinal de porcentagem e dois dígitos hex. Importa em CI sempre que você constrói URLs a partir de variáveis ou embute tokens e credenciais nelas.
O que é URL encoding
O URL encoding, também chamado de percent-encoding, representa um caractere inseguro como um sinal de porcentagem seguido do valor hexadecimal de dois dígitos do seu byte. Um espaço vira %20, um e comercial vira %26. Isso mantém a URL parseável porque caracteres reservados deixam de colidir com a própria sintaxe da URL.
Caracteres reservados versus não reservados
Alguns caracteres - letras, dígitos e alguns símbolos - são seguros para usar literalmente. Outros são reservados porque têm significado em uma URL, como a barra que separa segmentos de path ou o ponto de interrogação que inicia uma query. Quando você quer um deles como dado em vez de estrutura, você o codifica.
Codificando parâmetros de query
Valores de query string frequentemente contêm caracteres que de outra forma quebrariam a URL - espaços, sinais de igual ou outro e comercial. Codificar cada valor garante que o servidor separe os parâmetros corretamente em vez de interpretar errado onde um valor termina e o próximo começa.
URL encoding em CI
Em pipelines você constrói URLs a partir de variáveis o tempo todo - chamando uma API com um termo de busca, ou embutindo um token em uma URL de remote do git. Um token ou senha com um caractere especial como uma barra ou arroba precisa ter URL encoding, ou vai corromper a URL e a requisição vai falhar.
# Encode a value before putting it in a URL in CI
steps:
- run: |
enc=$(jq -rn --arg v "$QUERY" '$v|@uri')
curl "https://api.example.com/search?q=$enc"Por que morde em pipelines
Uma falha comum é um secret de CI como um token contendo um caractere especial que silenciosamente quebra uma URL autenticada. Fazer URL encoding da credencial antes de embuti-la - ou usar um header em vez disso - evita um confuso erro 401 ou de requisição malformada.
Principais conclusões
- O URL encoding substitui caracteres inseguros por um sinal de porcentagem e o valor hex de dois dígitos do seu byte.
- Caracteres reservados têm significado na URL, então você os codifica quando são dados, não estrutura.
- Em CI, tokens e valores de query com caracteres especiais precisam ter URL encoding ou corrompem a requisição.